From a7fc7084b0982d765ab0a56e687dcd49c3670d6f Mon Sep 17 00:00:00 2001
From: Hannes Vogt <vogt@hey.com>
Date: Wed, 5 Aug 2026 15:30:09 +0200
Subject: [PATCH] shared: dimensions as types (Part I extracted, scoped to the
 base)

---
 content/index.md                              |   1 +
 .../dimension-generic-fields.md               | 116 +++--------
 content/shared/dimensions-as-types.md         | 192 ++++++++++++++++++
 3 files changed, 220 insertions(+), 89 deletions(-)
 create mode 100644 content/shared/dimensions-as-types.md

diff --git a/content/index.md b/content/index.md
index 13d9474..0849025 100644
--- a/content/index.md
+++ b/content/index.md
@@ -15,6 +15,7 @@ index current. (Keep entries and their keywords in sync with each document's `ta
 Proposals the group broadly agrees are implementation-ready.
 
 - [[shared/external-memory-for-dace-arrays/external-memory-for-dace-arrays|External workspace memory for DaCe temporary arrays]] — keywords: dace, backend, gpu, memory, temporary-arrays, workspace, cuda, hip, mempool, persistent, external, allocation, icon4py, performance
+- [[shared/dimensions-as-types|Dimensions as types]] — keywords: type-system, dimensions, type-checking, mypy, mypy-plugin, nominal-types, metaclass, migration, frontend, foast, extension-point
 
 <!-- Entry format:
 - [[shared/<slug>|Title]] — keywords: keyword1, keyword2, keyword3
diff --git a/content/personal/havogt/dimension-generic-fields/dimension-generic-fields.md b/content/personal/havogt/dimension-generic-fields/dimension-generic-fields.md
index 8ad41fe..82d9e31 100644
--- a/content/personal/havogt/dimension-generic-fields/dimension-generic-fields.md
+++ b/content/personal/havogt/dimension-generic-fields/dimension-generic-fields.md
@@ -13,6 +13,11 @@ status: draft
 > constructor, and **dimension variables** (`TypeVar`/`TypeVarTuple` over
 > dimensions) so field operators can be generic in their dimensions.
 
+> **Part I has been extracted** into [[shared/dimensions-as-types|Dimensions as
+> types]]. §3 below is now a stub keeping only what Parts II and III refer back
+> to; the requirements, rejected alternatives, migration plan and risks of the
+> base live in the shared document. Parts II and III stay here.
+
 > **Prototypes**: the self-contained static-expressibility prototype (mypy 1.19,
 > no plugin) is vendored alongside this document in
 > [`dimension-generic-fields/`](dimension-generic-fields/) (see §8.A). The
@@ -42,8 +47,8 @@ status: draft
   expressibility, mypy-verified) and the `ts.DimensionVar`/`ts.DimsVar`
   extension of the type system (unit-tested, inert, on the gt4py branch).
 - **Outcome**: a staged design proposal; decisions should be recorded as ADRs
-  once reviewed (suggested: `0024-Dimensions-As-Types.md`,
-  `0025-Dimension-Generic-Operators.md`).
+  once reviewed (suggested: `0027-Dimensions-As-Types.md`,
+  `0028-Dimension-Generic-Operators.md`).
 
 ## 1. Goals
 
@@ -115,42 +120,14 @@ redesign of §3; with today's instance-dimensions it indeed is not.
 
 ## 3. Part I — dimensions as types
 
-### 3.1 Requirements
-
-1. `Field[Dims[I], float64]` must be a valid generic annotation for plain
-   mypy; distinct dimensions must be distinguishable (nominal).
-2. Everything dimension instances do today at the *value* level must keep
-   working on the new dimension objects: `I + 1` / `I - 1` (implicit cartesian
-   offsets), `I(5)` (`NamedIndex`), `I == J` / ordering, `I < 5` etc. (domain
-   construction), dict keys (`domain={I: ...}`, offset providers), `str(I)`,
-   `.value`/`.kind`, pickling.
-3. TypeVars over dimensions must be possible (`TypeVar("D", bound=Dimension)`,
-   `TypeVarTuple`), enabling Part III; `Staggered[I]` must be a type-level
-   function (Part II).
-4. Incremental migration: old-style `Dimension("I")` instances and new-style
-   dimension classes must coexist in one program.
-
-### 3.2 Considered designs
-
-- **(a) Dimension = class, value behavior via metaclass** — **chosen**, §3.3.
-- **(b) Status quo + mypy plugin**: rejected as a *target* (4-dim limit,
-  name-keyed global confusion, no TypeVars, plugin maintenance; the plugin's
-  dtype "blurring" also erases exactly what dtype generics need). The plugin
-  remains as a compatibility shim for old-style dims during migration.
-- **(c) `Dims[Literal["I"], ...]`**: rejected — loses `kind`, stringly-typed,
-  no `Staggered[...]`, unreadable diagnostics.
-- **(d) per-dimension synthesized types via a factory**
-  (`I = dimension("I")`): rejected — a dynamically created class is opaque to
-  static checkers; the *declaration* must be a class statement for mypy to
-  see a nominal type.
-
-### 3.3 Design: `class I(Dimension)` with `DimensionMeta`
-
-Prototype: [`dimension-generic-fields/typed_dimensions.py`](dimension-generic-fields/typed_dimensions.py).
+**Extracted** to [[shared/dimensions-as-types|Dimensions as types]], together
+with its requirements, the rejected alternatives, the migration plan and the
+mypy-plugin removal it enables. Repeated here only insofar as Parts II and III
+below refer back to it:
 
 ```python
 class DimensionBase(metaclass=DimensionMeta):  # root: anything usable in Dims[...]
-    value: ClassVar[str]  # defaults to the class name (__init_subclass__)
+    value: ClassVar[str]
     kind: ClassVar[DimensionKind] = DimensionKind.HORIZONTAL
 
 
@@ -158,55 +135,17 @@ class Dimension(DimensionBase): ...  # base of user-declared dimensions
 
 
 class I(Dimension): ...
-
-
 class K(Dimension, kind=DimensionKind.VERTICAL): ...
 ```
 
-(The two-level root/user split exists for staggering: `Staggered[...]`
-subclasses the root but not `Dimension`, see §4.2.)
-
-- The **class object itself is the value** — there is no instance level;
-  `Dimension.__new__` raises. Wherever today a `Dimension` instance flows
-  (domains, offset providers, `FieldType.dims`, IRs), the class object flows
-  instead.
-- `DimensionMeta` carries the value-level API (`__add__`/`__sub__` building
-  connectivities, `__call__` → `NamedIndex`, comparison operators → `Domain`,
-  `__repr__`) — binary operators on a class object dispatch through its
-  metaclass, so this is the only place they can live.
-- **Name-based `__eq__`/`__hash__` on the metaclass** reproduces today's
-  `Dimension.__eq__` (compares `.value` only) and makes new-style classes
-  compare/hash equal to old-style instances of the same name. This is the
-  migration mechanism: `Domain` dicts, offset-provider lookups and
-  `FieldType.dims` comparisons work across both styles, so subsystems (and
-  downstream code like icon4py) can migrate dimension-by-dimension.
-- **mypy quirk (important, prototype-verified)**: mypy rejects generic
-  self-types on metaclass methods at the *definition site* ("Self argument
-  missing for a non-static method") but applies them correctly at every
-  *call site*. The metaclass operator overloads therefore carry
-  `# type: ignore[misc]` on their signatures; `static_checks.py` pins the
-  call-site behavior so a mypy upgrade that changes this is caught
-  immediately. (If this ever regresses, the fallback is free functions
-  `shift(I, 1)` / `half(I)` with identical overload structure — only the
-  notation, not the design, depends on the quirk.)
-
-Migration sketch (each step landable separately):
-
-1. Land `DimensionMeta`/class-style `Dimension` in `common` with name-based
-   interop; keep `Dimension("I")` working (factory returning an old-style
-   instance, later a synthesized class).
-2. Move GT4Py-internal dimension definitions (tests, docs, fbuiltins) to
-   class style; add `typing_tests` coverage; drop the `_DimA`–`_DimD` and
-   `fixup_dims_*` machinery from the mypy plugin for class-style dims.
-3. Deprecate instance-style definitions; eventually `Dimension("I")` emits a
-   warning.
-
-Open points: eve serialization of dimension *classes* inside IR nodes
-(currently dataclass instances serialize structurally; classes need a
-`value`/`kind`-based representation — straightforward since both are class
-attributes), and `typing` internals caching subscriptions by
-hash-equal-but-distinct dims (only relevant for same-named distinct dims,
-which we reject anyway).
+- The **class object is the value**, and `DimensionMeta` carries the value-level
+  API (`__add__`/`__sub__`, `__call__` → `NamedIndex`, comparisons → `Domain`) —
+  which is where the staggering overloads of §4.2 attach.
+- The **two-level root/user split** is the extension point Parts II and III use:
+  `Staggered[...]` (§4.2) subclasses `DimensionBase` but not `Dimension`, and
+  every generic dimension TypeVar (§5.1) is bound to the root.
+- Dimensions are **nominal**, which is what lets the overload *argument matching*
+  of §4.1 discriminate positions at all.
 
 ## 4. Part II — statically typed staggering
 
@@ -715,9 +654,9 @@ produces them, mypy-clean, all existing tests pass):
 Stages 0–2 of the dtype plan are prerequisites for the *frontend* stages here
 (the binding utilities are shared); Part I/II stages are independent of dtype.
 
-1. **Stage D0 — dimensions as types in `common`** (Part I): class-style
-   `Dimension` + metaclass + interop equality, legacy factory, typing_tests;
-   ADR `0024`.
+1. **Stage D0 — dimensions as types in `common`** (Part I): specified in
+   [[shared/dimensions-as-types|Dimensions as types]]; prerequisite for every
+   stage below.
 2. **Stage D1 — typed shifts & staggering, static side** (Part II):
    `Staggered`, typed `Connectivity`, generated `Field.__call__` overloads;
    remove the dims hack from the mypy plugin for class-style dims.
@@ -735,7 +674,8 @@ Stages 0–2 of the dtype plan are prerequisites for the *frontend* stages here
 
 ## 10. Risks and open questions
 
-1. **The metaclass-overload mypy quirk** (§3.3): call-site behavior is
+1. **The metaclass-overload mypy quirk** (see
+   [[shared/dimensions-as-types|Dimensions as types]]): call-site behavior is
    correct but the def-site suppression could break on a mypy upgrade;
    pinned by tests, with a notation-only fallback. **pyright is untested** —
    must be checked before committing to the `I + 1/2` notation (the
@@ -745,10 +685,8 @@ Stages 0–2 of the dtype plan are prerequisites for the *frontend* stages here
 3. **Overload-set size vs. checker performance**: N(N+1)/2 overloads per
    substitution operation is small (≤ 15), but `Field` has many operators;
    measure mypy runtime on a large downstream consumer before generalizing.
-4. **Migration surface of Part I** is the largest cost item: every IR node
-   embedding `common.Dimension`, eve serialization of class objects, and
-   downstream user code. The name-based-equality interop bounds the risk but
-   needs a dedicated test layer (mixed old/new dims in one program).
+4. **Migration surface of Part I** is the largest cost item overall; it is
+   tracked in [[shared/dimensions-as-types|Dimensions as types]], not here.
 5. **Canonical dims ordering with variables**: `Dims[D, K]` assumes the
    binding of `D` sorts before `K`; substitution re-validates, so a "wrongly
    ordered" binding today raises a validator error — decide whether to
diff --git a/content/shared/dimensions-as-types.md b/content/shared/dimensions-as-types.md
new file mode 100644
index 0000000..ce5b4d7
--- /dev/null
+++ b/content/shared/dimensions-as-types.md
@@ -0,0 +1,192 @@
+---
+title: Dimensions as types
+description: "Make a concrete gt4py.next dimension a type (`class I(gtx.Dimension)`) instead of an instance, so `Field[Dims[I], float64]` is a real annotation for plain mypy — and so that staggering, dimension variables and dependent local dimensions can land on top without revisiting the base."
+author: havogt
+tags: [type-system, dimensions, type-checking, mypy, mypy-plugin, nominal-types, metaclass, migration, frontend, foast, extension-point]
+created: 2026-08-05
+status: proposed
+---
+
+> **TL;DR** A concrete dimension is currently an *instance*
+> (`I = Dimension("I")`), so `Field[Dims[I], float64]` is not a valid static
+> annotation and gt4py ships a mypy plugin to paper over it. Make a dimension a
+> *class* (`class I(gtx.Dimension): ...`) whose class object carries today's
+> value-level behaviour via a metaclass. That is the entire proposal — but the
+> shape is chosen so that staggering, dimension variables and dependent local
+> dimensions all land on top of it without coming back to change it.
+
+> **Prototype**: mypy-verified, vendored under
+> [[personal/havogt/dimension-generic-fields|Generic dimensions and statically
+> typed staggering]] (`dimension-generic-fields/typed_dimensions.py`,
+> `static_checks.py`, `static_errors.py`, `test_typed_dimensions.py`; mypy 1.19,
+> no plugin). That document is the wider investigation this one is extracted
+> from; everything beyond Part I stays there.
+
+## Scope
+
+| In | Out |
+| --- | --- |
+| A concrete dimension is a type | Staggering syntax and index conventions |
+| Value-level behaviour preserved on the class object | Dimension variables / dim-generic operators |
+| Old- and new-style dimensions coexist during migration | Dependent local dimensions and connectivity chains |
+| Dimension types usable as `TypeVar` bounds | Anything about `Dims` ordering semantics |
+
+The out-column items each have their own proposal. This one is deliberately the
+smallest thing that unblocks all of them.
+
+## Problem
+
+`I = Dimension("I")` is an instance (`common.py:95`), so `Field[Dims[I], T]` is
+not a valid annotation — mypy reports `Variable "I" is not valid as a type
+[valid-type]`. That is GridTools/gt4py#2503, and the shipped answer is a
+compatibility shim: `src/gt4py/next/type_system/mypy_plugin.py` (wired in via
+`pyproject.toml` `[tool.mypy] plugins = [...]`), which substitutes placeholder
+classes `_DimA`–`_DimD` and then `_AnyDim` for dimension arguments.
+
+What that costs:
+
+- At most **four distinct dimensions** are tracked per run, *globally*, keyed by
+  argument name — so same-named dimensions in different modules collide and
+  everything past the fourth becomes `_AnyDim`.
+- **No `TypeVar`s over dimensions**, so no dimension-generic operator can ever be
+  typed.
+- **Every downstream project must install the plugin**, and only mypy is served;
+  pyright users get nothing.
+- The plugin also *blurs dtypes* (`float` vs `float32` vs `float64`) to suppress
+  a different class of false positive, which erases exactly the information
+  dtype generics need.
+
+**Success criterion**: with this proposal landed, the dimension half of
+`mypy_plugin.py` is deleted rather than maintained, and client code type-checks
+without a gt4py-specific plugin.
+
+## Design
+
+```python
+class DimensionBase(metaclass=DimensionMeta):   # root: anything usable in Dims[...]
+    value: ClassVar[str]                        # defaults to the class name
+    kind: ClassVar[DimensionKind] = DimensionKind.HORIZONTAL
+
+
+class Dimension(DimensionBase): ...             # base of *user-declared* dimensions
+
+
+class I(Dimension): ...
+class K(Dimension, kind=DimensionKind.VERTICAL): ...
+```
+
+- **The class object is the value.** There is no instance level (`__new__`
+  raises). Wherever a `Dimension` instance flows today — domains, offset
+  providers, `FieldType.dims`, IR nodes — the class object flows instead.
+- **`DimensionMeta` carries the value-level API**: `__add__`/`__sub__` building
+  connectivities, `__call__` → `NamedIndex`, comparison operators → `Domain`,
+  `__repr__`. Binary operators on a class object dispatch through its metaclass,
+  so this is the only place they can live.
+- **Name-based `__eq__`/`__hash__` on the metaclass** reproduces today's
+  `Dimension.__eq__` (which compares `.value` only) and makes a new-style class
+  compare and hash equal to an old-style instance of the same name. This is the
+  migration mechanism: `Domain` dicts, offset-provider lookups and
+  `FieldType.dims` comparisons work across both styles, so subsystems — and
+  downstream code such as icon4py — migrate dimension by dimension.
+
+## The extension point
+
+This is the part that makes the proposal worth landing on its own.
+
+The two-level split — a root `DimensionBase` (anything usable inside `Dims[...]`)
+above `Dimension` (the base of user-declared dimensions) — exists so that
+**parameterized dimension types** can be usable in `Dims[...]` without being
+user-declarable. Both known follow-ups need exactly that, and neither is decided
+here:
+
+- **`Staggered[D]`** — a dimension parameterized by a dimension. Binding its
+  parameter to `Dimension` rather than the root is what makes
+  `Staggered[Staggered[I]]` statically unrepresentable.
+- **`Local[C]`** — a local dimension parameterized by the *connectivity* it comes
+  from, so `V2EDim`'s dependence on `Vertex` lives in the type
+  ([[personal/havogt/dependent-local-dimensions|Dependent local dimensions and
+  connectivity chains]], §4.4/§5.4 — both designs are mypy-verified on top of
+  this base).
+
+Dimension variables (`TypeVar("D", bound=Dimension)`, `TypeVarTuple` over dims)
+need only that dimensions *are* types, which is the proposal itself.
+
+So the forward-compatibility claim is narrow and checkable: **the root admits
+parameterized dimension types, and both candidate users of that slot have
+working prototypes.** Nothing else about them is settled here.
+
+## Relation to the shipped `_Staggered` name prefix
+
+gt4py already ships staggered dimensions (`feat[next]: staggered fields`, #2667,
+ADR 0026), encoding "staggered" as a `_Staggered` prefix on the dimension
+*name*. That ADR's rationale is sound *given today's model*: a dimension is
+identified by its name and appears as a `common.Dimension`, as an
+`itir.AxisLiteral`, and as a plain string in generated backend code, so a flag on
+`Dimension` would have to be threaded through all three.
+
+Dimensions-as-types changes that premise — identity becomes nominal, and the name
+becomes what crosses the IR boundary rather than what *is* the dimension.
+(`itir.AxisLiteral` is `(value: str, kind)` and already carries
+`TODO(havogt): Refactor to use declare Axis/Dimension at the Program level`.)
+
+**Step 1 keeps the prefix and costs nothing.** `Staggered[I]` materializes a class
+whose `value` is `"_StaggeredI"`; because the metaclass compares by name, every
+existing staggering helper keeps working untouched — `is_staggered`,
+`flip_staggered`, `as_non_staggered`, `check_dims` and `order_dimensions` read
+only `.value`/`.kind`, and gtfn's `_add_staggered_aliases` rebuilds a `Dimension`
+from a string. (Established by reading those call sites, not by running a
+migration.)
+
+**Step 2 is a separate change behind this surface.** Once staggering is answered
+by the type, `is_staggered`'s `dim.value.startswith("_Staggered")` sniffing has no
+callers and the encoding stops being a user-visible convention. Being precise
+about what does *not* go away: distinct axes still need distinct identifiers at
+the IR and backend boundary, so some mangling survives there. What disappears is
+the string sniffing and the fact that users can observe — or collide with — the
+prefix.
+
+## Migration
+
+Each step is landable separately, with name-based equality carrying the interop:
+
+1. Land `DimensionMeta` / class-style `Dimension` in `common`, with name-based
+   interop; keep `Dimension("I")` working as a factory.
+2. Move gt4py-internal dimension definitions (tests, docs, `fbuiltins`) to class
+   style; add `typing_tests` coverage; drop the `_DimA`–`_DimD` machinery from
+   the mypy plugin for class-style dimensions.
+3. Deprecate instance-style definitions; `Dimension("I")` eventually warns.
+
+## Open questions and risks
+
+1. **The metaclass-overload mypy quirk.** mypy rejects generic self-types on
+   metaclass methods at the *definition* site but applies them correctly at every
+   *call* site, so the operator overloads carry `# type: ignore[misc]`, pinned by
+   `static_checks.py`. **pyright is untested and must be checked before
+   committing** — the checker-agnostic fallback is free functions (`shift(I, 1)`),
+   which changes notation but not the design.
+2. **eve serialization of dimension classes** inside IR nodes: dataclass
+   instances serialize structurally today; classes need a `value`/`kind`-based
+   representation. Straightforward, since both are class attributes — but it is
+   real work and touches every IR node embedding a `common.Dimension`.
+3. **Migration surface is the largest cost item.** Name-based interop bounds the
+   risk but needs a dedicated test layer exercising mixed old/new dimensions in
+   one program.
+4. **`typing` internals cache subscriptions by hash**, so hash-equal-but-distinct
+   dimensions could alias. Only reachable for same-named distinct dimensions,
+   which are rejected anyway.
+5. **Dependent local dimensions stay open** and are expected to. The one question
+   that reaches back here is whether dimension variables range over hop stacks
+   ([[personal/havogt/dependent-local-dimensions|dependent local dimensions]]
+   §8.2); the v0 answer — dimension variables bind origin and non-local dims only
+   — leaves this proposal unaffected either way.
+
+## Related
+
+- [[personal/havogt/dimension-generic-fields|Generic dimensions and statically
+  typed staggering]] — the investigation this is extracted from; keeps staggering
+  (Part II) and dimension variables (Part III).
+- [[personal/havogt/dependent-local-dimensions|Dependent local dimensions and
+  connectivity chains]] — the second consumer of the parameterized-dimension slot.
+- [[personal/havogt/dtype-generic-fields|Dtype-generic fields in gt4py.next]] —
+  shares the binding/monomorphization machinery, and is the other half of what
+  the mypy plugin currently blurs.