Mark stale equation files and add README to CanonicalRingEquations

Added STALE warning comments to the 4 equation files (D=12,21,24,28)
that have failing Hilbert series sanity checks and cannot be regenerated
due to the upstream Magma bug at precompute.m:1064. Added README.md
documenting the status of all files in the directory.

Author: edgarcosta

Verification/CanonicalRingEquations/2.2.12.1-1.1-gl-0.m

@@ -1,3 +1,6 @@
+// STALE: generated with old 4-arg HilbertModularVariety; Hilbert series sanity check fails.
+// Cannot regenerate: narrow class number 2 hits upstream Magma bug (precompute.m:1064).
+//
 // level has label 1.1
 // Computed with precision = 190
 // generator degree bound = 14

Verification/CanonicalRingEquations/2.2.21.1-1.1-gl-0.m

@@ -1,3 +1,6 @@
+// STALE: generated with old 4-arg HilbertModularVariety; Hilbert series sanity check fails.
+// Cannot regenerate: narrow class number 2 hits upstream Magma bug (precompute.m:1064).
+//
 // level has label 1.1
 // Computed with precision = 180
 // generator degree bound = 10

Verification/CanonicalRingEquations/2.2.24.1-1.1-gl-0.m

@@ -1,3 +1,6 @@
+// STALE: generated with old 4-arg HilbertModularVariety; Hilbert series sanity check fails.
+// Cannot regenerate: narrow class number 2 hits upstream Magma bug (precompute.m:1064).
+//
 // level has label 1.1
 // Computed with precision = 260
 // generator degree bound = 10

Verification/CanonicalRingEquations/2.2.28.1-1.1-gl-0.m

@@ -1,3 +1,6 @@
+// STALE: generated with old 4-arg HilbertModularVariety; Hilbert series sanity check fails.
+// Cannot regenerate: narrow class number 2 hits upstream Magma bug (precompute.m:1064).
+//
 // level has label 1.1
 // Computed with precision = 320
 // generator degree bound = 10

Verification/CanonicalRingEquations/README.md

@@ -0,0 +1,46 @@
+# Canonical Ring Equations
+
+Precomputed canonical ring equations for Hilbert modular surfaces, generated by
+`WriteCanonicalRingComputationToFile` (see `ModFrmHilD/CanonicalRing/IO.m`).
+
+Each file defines a weighted projective scheme `S` whose Hilbert series should
+match the trace formula prediction from `HilbertSeries(M, NN)`.
+
+## File status
+
+### Current (sanity check passes)
+
+| File | Field | Level | Components |
+|------|-------|-------|------------|
+| `2.2.5.1-1.1-gl-0.m` | Q(sqrt(5)) | 1 | 1 |
+| `2.2.5.1-4.1-gl-0.m` | Q(sqrt(5)) | 4.1 | 1 |
+| `2.2.5.1-5.1-gl-0.m` | Q(sqrt(5)) | 5.1 | 1 |
+| `2.2.8.1-1.1-gl-0.m` | Q(sqrt(2)) | 1 | 1 |
+| `2.2.8.1-2.1-gl-0.m` | Q(sqrt(2)) | 2.1 | 1 |
+| `2.2.13.1-1.1-gl-0.m` | Q(sqrt(13)) | 1 | 1 |
+| `2.2.13.1-3.1-gl-0.m` | Q(sqrt(13)) | 3.1 | 1 |
+| `2.2.13.1-4.1-gl-0.m` | Q(sqrt(13)) | 4.1 | 1 |
+| `2.2.17.1-1.1-gl-0.m` | Q(sqrt(17)) | 1 | 1 |
+| `2.2.29.1-1.1-gl-0.m` | Q(sqrt(29)) | 1 | 1 |
+| `2.2.37.1-1.1-gl-0.m` | Q(sqrt(37)) | 1 | 1 |
+| `2.2.41.1-1.1-gl-0.m` | Q(sqrt(41)) | 1 | 1 |
+
+### Stale (sanity check fails)
+
+These were generated with the old 4-arg `HilbertModularVariety` and have
+incorrect equations. They cannot be regenerated because these discriminants have
+narrow class number > 1 and hit the upstream Magma bug at `precompute.m:1064`
+(assertion failure in `precompute_tps` for the definite method).
+
+| File | Field | Level | h+ | Issue |
+|------|-------|-------|----|-------|
+| `2.2.12.1-1.1-gl-0.m` | Q(sqrt(3)) | 1 | 2 | stale; regen runs >4h / 64 GB |
+| `2.2.21.1-1.1-gl-0.m` | Q(sqrt(21)) | 1 | 2 | stale; regen runs >4h / 50 GB |
+| `2.2.24.1-1.1-gl-0.m` | Q(sqrt(6)) | 1 | 2 | stale; hits precompute.m:1064 |
+| `2.2.28.1-1.1-gl-0.m` | Q(sqrt(7)) | 1 | 2 | stale; hits precompute.m:1064 |
+
+### Missing
+
+| Label | Field | Level | h+ | Issue |
+|-------|-------|-------|----|-------|
+| `2.2.33.1-1.1-gl-0.m` | Q(sqrt(33)) | 1 | 2 | hits precompute.m:1064 before writing |