fix(kotlin): a required generated key blocked every create; conflicts 500'd; int-backed enum filters lied

Three defects in the generated Kotlin controller tier, found by building an
adopter estate's Kotlin backend from the published 8.0.5-rc.7 as the docs
describe - each with every in-repo lane green.

1. Create. The data class is also the create @RequestBody, and a @required
   generated key made it a non-null ctor param with no default:
   jackson-module-kotlin rejected every body that (correctly) omitted it, so
   every create 400'd on the shape real models have (BaseEntity declares id
   required). An increment key hid it - a missing Long binds 0 - a UUID
   cannot. Behind it: the handler read a @generation: uuid key back from the
   insert, which Exposed returns only for a value it inserted or an
   autoIncrement column ("id is not in record set"). Now a server-owned-on-
   create field (generated key, @autoset column) is nullable, default null,
   no @field:NotNull - KotlinGenUtil.isServerOwnedOnCreate, mirroring Java's
   SERVER_OWNED_ON_CREATE - and the handler mints a uuid key itself, as the
   TS runtime does.
2. Conflicts. handleConstraintViolation was declared for RuntimeException;
   Exposed raises ExposedSQLException, a CHECKED java.sql.SQLException, so it
   never matched and every duplicate key / dangling reference was a 500. It
   handles java.sql.SQLException too. Nothing had ever run it.
3. Int-backed enum filters. Every enum was compared as TEXT against the
   member symbol; an @intValueMap column stores the integer, so eq/in matched
   nothing and ne everything, with a 200. Now compared through the
   enum-typed column (whose codec writes the integer).

Docs: docs/ports/kotlin.md's install block could not build a running app -
it now lists exposed-jdbc (runtime), exposed-java-time and exposed-json (the
tables import them), and says the controller needs KotlinRelationsGenerator
when the model has M:N. The config generator no longer claims a validator
runs when validatorEnabled=false.

Tests: UuidPkControllerRunTest now makes the uuid key @required, POSTs
without it (201, generated id) and POSTs a duplicate unique name (409);
EnumFilterControllerRunTest gains an int-backed enum (eq/ne/in/unknown).
Both failed before the fix. codegen-kotlin 394/0 (3 snapshots updated),
integration-tests-kotlin 161/0; the estate's Kotlin port 43/43 on this build.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EaGv4zNk4oT7FooD4eK5MD

Author: dmealing

CHANGELOG.md

@@ -302,6 +302,46 @@ edit (two registered `description` strings) and was ruled a hold, as 1.0.4's was
   reference server and the Python in-memory seam ignored the filter and returned every row,
   and the TS reference server's allowlist gave the discriminator no operators.
 
+- **Kotlin: no POST could create an entity whose server-generated key is `@required` — and
+  a uuid key could not be created at all.** The generated data class is also the create
+  `@RequestBody`, and a `@required` key made it a non-null constructor parameter with no
+  default, so jackson-module-kotlin rejected every body that (correctly) omitted it: HTTP 400
+  on every create, for the shape every real model has (a shared `BaseEntity` declares `id`
+  required). An `increment` key hid it — a missing `Long` binds 0 — but a `UUID` cannot.
+  Behind that sat a second defect: the create handler read a `@generation: uuid` key back
+  from the insert, and Exposed returns only a value it inserted or an autoIncrement column,
+  so the key "is not in record set" on any driver that does not hand the database default
+  back. Now a SERVER-OWNED-on-create field — a generated key, or an `@autoSet` column the
+  handler stamps — is a nullable, default-null property with no `@field:NotNull` (the same
+  relaxation a derived field on a write-through entity already had), and the create handler
+  mints a uuid key itself, as the TypeScript runtime does. Rows read back always carry the
+  key. **Kotlin adopters with committed generated code should run `mvn metaobjects:generate`**;
+  code that read `entity.id` as non-null on such an entity now needs `!!` or a null check.
+  Found by an adopter estate's Kotlin backend.
+
+- **Kotlin: a database constraint violation answered 500, not the contract's 409.** The
+  generated `handleConstraintViolation` was declared for `RuntimeException`, and Exposed raises
+  a violation as `ExposedSQLException`, which extends the CHECKED `java.sql.SQLException` — so
+  the handler never matched and Spring answered every duplicate key and dangling reference with
+  a 500. It now handles `java.sql.SQLException` too. Nothing had run the handler: it existed
+  only in snapshots. **Run `mvn metaobjects:generate`.**
+
+- **Kotlin: filters on an int-backed enum (`@intValueMap`) returned the wrong rows with a
+  200.** The generated filter compared every enum column as TEXT against the member symbol,
+  which is right for a string-backed enum; an int-backed column stores the declared integer,
+  so `filter[status][eq]=DELIVERED` compared `'30'` to `'DELIVERED'` — `eq` and `in` matched
+  nothing and `ne` matched everything. The filter now compares through the enum-typed column,
+  whose codec writes the declared integer; a symbol naming no member matches no row. **Run
+  `mvn metaobjects:generate`.**
+
+- **Kotlin docs: the documented install block could not build a running app.** The generated
+  tables import `exposed-java-time` and `exposed-json`, and `Database.connect(...)` needs
+  `exposed-jdbc` at runtime; `docs/ports/kotlin.md` listed only `exposed-core`. Its generator
+  table now lists all three, and says the controller needs `KotlinRelationsGenerator` whenever
+  the model has a M:N relationship (the traversal routes call helpers only that generator
+  emits). A `KotlinSpringConfigGenerator` run with `validatorEnabled=false` no longer emits a
+  KDoc claiming the validator runs.
+
 - **Python runtime: a `field.currency` read from a view answered as a JSON STRING, not
   integer minor units.** A table's currency column is BIGINT, which the driver already hands
   back as an `int`. A view's need not be: `SUM` over BIGINT is Postgres `numeric`, read back

docs/ports/kotlin.md

@@ -39,6 +39,25 @@ Two modules:
     <artifactId>exposed-core</artifactId>
     <version>${exposed.version}</version>
   </dependency>
+  <!-- The generated tables import these two: instant (tz-aware timestamp) columns come from
+       exposed-java-time, jsonb columns from exposed-json. exposed-jdbc is what
+       `Database.connect(...)` needs at RUNTIME — without it the app starts and the first
+       query fails. -->
+  <dependency>
+    <groupId>org.jetbrains.exposed</groupId>
+    <artifactId>exposed-jdbc</artifactId>
+    <version>${exposed.version}</version>
+  </dependency>
+  <dependency>
+    <groupId>org.jetbrains.exposed</groupId>
+    <artifactId>exposed-java-time</artifactId>
+    <version>${exposed.version}</version>
+  </dependency>
+  <dependency>
+    <groupId>org.jetbrains.exposed</groupId>
+    <artifactId>exposed-json</artifactId>
+    <version>${exposed.version}</version>
+  </dependency>
   <!-- Generated typed `field.object @storage:jsonb` / `field.map` columns serialize through a
        generated per-package `MetaJsonbMapper.kt` Jackson `ObjectMapper` (no kotlinx-serialization
        compiler plugin required). -->
@@ -87,7 +106,7 @@ The 15 generators registered in `codegen-kotlin` (`GeneratorRegistry.kt`):
 | `KotlinValidatorGenerator` | `MetadataStartupValidator.kt` + `ExposedTableValidator.kt` | once per project |
 | `KotlinSpringConfigGenerator` | `MetadataExposedConfig.kt` — `@Configuration` wiring `Database.connect()` + auto-validator | once per project |
 | `KotlinStoredProcGenerator` | Stored-procedure call wrappers | entities with `source.rdb @kind="storedProc"` |
-| `KotlinSpringControllerGenerator` | `<Entity>Controller.kt` — Spring `@RestController` (5 CRUD endpoints; cross-port API contract) | entities with `source.rdb @kind="table"` |
+| `KotlinSpringControllerGenerator` | `<Entity>Controller.kt` — Spring `@RestController` (5 CRUD endpoints; cross-port API contract). **Select `KotlinRelationsGenerator` with it** when the model has a M:N relationship: the traversal routes call the `<rel>Query` helpers only that generator emits, and without it the controller does not compile | entities with `source.rdb @kind="table"` |
 
 Maven wiring:
 

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

@@ -198,7 +198,16 @@ open class KotlinEntityGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
             // An ASSIGNED primary key is create-REQUIRED whatever @required says — the
             // caller is its only source (KotlinGenUtil.isAssignedPrimaryKeyField), so the
             // property stays non-null and a create body omitting it cannot bind.
-            val nullable = tphBase || derivedReadOnly ||
+            // A SERVER-OWNED-on-create field — the key an increment/uuid identity generates, or an
+            // @autoSet column the CRUD path stamps — is never the caller's to send, and this one data
+            // class is also the create @RequestBody. As a non-null param with no default it fails
+            // jackson-module-kotlin deserialization on a body that correctly omits it, so EVERY
+            // create answered 400 on an entity whose BaseEntity declares `id` @required — the shape
+            // real models have. (A missing `Long` silently binds 0, which is how an increment key
+            // hid it; a `UUID` cannot.) Same relaxation as a derived field on a write-through
+            // entity: nullable, default null, no @field:NotNull. Rows read back always carry it.
+            val serverOwned = KotlinGenUtil.isServerOwnedOnCreate(field, obj)
+            val nullable = tphBase || derivedReadOnly || serverOwned ||
                 (!KotlinGenUtil.isRequiredField(field) && !KotlinGenUtil.originGuaranteedNonNull(field)
                     && !KotlinGenUtil.isAssignedPrimaryKeyField(field))
             val propType = if (nullable) baseType.copy(nullable = true) else baseType
@@ -208,7 +217,7 @@ open class KotlinEntityGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
                 .build()
             ctorBuilder.addParameter(param)
             val propBuilder = PropertySpec.builder(propName, propType).initializer(propName)
-            if (!tphBase && !derivedReadOnly) {
+            if (!tphBase && !derivedReadOnly && !serverOwned) {
                 for (annotation in validationAnnotations(field)) {
                     propBuilder.addAnnotation(annotation)
                 }

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

@@ -634,6 +634,31 @@ public object KotlinGenUtil {
         return !field.hasMetaAttr(MetaField.ATTR_DEFAULT)
     }
 
+    /**
+     * True when [field] is SERVER-OWNED on create for [obj]: a component of [obj]'s
+     * `increment`/`uuid` primary key (the store generates it), or an `@autoSet` column (the
+     * CRUD path stamps it, issue #203). The caller never supplies either, so a create body
+     * that omits one is correct — the complement of [isAssignedPrimaryKeyField]. Judged
+     * against the entity being generated, not `field.parent`: a key idiomatically lives on
+     * an abstract base and is inherited through `extends`.
+     *
+     * Mirrors the Java port's `SERVER_OWNED_ON_CREATE` set (SpringControllerGenerator).
+     */
+    fun isServerOwnedOnCreate(field: MetaField<*>, obj: MetaObject): Boolean {
+        val pk = obj.primaryIdentity
+        if (pk != null && pk.isAutoGenerated && pk.fields.contains(field.name)) return true
+        return autoSetPolicy(field) != null
+    }
+
+    /**
+     * True when [field] is a `field.enum` stored as its declared INTEGER (`@intValueMap`) rather
+     * than its member symbol. Read resolving (ADR-0039) — the same test the Exposed table
+     * generator applies when it emits the INTEGER `customEnumeration` column, so the column and
+     * the filter that reads it cannot disagree.
+     */
+    fun isIntBackedEnum(field: MetaField<*>): Boolean =
+        field is com.metaobjects.field.EnumField && field.hasMetaAttr(com.metaobjects.field.EnumField.ATTR_INT_VALUE_MAP)
+
     fun isRequiredField(field: MetaField<*>): Boolean {
         if (!field.hasMetaAttr(MetaField.ATTR_REQUIRED, true)) return false
         val raw = runCatching { field.getMetaAttr(MetaField.ATTR_REQUIRED, true).value }.getOrNull()

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

@@ -60,10 +60,17 @@ open class KotlinSpringConfigGenerator : MultiFileDirectGeneratorBase<MetaObject
 
         val typeBuilder = TypeSpec.classBuilder(className)
             .addKdoc(
-                "GENERATED — wires Exposed's `Database.connect()` from the Spring " +
-                    "[DataSource] bean\nand runs [MetadataStartupValidator.validate] at " +
-                    "app startup.\n\nIf you don't want the validator auto-call, set " +
-                    "`metaobjects.validator.enabled=false`.\n"
+                if (validatorEnabled) {
+                    "GENERATED — wires Exposed's `Database.connect()` from the Spring " +
+                        "[DataSource] bean\nand runs [MetadataStartupValidator.validate] at " +
+                        "app startup.\n\nIf you don't want the validator auto-call, set " +
+                        "`metaobjects.validator.enabled=false`.\n"
+                } else {
+                    // Generated with validatorEnabled=false: no validator hook is emitted, so the
+                    // KDoc must not say one runs.
+                    "GENERATED — wires Exposed's `Database.connect()` from the Spring " +
+                        "[DataSource] bean.\n"
+                }
             )
             .addAnnotation(CONFIGURATION)
             .primaryConstructor(