fix(codegen-kotlin): fold TPH discriminator subtypes into the base — no dead per-subtype artifacts

A TPH (table-per-hierarchy) discriminator base already emitted the union table +
data class + discriminator enum + polymorphic controller, and the controller
generator skipped subtypes — but five other generation paths still emitted dead,
partly non-compiling per-subtype artifacts for each subtype:

- KotlinExposedTableGenerator emitted <Sub>Table mapping the SAME physical table
  with a partial column set (a footgun), AND its back-FK inference
  (buildGlobalFkMap) fanned a base's inherited to-many composition into phantom
  per-subtype inverse FKs (<Sub>Table.id references) — a compile break once the
  tables are folded away.
- KotlinEntityGenerator emitted a dead <Sub> data class that re-emitted the
  inherited discriminator enum under a spurious name.
- KotlinFilterAllowlistGenerator / KotlinValidatorGenerator / KotlinRelationsGenerator
  emitted dead <Sub> allowlists / registry entries / relation helpers, the latter
  two referencing the now-missing <Sub>Table (compile breaks).

Fix: every entity-iterating generator now skips KotlinTphPlan.isTphSubtype (mirroring
the controller's existing skip). Because a subtype folds into the base, the base
union data class must also emit the enum class for any subtype-only field.enum it
folds in (KotlinEntityGenerator now emits enum files over collectSubtypeFields,
owner = base) — else the union references an enum no file defines.

This brings Kotlin into line with the Java (codegen-spring) port, which already
folds TPH subtypes into the base.

Gated:
- Expanded entity-with-tph snapshot fixture (a to-many composition Auth.lines→AuthLine
  + validator/relations generators) byte-gates the five structural skips + the
  buildGlobalFkMap fold — reverting any one re-emits a per-subtype artifact.
- New KotlinOutputCompilesTest case compile-proves the folded-subtype-enum path
  (a subtype field.enum → the base union compiles).
- New integration TphFullSuiteCompilesTest compiles the FULL generator suite
  (Exposed + Spring on the classpath) over a discriminator base owning a
  composition — the compile gate the snapshot byte-compare can't provide.

Scoped out: a pre-existing, non-TPH bug where the generated Kotlin controller emits
non-compiling enum-filter code for @filterable field.enum columns (wrong enum name +
String→enum cast) — filed as #179; this change keeps its snapshot fixture's subtype
enum off the controller surface.

Two rounds of code review + simplify informed this change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ew1XfYSbEAezxjs9opynAe

Author: dmealing

server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinEntityGenerator.kt

@@ -88,6 +88,10 @@ open class KotlinEntityGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
                 if (emitAbstractShapes) emitAbstractShape(obj, outRoot, loader, emittedEnumFqns)
                 continue
             }
+            // FR-017 TPH: a discriminator subtype folds into its base's union data class +
+            // discriminator enum. A per-subtype data class is dead and re-emits the inherited
+            // enum under a spurious name. Mirror the controller/table skip.
+            if (KotlinTphPlan.isTphSubtype(obj)) continue
             emit(obj, outRoot, loader, emittedEnumFqns)
         }
     }
@@ -100,6 +104,14 @@ open class KotlinEntityGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
             if (field is EnumField && !Fr019SharedEnum.isProvidedEnumField(field))
                 KotlinEnumEmitter.emitEnumFile(obj, field, outRoot, emittedEnumFqns)
         }
+        // FR-017 TPH: the base union folds in subtype-only fields (below). A folded field.enum
+        // resolves to a typed enum ClassName, so its enum file must be emitted here (owner = base,
+        // matching the fold's type resolution) — the declaring subtype is skipped in execute(), so
+        // no other pass emits it. No-op for a non-TPH entity (collectSubtypeFields is empty).
+        for (field in KotlinTphPlan.collectSubtypeFields(obj, loader)) {
+            if (field is EnumField && !Fr019SharedEnum.isProvidedEnumField(field))
+                KotlinEnumEmitter.emitEnumFile(obj, field, outRoot, emittedEnumFqns)
+        }
 
         val (pkg, shortName) = PackageMapping.splitFqn(obj.name)
         val serializable = ClassName("kotlinx.serialization", "Serializable")

server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinExposedTableGenerator.kt

@@ -82,6 +82,11 @@ open class KotlinExposedTableGenerator : MultiFileDirectGeneratorBase<MetaObject
                 entity.subType != MetaObject.SUBTYPE_PROJECTION) continue
             // Abstract entities are inheritance scaffolding — never emit a persistence table.
             if (KotlinGenUtil.isAbstractEntity(entity)) continue
+            // FR-017 TPH: a discriminator subtype folds into its base's single table — the base
+            // emits the union table. A per-subtype table would map the SAME physical table with
+            // a partial column set (a footgun). The subtype inherits source.rdb via extends, so
+            // the resolving lookup below would otherwise emit one — mirror the controller's skip.
+            if (KotlinTphPlan.isTphSubtype(entity)) continue
             // ADR-0039: resolving source lookup — an entity inheriting its source.rdb via
             // extends must still emit a table (own-only .children returned null → no table).
             val sourceRdb = KotlinGenUtil.firstRdbSource(entity) ?: continue
@@ -854,6 +859,10 @@ open class KotlinExposedTableGenerator : MultiFileDirectGeneratorBase<MetaObject
 
         for (entity in loader.metaObjects) {
             if (entity.subType != MetaObject.SUBTYPE_ENTITY) continue
+            // FR-017 TPH: a subtype shares its base's single table, so its INHERITED to-many
+            // composition is already covered by the base's inverse FK — emitting one per subtype
+            // would target the folded-away <Sub>Table. Mirror the table-emission skip.
+            if (KotlinTphPlan.isTphSubtype(entity)) continue
             // ADR-0039: relationships are inheritable — RESOLVE via entity.relationships;
             // entity.children (own-only) would miss an inherited relationship.
             for (child in entity.relationships) {

server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinFilterAllowlistGenerator.kt

@@ -55,6 +55,10 @@ open class KotlinFilterAllowlistGenerator : MultiFileDirectGeneratorBase<MetaObj
         val outRoot = Paths.get(outDir.absolutePath)
         for (entity in loader.metaObjects) {
             if (entity.subType != MetaObject.SUBTYPE_ENTITY) continue
+            // FR-017 TPH: a discriminator subtype folds into its base — the base's allowlist
+            // (unioned across subtype columns via isTphBase) is the only one the polymorphic
+            // controller uses; a per-subtype allowlist is dead. Mirror the controller/table skip.
+            if (KotlinTphPlan.isTphSubtype(entity)) continue
             // ADR-0039: resolving source lookup (inherited source.rdb via extends).
             val sourceRdb = KotlinGenUtil.firstRdbSource(entity) ?: continue
             // Only writable tables get a filter allowlist (the controller is also

server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinRelationsGenerator.kt

@@ -66,6 +66,10 @@ open class KotlinRelationsGenerator : MultiFileDirectGeneratorBase<MetaObject>()
             if (entity.subType != MetaObject.SUBTYPE_ENTITY) continue
             // Abstract entities are inheritance scaffolding — never emit relation helpers.
             if (KotlinGenUtil.isAbstractEntity(entity)) continue
+            // FR-017 TPH: a subtype folds into its base — its inherited relationships are emitted on
+            // the base's helper; a per-subtype helper would reference the missing <Sub>Table. Mirror
+            // the table/controller skip.
+            if (KotlinTphPlan.isTphSubtype(entity)) continue
             // No source.rdb → no persistence layer → no FK column to query against.
             // ADR-0039: resolving (an inherited source.rdb still means the entity is persisted).
             if (!KotlinGenUtil.hasRdbSource(entity)) continue

server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinValidatorGenerator.kt

@@ -40,6 +40,9 @@ open class KotlinValidatorGenerator : MultiFileDirectGeneratorBase<MetaObject>()
             .filter { it.subType == MetaObject.SUBTYPE_ENTITY }
             // Abstract entities are inheritance scaffolding — never register a validator for them.
             .filter { !KotlinGenUtil.isAbstractEntity(it) }
+            // FR-017 TPH: a subtype folds into its base's single table — never register a per-
+            // subtype table (it no longer exists). Mirror the table/controller skip.
+            .filter { !KotlinTphPlan.isTphSubtype(it) }
             // ADR-0039: resolving source lookup (inherited source.rdb via extends).
             .filter { KotlinGenUtil.hasRdbSource(it) }
             .map { entity ->

server/java/codegen-kotlin/src/test/kotlin/com/metaobjects/generator/kotlin/KotlinOutputCompilesTest.kt

@@ -55,6 +55,55 @@ class KotlinOutputCompilesTest {
       ] }
     }""".trimIndent()
 
+    // FR-017 TPH regression guard: a subtype's OWN field.enum (CopayAuth.tier) folds into the base
+    // Auth union data class, so the base must emit that enum class (owner = base) — else the union
+    // references a type no generated file defines. The subtypes themselves emit nothing.
+    private val tphSubtypeEnumFixture = """{
+      "metadata.root": { "package": "acme::auth", "children": [
+        { "object.entity": { "name": "Auth", "@discriminator": "type", "children": [
+            { "source.rdb":   { "@table": "auths" } },
+            { "field.long":   { "name": "id" } },
+            { "field.enum":   { "name": "type", "@values": ["Bridge", "Copay"] } },
+            { "identity.primary": { "@fields": "id", "@generation": "increment" } }
+        ] } },
+        { "object.entity": { "name": "BridgeAuth", "extends": "Auth", "@discriminatorValue": "Bridge", "children": [
+            { "field.int": { "name": "quantity", "@required": true } }
+        ] } },
+        { "object.entity": { "name": "CopayAuth", "extends": "Auth", "@discriminatorValue": "Copay", "children": [
+            { "field.enum": { "name": "tier", "@values": ["Standard", "Premium"] } }
+        ] } }
+      ] }
+    }""".trimIndent()
+
+    @Test fun `FR-017 TPH base union with a folded subtype enum compiles`() {
+        val outDir = Files.createTempDirectory("compile-tph-")
+        try {
+            val gen = KotlinEntityGenerator()
+            gen.setArgs(mapOf("outputDir" to outDir.toString()))
+            gen.execute(loadString("tph-test", tphSubtypeEnumFixture))
+
+            val emitted = Files.walk(outDir).filter { it.isRegularFile() }.sorted().toList()
+            val names = emitted.map { it.fileName.toString() }.toSet()
+            // The base emits the union + the discriminator enum + the folded subtype enum; the
+            // subtypes emit nothing (they fold into the base — the whole point of the skip).
+            assertTrue("AuthTier.kt" in names,
+                "the folded subtype enum (CopayAuth.tier) must be emitted by the base; got $names")
+            assertFalse(names.any { it.startsWith("BridgeAuth") || it.startsWith("CopayAuth") },
+                "TPH subtypes must emit no data class / enum of their own; got $names")
+
+            val result = KotlinCompilation().apply {
+                this.sources = emitted.map { SourceFile.kotlin(it.fileName.toString(), it.readText()) }
+                inheritClassPath = true
+                messageOutputStream = System.out
+            }.compile()
+
+            assertEquals(KotlinCompilation.ExitCode.OK, result.exitCode,
+                "TPH union with a folded subtype enum failed to compile:\n${result.messages}")
+        } finally {
+            outDir.toFile().deleteRecursively()
+        }
+    }
+
     @Test fun `generated Author kt compiles`() {
         val outDir = Files.createTempDirectory("compile-")
         try {

server/java/codegen-kotlin/src/test/resources/fixtures/entity-with-tph/config.json

@@ -1 +1 @@
-{ "generators": ["entity", "table", "controller", "filter-allowlist"] }
+{ "generators": ["entity", "table", "controller", "filter-allowlist", "validator", "relations"], "validatorPackage": "acme.auth.validation" }

server/java/codegen-kotlin/src/test/resources/fixtures/entity-with-tph/meta.json

@@ -10,6 +10,7 @@
           { "field.long":       { "name": "id", "@filterable": true, "@sortable": true } },
           { "field.enum":       { "name": "type", "@values": ["Bridge", "Copay", "PriorAuth"], "@filterable": true } },
           { "field.string":     { "name": "reference", "@required": true, "@maxLength": 80, "@filterable": true, "@sortable": true } },
+          { "relationship.composition": { "name": "lines", "@cardinality": "many", "@objectRef": "AuthLine", "@onDelete": "cascade" } },
           { "identity.primary": { "name": "id", "@fields": "id", "@generation": "increment" } }
         ]
       }},
@@ -36,6 +37,15 @@
         "children": [
           { "field.string": { "name": "priorAuthNumber", "@maxLength": 80, "@filterable": true, "@sortable": true } }
         ]
+      }},
+      { "object.entity": {
+        "name": "AuthLine",
+        "children": [
+          { "source.rdb":       { "@table": "auth_lines" } },
+          { "field.long":       { "name": "id" } },
+          { "field.string":     { "name": "label", "@maxLength": 40 } },
+          { "identity.primary": { "name": "id", "@fields": "id", "@generation": "increment" } }
+        ]
       }}
     ]
   }

server/java/codegen-kotlin/src/test/resources/snapshots/entity-with-tph/acme/auth/AuthLine.kt

@@ -0,0 +1,16 @@
+package acme.auth
+
+import jakarta.validation.constraints.Size
+import kotlin.Long
+import kotlin.String
+import kotlinx.serialization.Serializable
+
+/**
+ * GENERATED — do not hand-edit. Regenerated from metadata.
+ */
+@Serializable
+public data class AuthLine(
+  public val id: Long? = null,
+  @field:Size(max = 40)
+  public val label: String? = null,
+)