From b2d25e949118e5bf13ad2bce88530fd24bb898e7 Mon Sep 17 00:00:00 2001
From: Jukka Aho <ahojukka5@gmail.com>
Date: Sat, 15 Nov 2025 02:24:01 +0200
Subject: [PATCH] refactor(topology): Add node count type parameter to
 AbstractTopology

Change AbstractTopology to AbstractTopology{N} where N is node count.

This implements ADR-002 (November 13, 2025) decision: node count comes
from mesh connectivity and should be captured in the type for
compile-time optimization.

Benefits:
- Enables Val(N) for zero-allocation ntuple operations
- Allows loop unrolling for small N (8, 20, 27 nodes typical)
- Type-stable operations based on node count
- Node count known from mesh before basis selection

Documentation updates:
- Add Type Parameter section with examples
- Add Rationale section explaining performance benefits
- Reference ADR-002 for design decision details

Concrete types updated in subsequent commits:
  Hexahedron{N}, Tetrahedron{N}, Triangle{N}, etc.
---
 src/topology/topology.jl | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/src/topology/topology.jl b/src/topology/topology.jl
index 9c0fed3..55b2349 100644
--- a/src/topology/topology.jl
+++ b/src/topology/topology.jl
@@ -46,8 +46,27 @@ element = Element(Tri3, (1,2,3))  # Tri3 is alias for Triangle
 
 See also: [`Segment`](@ref), [`Triangle`](@ref), [`Quadrilateral`](@ref), 
           [`Tetrahedron`](@ref), [`Hexahedron`](@ref), [`Pyramid`](@ref), [`Wedge`](@ref)
+
+# Type Parameter
+
+`AbstractTopology{N}` where `N` is the number of nodes. Node count comes from mesh connectivity.
+
+# Examples
+```julia
+Hexahedron{8} <: AbstractTopology{8}   # 8-node hex (linear)
+Hexahedron{20} <: AbstractTopology{20} # 20-node hex (quadratic serendipity)
+Hexahedron{27} <: AbstractTopology{27} # 27-node hex (quadratic full)
+```
+
+# Rationale
+
+Node count is included in the type parameter for compile-time performance optimization:
+- Enables `Val(N)` for zero-allocation ntuple operations
+- Allows loop unrolling for small N
+- Node count comes from mesh connectivity, not basis choice
+- See ADR-002 for detailed design rationale
 """
-abstract type AbstractTopology end
+abstract type AbstractTopology{N} end
 
 """
     nnodes(topology::AbstractTopology) -> Int