Merge: cross-port generator stable-name conformance (ADR-0021 D3 fan-out)

Stabilizes generator names across all 5 ports + adds a conformance gate:
- Canonical manifest fixtures/generator-registry-conformance/registry.json is the
  single source of truth for generator stable names (concept + tier + which ports
  expose each). Shared concepts (entity, routes, output-parser, output-prompt,
  render-helper, extractor, template, filter-allowlist, payload) are now spelled
  IDENTICALLY in every port.
- Each port gained a generator registry conformant to the manifest:
  TS + C# (registries pre-existed; added conformance tests), and NEW registries
  for Java (11), Kotlin (13, no template), Python (9). Python also got
  metaobjects gen --list + --generators selection (the 5th-port CLI parity).
- Every port's conformance test asserts bidirectional set-equality + tier against
  the one manifest, so any rogue/missing/misspelled generator name fails CI.
- CI wired to run the new conformance tests in the C#/Java/Kotlin jobs (TS+Python
  already run whole suites/dirs) — the gate actually fires.

Maven/dotnet selection-by-stable-name (vs the registry powering identity + the
gate) remains a staged follow-on. No generated-output change; per-port emission
and default suites unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

.github/workflows/conformance.yml

@@ -66,6 +66,8 @@ jobs:
           dotnet test MetaObjects.Render.Tests/MetaObjects.Render.Tests.csproj --nologo --verbosity quiet
           # Validator-parity corpus (generated DataAnnotations input validation).
           dotnet test MetaObjects.Codegen.Tests/MetaObjects.Codegen.Tests.csproj --filter "FullyQualifiedName~ValidationConformance" --nologo --verbosity quiet
+          # Generator stable-name registry conformance (ADR-0021 D3).
+          dotnet test MetaObjects.Codegen.Tests/MetaObjects.Codegen.Tests.csproj --filter "FullyQualifiedName~GeneratorRegistryConformance" --nologo --verbosity quiet
 
       - name: Java conformance
         if: matrix.language == 'java'
@@ -79,8 +81,9 @@ jobs:
           mvn -pl metadata test -Dtest='ConformanceTest,YamlConformanceTest,ObjectModelConformanceTest' -q
           # Byte-exact render / verify / extract / output-prompt corpora (render module).
           mvn -pl render test -Dtest='RenderCrossPortReportTest,VerifyConformanceTest,ExtractConformanceTest,OutputPromptConformanceTest' -q
-          # Validator-parity corpus (generated DTO jakarta.validation, codegen-spring module).
-          mvn -pl codegen-spring test -Dtest='ValidationConformanceTest' -q
+          # Validator-parity corpus (generated DTO jakarta.validation, codegen-spring module)
+          # + generator stable-name registry conformance (ADR-0021 D3).
+          mvn -pl codegen-spring test -Dtest='ValidationConformanceTest,GeneratorRegistryConformanceTest' -q
 
       - name: Python conformance
         if: matrix.language == 'python'
@@ -92,6 +95,8 @@ jobs:
           uv run pytest tests/render -q
           # Validator-parity corpus (generated Pydantic input validation).
           uv run pytest tests/codegen/test_validation_conformance.py -q
+          # Generator registry CLI ergonomics (gen --list / --generators selection, ADR-0021 D3).
+          uv run pytest tests/codegen/test_cli_registry.py -q
 
   conformance-kotlin:
     # Kotlin (codegen-kotlin, KotlinPoet on the JVM) ships no loader / YAML /
@@ -116,8 +121,9 @@ jobs:
           # SNAPSHOT-resolution race when the test module references freshly-built
           # artifacts.
           mvn -pl codegen-kotlin -am install -DskipTests -q
-          # object-model + output-prompt + validator-parity corpora (the corpora Kotlin has).
-          mvn -pl codegen-kotlin test -Dtest='ObjectModelConformanceTest,OutputPromptConformanceTest,ValidationConformanceTest' -q
+          # object-model + output-prompt + validator-parity corpora (the corpora Kotlin has)
+          # + generator stable-name registry conformance (ADR-0021 D3).
+          mvn -pl codegen-kotlin test -Dtest='ObjectModelConformanceTest,OutputPromptConformanceTest,ValidationConformanceTest,GeneratorRegistryConformanceTest' -q
 
   completeness-gate:
     needs: [conformance, conformance-kotlin]

fixtures/generator-registry-conformance/README.md

@@ -0,0 +1,40 @@
+# generator-registry conformance
+
+The canonical cross-port manifest of **stable generator names** (ADR-0021 D3).
+`registry.json` is the single source of truth; every port's generator registry is
+conformance-tested against it.
+
+## The contract each port's test enforces
+
+Given the port's own generator registry (stable-name → generator), the port's
+conformance test asserts:
+
+1. **No rogue names** — every stable name the port registers appears in
+   `registry.json`.
+2. **Presence both ways** — for every manifest entry whose `ports` array includes
+   this port, the port's registry exposes that name; and the port does **not**
+   expose a name whose `ports` array omits it.
+3. **Tier agreement** — a name marked `tier: "neutral"` is flagged neutral in the
+   port (owned by `meta docs`, not the recommended native suite).
+
+Because all five ports validate against this one file, a **shared concept is
+spelled identically everywhere** (e.g. the REST surface is `routes` in every
+port, never `controller`/`router`). That cross-port spelling stability is the
+whole point.
+
+## Shared (cross-port) names
+
+These concepts MUST use the same stable name wherever a port implements them:
+`entity`, `routes`, `output-parser`, `output-prompt`, `render-helper`,
+`extractor`, `template`, `filter-allowlist`, `payload`.
+
+## Changing the surface
+
+Adding, removing, or renaming a generator means editing **both** `registry.json`
+**and** the port's registry in the same change — the conformance gate fails on
+any drift (a typo'd name, a missing registration, a port that quietly diverges).
+This is the mechanism that keeps the codegen surface coherent as it grows.
+
+## Port ids
+
+`typescript`, `csharp`, `java`, `kotlin`, `python`.

fixtures/generator-registry-conformance/registry.json

@@ -0,0 +1,128 @@
+{
+  "$comment": "CANONICAL generator stable-name manifest (ADR-0021 D3). The single cross-port source of truth for generator stable names. Every port's generator registry is conformance-tested against this file: (1) every generator a port exposes MUST use a name listed here; (2) for each generator, the `ports` array lists exactly the ports expected to expose it (presence is checked both ways); (3) because all ports validate against this one file, a shared concept (e.g. `routes`) is spelled identically everywhere. Port ids: typescript, csharp, java, kotlin, python. `tier`: native (idiomatic per-port code) or neutral (Tier-2, owned by `meta docs`). Adding/renaming a generator = edit THIS file + the port registry together; the conformance gate fails otherwise.",
+  "ports": ["typescript", "csharp", "java", "kotlin", "python"],
+  "generators": {
+    "entity": {
+      "concept": "Per-entity model/class — the entity module (table-backed or value object).",
+      "tier": "native",
+      "ports": ["typescript", "csharp", "java", "kotlin", "python"]
+    },
+    "routes": {
+      "concept": "Per-entity REST endpoint surface (controllers / routes / router).",
+      "tier": "native",
+      "ports": ["typescript", "csharp", "java", "kotlin", "python"]
+    },
+    "output-parser": {
+      "concept": "Per-template tolerant output parser (recover-on-receipt).",
+      "tier": "native",
+      "ports": ["typescript", "csharp", "java", "kotlin", "python"]
+    },
+    "output-prompt": {
+      "concept": "Per-template output-format prompt fragment generator.",
+      "tier": "native",
+      "ports": ["typescript", "csharp", "java", "kotlin", "python"]
+    },
+    "render-helper": {
+      "concept": "Per-template.output render helper (document/email typed wrappers).",
+      "tier": "native",
+      "ports": ["typescript", "csharp", "java", "kotlin", "python"]
+    },
+    "extractor": {
+      "concept": "Per-template strict typed extract<Name> helper (strict payload extraction).",
+      "tier": "native",
+      "ports": ["typescript", "csharp", "java", "kotlin", "python"]
+    },
+    "template": {
+      "concept": "Generic Mustache template primitive (walk + template -> files).",
+      "tier": "native",
+      "ports": ["typescript", "csharp", "java", "python"]
+    },
+    "filter-allowlist": {
+      "concept": "Per-entity REST filter allowlist (queryable-field guard).",
+      "tier": "native",
+      "ports": ["csharp", "java", "kotlin", "python"]
+    },
+    "payload": {
+      "concept": "Per-template payload value object (the strict payload type).",
+      "tier": "native",
+      "ports": ["java", "kotlin", "python"]
+    },
+    "queries": {
+      "concept": "Per-entity typed query helpers (findById/create/...).",
+      "tier": "native",
+      "ports": ["typescript"]
+    },
+    "callable": {
+      "concept": "Per-entity callable/service surface wrapping the query helpers.",
+      "tier": "native",
+      "ports": ["typescript"]
+    },
+    "routes-hono": {
+      "concept": "Per-entity Hono CRUD routes.",
+      "tier": "native",
+      "ports": ["typescript"]
+    },
+    "barrel": {
+      "concept": "Single index module re-exporting every generated entity module.",
+      "tier": "native",
+      "ports": ["typescript"]
+    },
+    "prompt-render": {
+      "concept": "Per-template prompt-render helper over the render engine.",
+      "tier": "native",
+      "ports": ["typescript"]
+    },
+    "db-context": {
+      "concept": "Single EF Core DbContext binding every generated entity.",
+      "tier": "native",
+      "ports": ["csharp"]
+    },
+    "repository": {
+      "concept": "Per-entity Spring Data repository.",
+      "tier": "native",
+      "ports": ["java"]
+    },
+    "dto": {
+      "concept": "Per-entity Spring DTO.",
+      "tier": "native",
+      "ports": ["java"]
+    },
+    "exposed-table": {
+      "concept": "Per-entity Kotlin Exposed table object.",
+      "tier": "native",
+      "ports": ["kotlin"]
+    },
+    "relations": {
+      "concept": "Cross-entity relationship helpers.",
+      "tier": "native",
+      "ports": ["kotlin"]
+    },
+    "spring-config": {
+      "concept": "Spring wiring/configuration for the generated surface.",
+      "tier": "native",
+      "ports": ["kotlin"]
+    },
+    "stored-proc": {
+      "concept": "Stored-procedure binding helpers.",
+      "tier": "native",
+      "ports": ["kotlin"]
+    },
+    "validator": {
+      "concept": "Per-entity input validator.",
+      "tier": "native",
+      "ports": ["kotlin"]
+    },
+    "docs": {
+      "concept": "Neutral per-entity / per-template Markdown documentation pages.",
+      "tier": "neutral",
+      "note": "Owned by `meta docs` (the single docs door, ADR-0021 D1); not part of the recommended native suite.",
+      "ports": ["typescript"]
+    },
+    "mermaid-er": {
+      "concept": "Neutral Mermaid ER diagram of the entity/relationship model.",
+      "tier": "neutral",
+      "note": "Neutral artifact owned by the docs engine (ADR-0020); surfaced via `meta docs`.",
+      "ports": ["typescript"]
+    }
+  }
+}

server/csharp/MetaObjects.Codegen.Tests/GeneratorRegistryConformanceTests.cs

@@ -0,0 +1,113 @@
+using System.Text.Json;
+using MetaObjects.Codegen;
+using Xunit;
+
+namespace MetaObjects.Codegen.Tests;
+
+/// <summary>
+/// Cross-port conformance for the C# generator registry (ADR-0021 D3). Validates
+/// <see cref="GeneratorRegistry"/> against the CANONICAL stable-name manifest at
+/// <c>fixtures/generator-registry-conformance/registry.json</c> — the single
+/// cross-port source of truth every port's registry is checked against.
+///
+/// Contract for the <c>csharp</c> port:
+///   (1) every stable name the C# registry exposes appears in the manifest;
+///   (2) presence both ways — every manifest entry whose <c>ports</c> includes
+///       <c>csharp</c> IS in the C# registry, and the C# registry exposes NO name
+///       whose manifest <c>ports</c> omits <c>csharp</c> (i.e. the two sets are EQUAL);
+///   (3) tier agreement — every native manifest name is non-neutral in the registry
+///       (C# has no neutral generators per the manifest).
+///
+/// On mismatch this REPORTS the exact diff (extras / missing / tier) so the manifest
+/// and registry can be reconciled. It never mutates either.
+/// </summary>
+public sealed class GeneratorRegistryConformanceTests
+{
+    private const string Port = "csharp";
+
+    // Walk upward from the test assembly to the repo root (contains the manifest dir),
+    // mirroring RenderHelperConformanceTests.Corpus().
+    private static string ManifestPath()
+    {
+        var dir = AppContext.BaseDirectory;
+        while (dir is not null &&
+               !Directory.Exists(Path.Combine(dir, "fixtures", "generator-registry-conformance")))
+            dir = Directory.GetParent(dir)?.FullName;
+        if (dir is null)
+            throw new InvalidOperationException(
+                "fixtures/generator-registry-conformance not found walking up from " + AppContext.BaseDirectory);
+        return Path.Combine(dir, "fixtures", "generator-registry-conformance", "registry.json");
+    }
+
+    private sealed record ManifestEntry(string Name, string Tier, IReadOnlyList<string> Ports);
+
+    private static IReadOnlyList<ManifestEntry> LoadManifest()
+    {
+        using var doc = JsonDocument.Parse(File.ReadAllText(ManifestPath()));
+        var generators = doc.RootElement.GetProperty("generators");
+        var entries = new List<ManifestEntry>();
+        foreach (var prop in generators.EnumerateObject())
+        {
+            var tier = prop.Value.GetProperty("tier").GetString()!;
+            var ports = prop.Value.GetProperty("ports").EnumerateArray()
+                .Select(p => p.GetString()!).ToList();
+            entries.Add(new ManifestEntry(prop.Name, tier, ports));
+        }
+        return entries;
+    }
+
+    /// <summary>(1)+(2): the manifest's csharp slice equals the C# registry's stable names.</summary>
+    [Fact]
+    public void RegistryStableNames_EqualManifestCsharpSlice()
+    {
+        var manifest = LoadManifest();
+
+        var expected = manifest
+            .Where(e => e.Ports.Contains(Port))
+            .Select(e => e.Name)
+            .ToHashSet(StringComparer.Ordinal);
+
+        var actual = GeneratorRegistry.Entries.Keys.ToHashSet(StringComparer.Ordinal);
+
+        var missing = expected.Except(actual).OrderBy(n => n, StringComparer.Ordinal).ToList();
+        var extras = actual.Except(expected).OrderBy(n => n, StringComparer.Ordinal).ToList();
+
+        Assert.True(
+            missing.Count == 0 && extras.Count == 0,
+            $"C# generator registry disagrees with the canonical manifest's `{Port}` slice " +
+            $"(fixtures/generator-registry-conformance/registry.json).\n" +
+            $"  MISSING (manifest says `{Port}` exposes it, but the registry does not): " +
+            $"[{string.Join(", ", missing)}]\n" +
+            $"  EXTRA  (registry exposes it, but the manifest omits `{Port}` for it):    " +
+            $"[{string.Join(", ", extras)}]\n" +
+            "Reconcile by editing the manifest AND the registry together — do not force one to match.");
+    }
+
+    /// <summary>(3): every native manifest name is non-neutral (Native) in the C# registry.</summary>
+    [Fact]
+    public void TierAgreement_NativeManifestNames_AreNativeInRegistry()
+    {
+        var manifest = LoadManifest();
+
+        var tierMismatches = manifest
+            .Where(e => e.Ports.Contains(Port))
+            .Where(e => GeneratorRegistry.Entries.TryGetValue(e.Name, out var reg)
+                        && !TierMatches(e.Tier, reg.Tier))
+            .Select(e =>
+                $"{e.Name}: manifest tier=`{e.Tier}` but registry tier=`{GeneratorRegistry.Entries[e.Name].Tier}`")
+            .ToList();
+
+        Assert.True(
+            tierMismatches.Count == 0,
+            "C# generator registry tier disagrees with the canonical manifest:\n  " +
+            string.Join("\n  ", tierMismatches));
+    }
+
+    private static bool TierMatches(string manifestTier, GeneratorTier registryTier) =>
+        manifestTier switch
+        {
+            "native" => registryTier == GeneratorTier.Native,
+            "neutral" => registryTier == GeneratorTier.Neutral,
+            _ => false,
+        };
+}