feat(fr-035): present-key PATCH tristate — Kotlin port (completes all 5 ports)

Green the cross-port `update-explicit-null-clears` gate on Kotlin (both lanes),
completing FR-035 Part B across TS / Python / C# / Java / Kotlin. The generated
controller bound `@Valid @RequestBody dto: <Entity>` (a non-null-ctor data class),
so a partial PATCH omitting a @required field 400'd at Jackson binding and an
explicit null was a silent no-op. Rebind the update handler off the typed data
class onto the raw JSON tree — minimal inline, NOT the repo-delegation refactor:

- codegen-kotlin: the non-TPH `<Entity>Controller` constructor-injects an
  `ObjectMapper` (only when it has settable scalar fields — a PK+object/jsonb-only
  entity keeps a no-arg controller, so no unused-param `-Werror` break) and the
  update handler binds `@RequestBody body: JsonNode`. Per body key: a non-object
  body → 400; an explicit null on a @required field → 400; a present value binds
  through the configured `ObjectMapper` (`treeToValue` with a `TypeReference` so
  boxing / generics / inline enums survive) and per-field-dispatches into the
  inline Exposed `update {}` (required → typed local; nullable → `if (n.isNull)
  it[Table.col]=null else …`); an absent key is untouched; an effectively-empty
  patch is a no-op read-back. Columns are qualified `it[Table.col]` (a field named
  like the `body` param would otherwise shadow the column). A value whose JSON
  shape can't bind → 400 (JsonMappingException), matching create, not a 500.
- reference server + KNOWN_GAPS + `PatchTristateEdgeCasesTest` (no-settable-field
  controller emits no ObjectMapper/TypeReference; `PATCH {"name":{…}}` → 400).

Known gaps (KNOWN_GAPS.md, cross-port PATCH-4 follow-ups): (1) present-VALUE
constraint validation (@Size/@Pattern/@notblank) is not run on PATCH values (only
null-on-@required → 400) — matches C#/Java; TS/Python enforce it. (2) a
`field.string @dbColumnType:jsonb` open bag is a create-only column (kotlinx
JsonElement can't bind on the raw-JsonNode PATCH path without tripping the #179
open-bag guard) — PATCH leaves it untouched.

Gate green both Kotlin lanes (generated 23/0; reference 23/0 — the reference lane
occasionally flakes on PG-testcontainer readiness under load, a known
environmental issue, not a code failure); codegen-kotlin 48 reports / 0 failures;
jsonb 1/0 both, m2m 3/0 both, tph generated 5/0, enum/uuid run-tests green.
Generated Kotlin compiles under allWarningsAsErrors.

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

Author: dmealing

server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KNOWN_GAPS.md

@@ -46,3 +46,25 @@ byte-identical to the Java port by construction.
     `metaobjects-om` (which transitively brings `render` + `metadata`) and
     `com.metaobjects.loader.MetaDataLoader`. Consumers wanting nested extraction must have
     `metaobjects-om` on the classpath.
+
+## FR-035 partial-PATCH (present-key tristate)
+
+The generated `@RestController`'s PATCH/PUT handler binds the raw `JsonNode` and
+per-field-binds present values via the Spring `ObjectMapper` (absent → untouched;
+explicit null → clears a nullable column or 400 on a `@required` field; present
+value → set). Two deliberate gaps:
+
+- **Present-value constraint validation** is NOT run on PATCH. Dropping `@Valid`
+  means `@Size` / `@Pattern` / `@NotBlank` / `@Min` / `@Max` (emitted by
+  `validationAnnotations`) no longer fire on a PATCH body's present values — only a
+  present-null-on-`@required` → 400. This matches the C#/Java partial-PATCH state; TS
+  and Python DO validate present values on PATCH. A cross-port PATCH-4 follow-up.
+- **`field.string @dbColumnType=jsonb` open-bag** is a **create-only** column on the
+  generated CRUD. The generated `create` writes it (bound from the `@Valid` DTO's
+  kotlinx `JsonElement` property — exercised by the `jsonb-open-bag-roundtrip` corpus),
+  but the generated `update` does NOT: the raw-JsonNode patch path cannot bind a kotlinx
+  `JsonElement` via Jackson `treeToValue`, and the type name must not surface
+  un-imported in the controller (the #179 filter/sort guard). So a `PATCH` leaves an
+  open-bag column untouched. A consumer needing to PATCH an open-bag column overrides
+  the generated update handler. Typed value-object jsonb (`field.object`) is
+  object-typed and separately out of the CRUD DTO scope.

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

@@ -151,6 +151,19 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
         val pkFieldName = primary?.fields?.firstOrNull() ?: DEFAULT_PK_FIELD
         val pkParamType = primaryKeyParamType(entity, pkFieldName)
 
+        // FR-035: the PATCH-settable columns = scalar fields minus the PK. ObjectField / MapField
+        // (jsonb value-objects) and the `field.string @dbColumnType=jsonb` open bag are excluded:
+        // their in-process type is a kotlinx JsonElement / VO with no clean Jackson treeToValue
+        // bind on the raw-JsonNode patch path. (create DOES write the open bag from the DTO;
+        // an open bag is thus a create-only CRUD column — see KNOWN_GAPS.)
+        // When this is EMPTY (a PK + only object/map/jsonb columns) the controller emits no
+        // ObjectMapper ctor param / TypeReference import (they'd be unused → allWarningsAsErrors).
+        val patchSettableFields = entity.metaFields.filter {
+            it !is ObjectField && it !is MapField && it.name != pkFieldName &&
+                !KotlinTypeMapper.isJsonbOpenBag(it)
+        }
+        val hasPatchFields = patchSettableFields.isNotEmpty()
+
         // Sort allowlist: every scalar field is sortable. Skip ObjectField (no SQL column
         // surface on the Exposed Table; @storage controls a separate column shape) and the
         // `field.string @dbColumnType=jsonb` open bag — a JSONB value is not a scalar sort
@@ -190,6 +203,14 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
             append("import org.jetbrains.exposed.sql.selectAll\n")
             append("import org.jetbrains.exposed.sql.update\n")
             append("import org.jetbrains.exposed.sql.transactions.transaction\n")
+            append("import com.fasterxml.jackson.databind.JsonNode\n")
+            // ObjectMapper + TypeReference are used ONLY by the per-field patch bind, which is
+            // emitted only when there ARE settable fields — omit them otherwise (unused import /
+            // ctor param would fail the module's allWarningsAsErrors compile).
+            if (hasPatchFields) {
+                append("import com.fasterxml.jackson.core.type.TypeReference\n")
+                append("import com.fasterxml.jackson.databind.ObjectMapper\n")
+            }
             append("import jakarta.validation.Valid\n")
             append("import org.springframework.http.HttpStatus\n")
             append("import org.springframework.http.ResponseEntity\n")
@@ -284,7 +305,15 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
             append("/** GENERATED — REST controller for ${shortName} entity. Implements the cross-port API contract. */\n")
             append("@RestController\n")
             append("@RequestMapping(\"$routeBase\")\n")
-            append("class ${shortName}Controller {\n\n")
+            // FR-035 present-key PATCH: the update handler binds the RAW JsonNode (not the
+            // @Valid data class, which cannot see absent-vs-null) and per-field-binds present
+            // values via the Spring-configured ObjectMapper — injected only when there ARE
+            // settable fields (a PK + only object/jsonb columns needs no mapper).
+            if (hasPatchFields) {
+                append("class ${shortName}Controller(private val objectMapper: ObjectMapper) {\n\n")
+            } else {
+                append("class ${shortName}Controller {\n\n")
+            }
 
             // List handler — pagination + sort + withCount + FR-009 filter operators.
             //
@@ -341,6 +370,11 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
                 // If the entity has no auto-incrementing PK the consumer can override the
                 // generated handler; this is the 95% case.
                 if (field.name == pkFieldName) continue
+                // NOTE: a `field.string @dbColumnType=jsonb` open bag IS written here (create
+                // binds it from the @Valid DTO's kotlinx JsonElement property, gated by the
+                // jsonb-open-bag-roundtrip corpus). PATCH cannot (the raw-JsonNode path can't bind
+                // a JsonElement without surfacing the un-imported type the #179 guard forbids), so
+                // an open bag is a create-only column on the generated CRUD — see KNOWN_GAPS.
                 append("            it[${field.name}] = dto.${field.name}\n")
             }
             append("        }[${tableObjectName}.${pkFieldName}]\n")
@@ -353,31 +387,57 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
             // Stacking @PatchMapping + @PutMapping on the same method does NOT register both
             // in Spring MVC — only one composed @RequestMapping per method is honored, so the
             // other verb 405s. (Surfaced by the SP-F generated-controller HTTP lane.)
+            // FR-035 present-key tristate: bind the RAW JsonNode so absent-vs-null is visible.
+            // A non-object body, or an explicit null on a @required field, is a 400; an explicit
+            // null on a nullable field CLEARS it; an omitted field is untouched; a present value
+            // binds through the configured ObjectMapper (same codecs as create). An empty
+            // effective patch is a no-op read-back (avoids Exposed's empty-SET error).
+            // Settable columns are `patchSettableFields` (computed up top): scalar fields minus
+            // the PK, EXCLUDING object/map/jsonb-open-bag (an open bag is a create-only CRUD
+            // column — PATCH can't bind a kotlinx JsonElement; see KNOWN_GAPS). When empty, no
+            // update{} block is emitted (an empty Exposed SET throws) — a no-op read-back.
             append("    @RequestMapping(value = [\"/{id}\"], method = [RequestMethod.PATCH, RequestMethod.PUT])\n")
-            append("    fun update(@PathVariable id: $pkParamType, @Valid @RequestBody dto: ${shortName}): ResponseEntity<Any> = transaction {\n")
-            append("        val updated = ${tableObjectName}.update({ ${tableObjectName}.${pkFieldName} eq id }) {\n")
-            for (field in entity.metaFields) {
-                if (field is ObjectField || field is MapField) continue
-                if (field.name == pkFieldName) continue
-                // Partial merge: an OPTIONAL field omitted from a PATCH must not clobber the
-                // stored value. Optional DTO props are nullable + default to null, so absent
-                // reads as null here — null-guard them (the same merge the TPH per-subtype
-                // handler uses). Required props are non-null (Jackson rejects a body missing
-                // them with a 400 before this runs), so they are always present → written
-                // unconditionally. Guarding a non-null prop would be an always-true warning
-                // and break -Werror consumers. (Explicit-null-clears is the deferred tristate.)
+            append("    fun update(@PathVariable id: $pkParamType, @RequestBody body: JsonNode): ResponseEntity<Any> = transaction {\n")
+            append("        if (!body.isObject) return@transaction ResponseEntity.badRequest().body(mapOf(\"error\" to \"validation\") as Any)\n")
+            for (field in patchSettableFields) {
                 if (KotlinGenUtil.isRequiredField(field)) {
-                    append("            it[${field.name}] = dto.${field.name}\n")
-                } else {
-                    append("            if (dto.${field.name} != null) it[${field.name}] = dto.${field.name}\n")
+                    append("        if (body.has(\"${field.name}\") && body.get(\"${field.name}\").isNull) return@transaction ResponseEntity.badRequest().body(mapOf(\"error\" to \"validation\") as Any)\n")
                 }
             }
-            append("        }\n")
-            append("        if (updated == 0) ResponseEntity.status(HttpStatus.NOT_FOUND).body(mapOf(\"error\" to \"not_found\") as Any)\n")
-            append("        else {\n")
-            append("            val row = ${tableObjectName}.selectAll().where { ${tableObjectName}.${pkFieldName} eq id }.single()\n")
-            append("            ResponseEntity.ok(rowTo${shortName}(row) as Any)\n")
-            append("        }\n")
+            if (hasPatchFields) {
+                val settableNamesList = patchSettableFields.joinToString(", ") { "\"${it.name}\"" }
+                append("        if (listOf($settableNamesList).any { body.has(it) }) {\n")
+                // A present value that cannot bind to its column's Kotlin type (e.g. a JSON object
+                // for a String column) throws from treeToValue INSIDE the statement build — map
+                // that to 400 (the create @Valid path 400s the same value), not a 500. Catch the
+                // specific Jackson JsonMappingException so no unrelated exception is swallowed.
+                append("            try {\n")
+                append("                ${tableObjectName}.update({ ${tableObjectName}.${pkFieldName} eq id }) {\n")
+                for (field in patchSettableFields) {
+                    // The DATA-CLASS element type (a field.enum's materialized enum class, not the
+                    // wire String) so the bound value matches the Exposed Column<E>. Columns are
+                    // qualified (`Table.col`) so a field named like the `body` param can't shadow them.
+                    val elem = KotlinTypeMapper.enumTypeName(field, entity) ?: KotlinTypeMapper.kotlinTypeName(field)
+                    val ktType = if (field.isArrayType) "kotlin.collections.List<$elem>" else "$elem"
+                    val col = "$tableObjectName.${field.name}"
+                    // A typed local coerces the ObjectMapper's platform return type to the exact
+                    // column type (matching the data-class property the old handler assigned) so
+                    // Exposed's set() overload resolves for enum / EntityID-FK columns too.
+                    if (KotlinGenUtil.isRequiredField(field)) {
+                        append("                    if (body.has(\"${field.name}\")) { val v: $ktType = objectMapper.treeToValue(body.get(\"${field.name}\"), object : TypeReference<$ktType>() {}); it[$col] = v }\n")
+                    } else {
+                        append("                    if (body.has(\"${field.name}\")) { val n = body.get(\"${field.name}\"); if (n.isNull) it[$col] = null else { val v: $ktType = objectMapper.treeToValue(n, object : TypeReference<$ktType>() {}); it[$col] = v } }\n")
+                    }
+                }
+                append("                }\n")
+                append("            } catch (e: com.fasterxml.jackson.databind.JsonMappingException) {\n")
+                append("                return@transaction ResponseEntity.badRequest().body(mapOf(\"error\" to \"validation\") as Any)\n")
+                append("            }\n")
+                append("        }\n")
+            }
+            append("        val row = ${tableObjectName}.selectAll().where { ${tableObjectName}.${pkFieldName} eq id }.singleOrNull()\n")
+            append("        if (row == null) ResponseEntity.status(HttpStatus.NOT_FOUND).body(mapOf(\"error\" to \"not_found\") as Any)\n")
+            append("        else ResponseEntity.ok(rowTo${shortName}(row) as Any)\n")
             append("    }\n\n")
 
             // DELETE — Exposed's `deleteWhere` is an extension fn on Table; the import

server/java/codegen-kotlin/src/test/resources/snapshots/entity-with-controller/acme/blog/AuthorController.kt

@@ -10,6 +10,9 @@ import org.jetbrains.exposed.sql.insert
 import org.jetbrains.exposed.sql.selectAll
 import org.jetbrains.exposed.sql.update
 import org.jetbrains.exposed.sql.transactions.transaction
+import com.fasterxml.jackson.databind.JsonNode
+import com.fasterxml.jackson.core.type.TypeReference
+import com.fasterxml.jackson.databind.ObjectMapper
 import jakarta.validation.Valid
 import org.springframework.http.HttpStatus
 import org.springframework.http.ResponseEntity
@@ -232,7 +235,7 @@ private fun rowToAuthor(row: ResultRow): Author = Author(
 /** GENERATED — REST controller for Author entity. Implements the cross-port API contract. */
 @RestController
 @RequestMapping("/api/authors")
-class AuthorController {
+class AuthorController(private val objectMapper: ObjectMapper) {
 
     @GetMapping
     fun list(
@@ -280,15 +283,21 @@ class AuthorController {
     }
 
     @RequestMapping(value = ["/{id}"], method = [RequestMethod.PATCH, RequestMethod.PUT])
-    fun update(@PathVariable id: Long, @Valid @RequestBody dto: Author): ResponseEntity<Any> = transaction {
-        val updated = AuthorTable.update({ AuthorTable.id eq id }) {
-            it[name] = dto.name
-        }
-        if (updated == 0) ResponseEntity.status(HttpStatus.NOT_FOUND).body(mapOf("error" to "not_found") as Any)
-        else {
-            val row = AuthorTable.selectAll().where { AuthorTable.id eq id }.single()
-            ResponseEntity.ok(rowToAuthor(row) as Any)
+    fun update(@PathVariable id: Long, @RequestBody body: JsonNode): ResponseEntity<Any> = transaction {
+        if (!body.isObject) return@transaction ResponseEntity.badRequest().body(mapOf("error" to "validation") as Any)
+        if (body.has("name") && body.get("name").isNull) return@transaction ResponseEntity.badRequest().body(mapOf("error" to "validation") as Any)
+        if (listOf("name").any { body.has(it) }) {
+            try {
+                AuthorTable.update({ AuthorTable.id eq id }) {
+                    if (body.has("name")) { val v: kotlin.String = objectMapper.treeToValue(body.get("name"), object : TypeReference<kotlin.String>() {}); it[AuthorTable.name] = v }
+                }
+            } catch (e: com.fasterxml.jackson.databind.JsonMappingException) {
+                return@transaction ResponseEntity.badRequest().body(mapOf("error" to "validation") as Any)
+            }
         }
+        val row = AuthorTable.selectAll().where { AuthorTable.id eq id }.singleOrNull()
+        if (row == null) ResponseEntity.status(HttpStatus.NOT_FOUND).body(mapOf("error" to "not_found") as Any)
+        else ResponseEntity.ok(rowToAuthor(row) as Any)
     }
 
     @DeleteMapping("/{id}")

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

@@ -10,6 +10,9 @@ import org.jetbrains.exposed.sql.insert
 import org.jetbrains.exposed.sql.selectAll
 import org.jetbrains.exposed.sql.update
 import org.jetbrains.exposed.sql.transactions.transaction
+import com.fasterxml.jackson.databind.JsonNode
+import com.fasterxml.jackson.core.type.TypeReference
+import com.fasterxml.jackson.databind.ObjectMapper
 import jakarta.validation.Valid
 import org.springframework.http.HttpStatus
 import org.springframework.http.ResponseEntity
@@ -232,7 +235,7 @@ private fun rowToAuthLine(row: ResultRow): AuthLine = AuthLine(
 /** GENERATED — REST controller for AuthLine entity. Implements the cross-port API contract. */
 @RestController
 @RequestMapping("/api/authlines")
-class AuthLineController {
+class AuthLineController(private val objectMapper: ObjectMapper) {
 
     @GetMapping
     fun list(
@@ -280,15 +283,20 @@ class AuthLineController {
     }
 
     @RequestMapping(value = ["/{id}"], method = [RequestMethod.PATCH, RequestMethod.PUT])
-    fun update(@PathVariable id: Long, @Valid @RequestBody dto: AuthLine): ResponseEntity<Any> = transaction {
-        val updated = AuthLineTable.update({ AuthLineTable.id eq id }) {
-            if (dto.label != null) it[label] = dto.label
-        }
-        if (updated == 0) ResponseEntity.status(HttpStatus.NOT_FOUND).body(mapOf("error" to "not_found") as Any)
-        else {
-            val row = AuthLineTable.selectAll().where { AuthLineTable.id eq id }.single()
-            ResponseEntity.ok(rowToAuthLine(row) as Any)
+    fun update(@PathVariable id: Long, @RequestBody body: JsonNode): ResponseEntity<Any> = transaction {
+        if (!body.isObject) return@transaction ResponseEntity.badRequest().body(mapOf("error" to "validation") as Any)
+        if (listOf("label").any { body.has(it) }) {
+            try {
+                AuthLineTable.update({ AuthLineTable.id eq id }) {
+                    if (body.has("label")) { val n = body.get("label"); if (n.isNull) it[AuthLineTable.label] = null else { val v: kotlin.String = objectMapper.treeToValue(n, object : TypeReference<kotlin.String>() {}); it[AuthLineTable.label] = v } }
+                }
+            } catch (e: com.fasterxml.jackson.databind.JsonMappingException) {
+                return@transaction ResponseEntity.badRequest().body(mapOf("error" to "validation") as Any)
+            }
         }
+        val row = AuthLineTable.selectAll().where { AuthLineTable.id eq id }.singleOrNull()
+        if (row == null) ResponseEntity.status(HttpStatus.NOT_FOUND).body(mapOf("error" to "not_found") as Any)
+        else ResponseEntity.ok(rowToAuthLine(row) as Any)
     }
 
     @DeleteMapping("/{id}")

server/java/integration-tests-kotlin/src/test/kotlin/com/metaobjects/integration/kotlin/api/AuthorApiServer.kt

@@ -197,6 +197,12 @@ class AuthorApiServer(private val pg: PostgresContainer) : AutoCloseable {
         @Suppress("UNCHECKED_CAST")
         val body = readJsonBody(exchange) as? Map<String, Any?>
             ?: return sendJson(exchange, 400, mapOf("error" to "validation"))
+        // FR-035 PATCH-2: an explicit null on a @required field (name / createdAt, per
+        // meta.json) is a 400 — a present null on the nullable bio clears it, and an
+        // omitted required field is untouched (never a 400).
+        for (f in listOf("name", "createdAt")) {
+            if (body.containsKey(f) && body[f] == null) return sendJson(exchange, 400, mapOf("error" to "validation"))
+        }
         val updated = transaction(db) {
             AuthorTable.update({ AuthorTable.id eq id }) {
                 (body["name"] as? String)?.let { v -> it[name] = v }

server/java/integration-tests-kotlin/src/test/kotlin/com/metaobjects/integration/kotlin/api/generated/EnumFilterControllerRunTest.kt

@@ -89,7 +89,7 @@ class EnumFilterControllerRunTest {
                 "jdbc:h2:mem:enum_filter;DB_CLOSE_DELAY=-1;MODE=PostgreSQL", driver = "org.h2.Driver")
             transaction(db) { SchemaUtils.create(widgetTable) }
 
-            val controller = controllerClass.getDeclaredConstructor().newInstance()
+            val controller = controllerClass.getDeclaredConstructor(ObjectMapper::class.java).newInstance(mapper)
             val converter = MappingJackson2HttpMessageConverter().apply { objectMapper = mapper }
             val mvc = MockMvcBuilders.standaloneSetup(controller).setMessageConverters(converter).build()