feat(program-d): Kotlin codegen reads/creates/PATCHes value-object jsonb columns

The generated controller excluded ObjectField from read (rowToEntity), create,
and PATCH — VO jsonb columns were invisible. Now included everywhere:
- patchSettableFields drops the ObjectField exclusion (MapField + jsonb-open-bag
  stay excluded — staged out); rowToEntity + the create insert loop include VO
  columns (the Exposed Column<VO> codec / shared Jackson metaJsonbMapper handles
  the jsonb text <-> VO record / List<VO>).
- PATCH binds a present VO via objectMapper.treeToValue (Jackson, NOT the
  decorative kotlinx serializer) into the VO record / List<VO>, resolved by a new
  voElementTypeFqn helper, then validates: keeps validateValue for own constraints
  and ADDS explicit validator.validate(voElement) per present element (spec
  section 0 — validateValue does not cascade @Valid). FR-035 tristate preserved.
- KotlinEntityGenerator stamps @field:jakarta.validation.Valid on nested VO members
  so validate(dto) cascades on POST (golden snapshot User.kt reconciled).

Both lanes green (reference Exposed + generated MockMvc, over Testcontainers PG);
codegen-kotlin 280/0; typed-jsonb roundtrip 1/1 — no regression. field.map and the
Kotlin open-bag PATCH remain staged-out follow-ups.

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/KotlinEntityGenerator.kt

@@ -154,6 +154,14 @@ open class KotlinEntityGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
                 for (annotation in validationAnnotations(field)) {
                     propBuilder.addAnnotation(annotation)
                 }
+                // Program D (spec §0): a field.object (value-object) member carries @field:Valid so a
+                // parent validator.validate(bean) / @Valid cascades into the nested VO's own
+                // constraints (the create-body POST path). jakarta validateValue does NOT cascade, so
+                // the PATCH path validates present VO values explicitly in the controller. MapField is
+                // NOT an ObjectField (dict-of-VO is staged out), so it never gets @Valid here.
+                if (field is ObjectField) {
+                    propBuilder.addAnnotation(constraint(VALID))
+                }
             }
             typeBuilder.addProperty(propBuilder.build())
         }
@@ -506,6 +514,11 @@ open class KotlinEntityGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
         val MAX = ClassName(JAKARTA_CONSTRAINTS, "Max")
         val EMAIL = ClassName(JAKARTA_CONSTRAINTS, "Email")
 
+        /** Program D: `@field:Valid` on a value-object member so a parent `@Valid` / whole-bean
+         *  validate cascades into the nested VO's own constraints (lives in `jakarta.validation`,
+         *  NOT `jakarta.validation.constraints`). */
+        val VALID = ClassName("jakarta.validation", "Valid")
+
         /**
          * Canonical DNS-hostname matcher for `@stringFormat: hostname` (ADR-0036/0037 Wave 3).
          * Codegen-owned (NOT author `validator.regex`) — one or more dot-separated labels, each

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

@@ -151,15 +151,16 @@ 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).
+        // FR-035: the PATCH-settable columns = scalar + value-object fields minus the PK. Program D:
+        // a field.object value-object jsonb column IS settable — bound via Jackson treeToValue into
+        // the generated VO record / List<VO> and validated (spec §0). Still EXCLUDED: MapField
+        // (dict-of-VO, staged out) and the `field.string @dbColumnType=jsonb` open bag (its
+        // in-process type is a kotlinx JsonElement the raw-JsonNode patch path can't bind — a
+        // create-only column, see KNOWN_GAPS).
+        // When this is EMPTY (a PK + only map/open-bag 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 &&
+            it !is MapField && it.name != pkFieldName &&
                 !KotlinTypeMapper.isJsonbOpenBag(it)
         }
         val hasPatchFields = patchSettableFields.isNotEmpty()
@@ -293,14 +294,16 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
             //      type at compile time (no reflection / runtime cast surprises).
             emitFilterPipeline(this, shortName, tableObjectName, allowlistName, scalarFields)
 
-            // rowTo<Entity>: ResultRow → data class. Scalar fields only; ObjectField is
-            // skipped here for the same reason as the sort allowlist (the Table object's
-            // jsonb/flattened column shape would require type-specific deserialization
-            // which is generator-future work).
+            // rowTo<Entity>: ResultRow → data class. Program D: a field.object value-object jsonb
+            // column IS read here — the Exposed Column<VO> codec (the shared Jackson metaJsonbMapper)
+            // already decodes the jsonb text to the VO record / List<VO>, so `row[Table.col]` yields
+            // the typed value the data-class property expects. MapField (dict-of-VO) stays skipped
+            // (staged out). The `field.string @dbColumnType=jsonb` open bag is a StringField, so it is
+            // read here too (its column decodes to a kotlinx JsonElement).
             append("/** GENERATED — map an Exposed ResultRow to the ${shortName} data class. */\n")
             append("private fun rowTo${shortName}(row: ResultRow): ${shortName} = ${shortName}(\n")
             for (field in entity.metaFields) {
-                if (field is ObjectField || field is MapField) continue
+                if (field is MapField) continue
                 append("    ${field.name} = row[${tableObjectName}.${field.name}],\n")
             }
             append(")\n\n")
@@ -373,7 +376,10 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
             append("        if (validator.validate(dto).isNotEmpty()) return@transaction ResponseEntity.badRequest().body(mapOf(\"error\" to \"validation\") as Any)\n")
             append("        val newId = ${tableObjectName}.insert {\n")
             for (field in entity.metaFields) {
-                if (field is ObjectField || field is MapField) continue
+                // Program D: a field.object value-object jsonb column IS written on create — the
+                // DTO property is the typed VO (record / List<VO>) and the Exposed Column<VO> codec
+                // encodes it to jsonb. MapField (dict-of-VO) stays skipped (staged out).
+                if (field is MapField) continue
                 // Skip the PK column on insert — the table's @generation=increment owns it.
                 // If the entity has no auto-incrementing PK the consumer can override the
                 // generated handler; this is the 95% case.
@@ -400,10 +406,11 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
             // 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.
+            // Settable columns are `patchSettableFields` (computed up top): scalar + value-object
+            // fields minus the PK, EXCLUDING map/jsonb-open-bag (an open bag is a create-only CRUD
+            // column — PATCH can't bind a kotlinx JsonElement; see KNOWN_GAPS). Program D: a present
+            // field.object VO binds via Jackson treeToValue and is validated in FULL (spec §0).
+            // 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, @RequestBody body: JsonNode): ResponseEntity<Any> = transaction {\n")
             append("        if (!body.isObject) return@transaction ResponseEntity.badRequest().body(mapOf(\"error\" to \"validation\") as Any)\n")
@@ -427,10 +434,17 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
                 // @required field was already 400'd above; present-null on a nullable field clears it
                 // (no bind, no validation).
                 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>.
-                    val elem = KotlinTypeMapper.enumTypeName(field, entity) ?: KotlinTypeMapper.kotlinTypeName(field)
-                    val ktType = if (field.isArrayType) "kotlin.collections.List<$elem>" else "$elem"
+                    // The DATA-CLASS element type: a field.enum's materialized enum class; a
+                    // field.object's referenced value-object record (Program D — bound via Jackson
+                    // treeToValue into the VO / List<VO>); else the scalar Kotlin type — so the bound
+                    // value matches the Exposed Column<E>. A VO type is emitted fully-qualified so the
+                    // controller needs no extra import (mirrors the Exposed column codec).
+                    val elem: String = if (field is ObjectField) {
+                        voElementTypeFqn(field, loader)
+                    } else {
+                        (KotlinTypeMapper.enumTypeName(field, entity) ?: KotlinTypeMapper.kotlinTypeName(field)).toString()
+                    }
+                    val ktType = if (field.isArrayType) "kotlin.collections.List<$elem>" else elem
                     val fn = field.name
                     val cap = capitalizeFirst(fn)
                     append("                val has$cap = body.has(\"$fn\")\n")
@@ -443,6 +457,17 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
                         append("                val v$cap: $ktType? = if (has$cap && !null$cap) objectMapper.treeToValue(body.get(\"$fn\"), object : TypeReference<$ktType>() {}) else null\n")
                         append("                if (has$cap && !null$cap && validator.validateValue(${shortName}::class.java, \"$fn\", v$cap).isNotEmpty()) return@transaction ResponseEntity.badRequest().body(mapOf(\"error\" to \"validation\") as Any)\n")
                     }
+                    // Program D (spec §0): jakarta validateValue does NOT cascade @Valid into a nested
+                    // value-object's constraints, so a present VO is validated EXPLICITLY —
+                    // validator.validate(voElement) per element (single VO whole; array VO per element),
+                    // 400 on any violation. (A present-null / cleared value is already handled above.)
+                    if (field is ObjectField) {
+                        if (field.isArrayType) {
+                            append("                if (v$cap != null && v$cap.any { validator.validate(it).isNotEmpty() }) return@transaction ResponseEntity.badRequest().body(mapOf(\"error\" to \"validation\") as Any)\n")
+                        } else {
+                            append("                if (v$cap != null && validator.validate(v$cap).isNotEmpty()) return@transaction ResponseEntity.badRequest().body(mapOf(\"error\" to \"validation\") as Any)\n")
+                        }
+                    }
                 }
                 // Apply the already-bound + validated values. Columns are qualified (`Table.col`)
                 // so a field named like the `body`/`id` params can't shadow them.
@@ -1279,6 +1304,25 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
         }
     }
 
+    /** Read the `@objectRef` attr off a value-object [field] (resolving); null when absent. */
+    private fun readObjectRef(field: ObjectField): String? {
+        if (!field.hasMetaAttr(ObjectField.ATTR_OBJECTREF, true)) return null
+        return runCatching { field.getMetaAttr(ObjectField.ATTR_OBJECTREF, true).valueAsString }.getOrNull()
+    }
+
+    /**
+     * The fully-qualified Kotlin type of the value object a [field] `field.object` references
+     * (e.g. `acme.store.Marker`) — the Jackson bind target for the PATCH TypeReference. Emitted
+     * fully-qualified so the generated controller needs no extra import (mirrors the Exposed
+     * column codec in [KotlinExposedTableGenerator]). Falls back to a Jackson `JsonNode` when the
+     * `@objectRef` cannot resolve (defensive — the loader gates the attr's presence).
+     */
+    private fun voElementTypeFqn(field: ObjectField, loader: MetaDataLoader): String {
+        val target = readObjectRef(field)?.let { KotlinGenUtil.resolveObjectByShortOrFqn(loader, it) }
+        return target?.let { PackageMapping.toKotlin(it.name) }
+            ?: "com.fasterxml.jackson.databind.JsonNode"
+    }
+
     private companion object {
         /** Default primary-key field name when the entity declares no identity.primary. */
         const val DEFAULT_PK_FIELD = "id"

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

@@ -166,6 +166,54 @@ class KotlinEntityGeneratorTest {
         }
     }
 
+    @Test fun valueObjectMembersCarryValidAndNestedConstraints() {
+        // Program D: a field.object value-object member on an entity carries @field:Valid so a
+        // parent validator.validate(bean) cascades into the nested VO's own constraints; the VO's
+        // own members keep their jakarta constraints (Marker.label @required @maxLength 40 →
+        // @field:NotNull + @field:Size(min = 1, max = 40)). Mirrors the gate fixture.
+        val fx = """{
+          "metadata.root": { "package": "acme::store", "children": [
+            { "object.value": { "name": "Marker", "children": [
+                { "field.string": { "name": "label", "@required": true, "@maxLength": 40 } },
+                { "field.int":    { "name": "score" } }
+            ] } },
+            { "object.entity": { "name": "Document", "children": [
+                { "field.long":   { "name": "id" } },
+                { "field.object": { "name": "primaryMarker", "@objectRef": "Marker",
+                    "@storage": "jsonb", "@required": true } },
+                { "field.object": { "name": "markers", "@objectRef": "Marker",
+                    "@storage": "jsonb", "isArray": true } }
+            ] } }
+          ] }
+        }""".trimIndent()
+
+        val outDir = Files.createTempDirectory("kgen-vo-valid-")
+        try {
+            val gen = KotlinEntityGenerator()
+            gen.setArgs(mapOf("outputDir" to outDir.toString()))
+            gen.execute(loadString("vo-valid", fx))
+
+            val docSrc = Files.readString(outDir.resolve("acme/store/Document.kt"))
+            // The single + array VO members both carry @field:Valid (cascade on POST).
+            assertTrue("@field:Valid" in docSrc, "expected @field:Valid on VO members in:\n$docSrc")
+            assertTrue("import jakarta.validation.Valid" in docSrc,
+                "expected jakarta.validation.Valid import in:\n$docSrc")
+            assertTrue("val primaryMarker: Marker" in docSrc,
+                "expected typed VO property in:\n$docSrc")
+
+            val markerSrc = Files.readString(outDir.resolve("acme/store/Marker.kt"))
+            // The VO's own members carry the jakarta constraints the nested validation enforces.
+            assertTrue("@field:NotNull" in markerSrc, "expected @field:NotNull on Marker.label in:\n$markerSrc")
+            assertTrue("@field:Size(" in markerSrc && "max = 40" in markerSrc,
+                "expected @field:Size(...max = 40) on Marker.label in:\n$markerSrc")
+            // A pure-value VO with no nested VO member carries NO @field:Valid of its own.
+            assertFalse("@field:Valid" in markerSrc,
+                "Marker has no nested VO member — expected NO @field:Valid in:\n$markerSrc")
+        } finally {
+            outDir.toFile().deleteRecursively()
+        }
+    }
+
     // === field.enum coverage ===============================================
 
     private val enumFixture = """{

server/java/codegen-kotlin/src/test/resources/snapshots/entity-with-storage/acme/commerce/User.kt

@@ -1,5 +1,6 @@
 package acme.commerce
 
+import jakarta.validation.Valid
 import jakarta.validation.constraints.Size
 import kotlin.Long
 import kotlin.String
@@ -11,6 +12,8 @@ public data class User(
   public val id: Long? = null,
   @field:Size(max = 255)
   public val email: String? = null,
+  @field:Valid
   public val address: Address? = null,
+  @field:Valid
   public val preferences: UserMetadata? = null,
 )