feat(codegen-kotlin): a generated entity/value object is now constructible from Java

Kotlin default arguments are a COMPILER feature, not a bytecode one. A generated
data class whose properties are all defaulted offered Java exactly three
constructors — the full N-arg one, a synthetic bitmask one Java cannot call, and
(because every parameter is defaulted) a no-arg one yielding an all-null instance
of an IMMUTABLE class. Nothing in between, and no setters to fill in afterwards.

So a Java caller setting 3 of 14 properties had to pass 14 arguments with 11
nulls. An adopter converting an untyped jsonb bag to an `object.value` per the
authoring skill's ladder found the generated VO replacing a hand-written Lombok
`@Builder` made four Java call sites strictly worse, and reverted the conversion.
The ladder's promise is a better handle than the cast; here the handle was worse.

Emits a nested `Builder` plus a `@JvmStatic builder()`:

    ItemEffect.builder().name("Restore HP").value(10).build();

A builder rather than `@JvmOverloads`: overloads are positional, so they only
help a caller whose omissions are all TRAILING, and a 14-member class would emit
15 constructors to say so. Deliberately NOT Lombok — generated code must not
force a third-party annotation processor on an adopter — so it is a plain nested
class with no new dependency.

Every backing field is nullable even where the property is not: a builder fills
incrementally and cannot hold the constructor's non-null guarantee. `build()`
restores it with `requireNotNull`, naming the property. The data-class
constructor remains the real enforcement point.

NOT on `object.projection`. A projection is a derived read-only representation —
it arrives from a view query and nothing constructs one, so a builder would
advertise something callers must not do. That exclusion was FOUND, not reasoned
about: KotlinProjectionCompileTest requires projection data classes to be
immutable and my `var` backing fields tripped it. The stored-proc fixture now
demonstrates the split cleanly — `OrderReportArgs` (object.value, the input a
caller builds) gets a builder; `OrderReport` (object.projection, the result)
does not.

The new test is the point of the change as much as the generator is: every other
test in this module is Kotlin-side, where named arguments hide the problem
completely, which is exactly why the Java-interop face of this output was free to
be bad. KotlinValueObjectJavaConstructionTest compiles real JAVA against the
generated class through kotlin-compile-testing and sets 2 of 5 properties.
Verified by reverting the generator: `error: cannot find symbol`.

13 snapshots re-cut. The only removed line in that whole diff is `)` becoming
`) {` — everything else is additive. No vocabulary change, so metamodelVersion
does not move (`check-metamodel-version`: none change since v1.0.1).

373/373 in codegen-kotlin; java+kotlin conformance green; gates lane green.

codegen-spring emits Java `record`s, which have the same all-args problem and no
defaults at all — tracked in #365 as a follow-on, deliberately out of scope here.

Closes #365

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

Author: dmealing

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

@@ -238,8 +238,12 @@ open class KotlinEntityGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
             typeBuilder.addProperty(PropertySpec.builder(propName, propType).initializer(propName).build())
         }
 
+        val primaryCtor = ctorBuilder.build()
+        typeBuilder.primaryConstructor(primaryCtor)
+        addJavaBuilder(obj, typeBuilder, ClassName(pkg, shortName), primaryCtor.parameters)
+
         val fileSpec = FileSpec.builder(pkg, shortName)
-            .addType(typeBuilder.primaryConstructor(ctorBuilder.build()).build())
+            .addType(typeBuilder.build())
             .build()
 
         // Guarded: `<Entity>.kt` is the file an adopter is most likely to want to own, and a
@@ -726,4 +730,90 @@ open class KotlinEntityGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
         PackageMapping.splitFqn(md.name).first.replace('.', '/')
     override fun getSingleOutputFilename(md: MetaObject): String =
         PackageMapping.splitFqn(md.name).second + ".kt"
+
+    /**
+     * Emit a nested `Builder` plus a `@JvmStatic builder()` factory.
+     *
+     * Kotlin default arguments are a COMPILER feature, not a bytecode one. A data class whose
+     * properties are all defaulted exposes only three constructors to Java — the full N-arg one,
+     * a synthetic bitmask one Java cannot call, and (when every parameter is defaulted) a no-arg
+     * one that yields an all-null instance of an IMMUTABLE class. So a Java caller setting 3 of
+     * 14 fields had to pass 14 arguments with 11 nulls, and a generated value object replacing a
+     * hand-written Lombok `@Builder` made its Java call sites strictly worse (#365). Kotlin
+     * callers were never affected — named arguments cover it — which is why every existing test
+     * here, all Kotlin-side, missed it.
+     *
+     * A nested builder rather than `@JvmOverloads`: overloads are positional, so they only help a
+     * caller whose omissions are all TRAILING, and a 14-member class would emit 15 constructors
+     * to say so. A builder needs no dependency (deliberately NOT Lombok — generated code must not
+     * force a third-party annotation processor on an adopter) and reads the same from both
+     * languages.
+     *
+     * Every backing field is nullable even where the property is not: a builder is filled
+     * incrementally, so it cannot hold the constructor's non-null guarantee. `build()` restores it
+     * with `requireNotNull`, naming the property — the same trade every builder makes, and the
+     * data-class constructor remains the real enforcement point.
+     */
+    private fun addJavaBuilder(
+        obj: MetaObject,
+        typeBuilder: TypeSpec.Builder,
+        className: ClassName,
+        params: List<ParameterSpec>,
+    ) {
+        if (params.isEmpty()) return
+        // NOT on an object.projection. A projection is a DERIVED read-only representation —
+        // it arrives from a view query and nothing constructs one, so a builder would be an
+        // affordance for something callers must not do. It would also put `var` backing fields
+        // into a type KotlinProjectionCompileTest requires to be immutable, which is how this
+        // exclusion was found rather than reasoned about.
+        if (obj.subType == MetaObject.SUBTYPE_PROJECTION) return
+
+        val builderClass = ClassName(className.packageName, className.simpleName, "Builder")
+        val builder = TypeSpec.classBuilder("Builder")
+            .addKdoc("Fluent builder — lets a JAVA caller set a subset of properties.\n")
+
+        for (param in params) {
+            val backingType = param.type.copy(nullable = true)
+            builder.addProperty(
+                PropertySpec.builder(param.name, backingType)
+                    .addModifiers(KModifier.PRIVATE)
+                    .mutable(true)
+                    .initializer("null")
+                    .build()
+            )
+            builder.addFunction(
+                FunSpec.builder(param.name)
+                    .addParameter("v", backingType)
+                    .returns(builderClass)
+                    .addStatement("this.%N = v", param.name)
+                    .addStatement("return this")
+                    .build()
+            )
+        }
+
+        val args = params.joinToString(",\n  ") { p ->
+            if (p.type.isNullable) "%1N = %1N".replace("%1N", p.name)
+            else "${p.name} = requireNotNull(${p.name}) { \"${p.name} is required\" }"
+        }
+        builder.addFunction(
+            FunSpec.builder("build")
+                .returns(className)
+                .addStatement("return %T(\n  $args\n)", className)
+                .build()
+        )
+
+        typeBuilder.addType(builder.build())
+        typeBuilder.addType(
+            TypeSpec.companionObjectBuilder()
+                .addFunction(
+                    FunSpec.builder("builder")
+                        .addAnnotation(JvmStatic::class)
+                        .returns(builderClass)
+                        .addStatement("return Builder()")
+                        .build()
+                )
+                .build()
+        )
+    }
+
 }

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

@@ -313,4 +313,98 @@ class KotlinEntityGeneratorTest {
             outDir.toFile().deleteRecursively()
         }
     }
+
+    @Test fun `emits a Java-callable builder for partial construction`() {
+        // Kotlin default arguments are a COMPILER feature, not a bytecode one: a data class
+        // whose properties are all defaulted exposes only a no-arg constructor and the full
+        // N-arg one to Java, plus a synthetic bitmask ctor Java cannot call. The class is
+        // immutable, so there are no setters to fill in afterwards either — a Java caller
+        // setting 3 of 14 fields had to pass 14 arguments with 11 nulls (#365, found when a
+        // generated value object replaced a hand-written Lombok @Builder and made four Java
+        // call sites strictly worse). The builder restores partial construction WITHOUT
+        // adding a dependency: a plain nested class, no Lombok.
+        val outDir = Files.createTempDirectory("kgen-builder-")
+        try {
+            val gen = KotlinEntityGenerator()
+            gen.setArgs(mapOf("outputDir" to outDir.toString()))
+            gen.execute(loadString("test", fixture))
+
+            val src = Files.readString(outDir.resolve("acme/demo/Author.kt"))
+
+            assertTrue("public class Builder" in src, "expected a nested Builder in:\n$src")
+            // @JvmStatic so Java writes Author.builder(), not Author.Companion.builder().
+            assertTrue("@JvmStatic" in src, "expected @JvmStatic on builder() in:\n$src")
+            assertTrue("public fun builder(): Builder" in src, "expected a builder() factory in:\n$src")
+            // One fluent setter per property, returning Builder so calls chain.
+            for (prop in listOf("id", "name", "bio")) {
+                assertTrue("public fun $prop(" in src, "expected a fluent `$prop(...)` setter in:\n$src")
+            }
+            assertTrue("public fun build(): Author" in src, "expected build() in:\n$src")
+        } finally {
+            outDir.toFile().deleteRecursively()
+        }
+    }
+
+    @Test fun `the builder covers value objects, not just entities`() {
+        // Same emit path serves object.entity and object.value, and the reported case was a
+        // VALUE object — so assert the VO explicitly rather than relying on the shared path.
+        val voFixture = """{
+          "metadata.root": { "package": "acme::demo", "children": [
+            { "object.value": { "name": "Money", "children": [
+                { "field.string": { "name": "currency" } },
+                { "field.int":    { "name": "amountMinor" } }
+            ] } }
+          ] }
+        }""".trimIndent()
+        val outDir = Files.createTempDirectory("kgen-vo-builder-")
+        try {
+            val gen = KotlinEntityGenerator()
+            gen.setArgs(mapOf("outputDir" to outDir.toString()))
+            gen.execute(loadString("test", voFixture))
+
+            val src = Files.readString(outDir.resolve("acme/demo/Money.kt"))
+            assertTrue("public class Builder" in src, "expected a Builder on the value object in:\n$src")
+            assertTrue("public fun build(): Money" in src, "expected build(): Money in:\n$src")
+            assertTrue("public fun currency(" in src, "expected a fluent currency(...) setter in:\n$src")
+        } finally {
+            outDir.toFile().deleteRecursively()
+        }
+    }
+
+
+    @Test fun `the builder restores the non-null guarantee it cannot hold`() {
+        // A builder is filled incrementally, so its backing field must be nullable even where
+        // the property is not. build() puts the guarantee back with requireNotNull, naming the
+        // property — the data-class constructor stays the real enforcement point.
+        val requiredFixture = """{
+          "metadata.root": { "package": "acme::demo", "children": [
+            { "object.entity": { "name": "Ticket", "children": [
+                { "field.string": { "name": "code", "@required": true } },
+                { "field.string": { "name": "note" } }
+            ] } }
+          ] }
+        }""".trimIndent()
+        val outDir = Files.createTempDirectory("kgen-required-")
+        try {
+            val gen = KotlinEntityGenerator()
+            gen.setArgs(mapOf("outputDir" to outDir.toString()))
+            gen.execute(loadString("test", requiredFixture))
+
+            val src = Files.readString(outDir.resolve("acme/demo/Ticket.kt"))
+            // the property itself is non-null...
+            assertTrue("public val code: String," in src || "public val code: String\n" in src,
+                "expected a NON-null `code` property in:\n$src")
+            // ...its builder backing field is nullable, and build() re-asserts it
+            assertTrue("private var code: String? = null" in src,
+                "expected a nullable builder field for `code` in:\n$src")
+            assertTrue("requireNotNull(code)" in src,
+                "expected build() to requireNotNull(code) in:\n$src")
+            // a nullable sibling passes straight through, unguarded
+            assertFalse("requireNotNull(note)" in src,
+                "a nullable property must NOT be guarded in:\n$src")
+        } finally {
+            outDir.toFile().deleteRecursively()
+        }
+    }
+
 }

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

@@ -0,0 +1,82 @@
+package com.metaobjects.generator.kotlin
+
+import com.metaobjects.metadata.ktx.loadString
+import com.tschuchort.compiletesting.KotlinCompilation
+import com.tschuchort.compiletesting.SourceFile
+import java.nio.file.Files
+import kotlin.io.path.isRegularFile
+import kotlin.io.path.readText
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+/**
+ * The generated shapes must be constructible FROM JAVA, not only from Kotlin (#365).
+ *
+ * Kotlin default arguments are a compiler feature, not a bytecode one, so a data class whose
+ * properties are all defaulted offers Java the full N-arg constructor, a synthetic bitmask one
+ * it cannot call, and a no-arg one yielding an all-null instance of an immutable class —
+ * nothing in between. An adopter converting an untyped jsonb bag to an `object.value` found a
+ * generated 14-member VO needed 14 arguments with 11 nulls where the hand-written class it
+ * replaced had a Lombok builder.
+ *
+ * Every other test in this module is Kotlin-side, where named arguments hide the problem
+ * completely. This one compiles real JAVA against the generated output, which is the only way
+ * the guarantee stays honest.
+ */
+@OptIn(org.jetbrains.kotlin.compiler.plugin.ExperimentalCompilerApi::class)
+class KotlinValueObjectJavaConstructionTest {
+
+    private val fixture = """{
+      "metadata.root": { "package": "acme::demo", "children": [
+        { "object.value": { "name": "ItemEffect", "children": [
+            { "field.string": { "name": "name" } },
+            { "field.string": { "name": "targetAttribute" } },
+            { "field.int":    { "name": "value" } },
+            { "field.int":    { "name": "duration" } },
+            { "field.string": { "name": "damageType" } }
+        ] } }
+      ] }
+    }""".trimIndent()
+
+    @Test fun `java can construct a generated value object setting only some properties`() {
+        val outDir = Files.createTempDirectory("kgen-java-ctor-")
+        try {
+            val gen = KotlinEntityGenerator()
+            gen.setArgs(mapOf("outputDir" to outDir.toString()))
+            gen.execute(loadString("test", fixture))
+
+            val generated = Files.walk(outDir).filter { it.isRegularFile() }.toList()
+                .map { SourceFile.kotlin(it.fileName.toString(), it.readText()) }
+
+            // Sets 2 of 5 properties. Without a builder this cannot be written at all: the
+            // class is immutable, so there is no no-arg-then-set path, and the only other
+            // constructor takes every argument.
+            val caller = SourceFile.java(
+                "Caller.java",
+                """
+                package acme.demo;
+
+                public class Caller {
+                    public static ItemEffect partial() {
+                        return ItemEffect.builder()
+                                .name("Restore HP")
+                                .value(10)
+                                .build();
+                    }
+                }
+                """.trimIndent(),
+            )
+
+            val result = KotlinCompilation().apply {
+                sources = generated + caller
+                inheritClassPath = true
+                messageOutputStream = System.out
+            }.compile()
+
+            assertEquals(KotlinCompilation.ExitCode.OK, result.exitCode,
+                "Java could not construct the generated value object:\n${result.messages}")
+        } finally {
+            outDir.toFile().deleteRecursively()
+        }
+    }
+}

server/java/codegen-kotlin/src/test/resources/snapshots/entity-with-bidirectional-fk/acme/blog/Author.kt

@@ -3,6 +3,7 @@ package acme.blog
 import jakarta.validation.constraints.Size
 import kotlin.Long
 import kotlin.String
+import kotlin.jvm.JvmStatic
 
 /**
  * GENERATED — do not hand-edit. Regenerated from metadata.
@@ -11,4 +12,33 @@ public data class Author(
   public val id: Long? = null,
   @field:Size(max = 100)
   public val name: String? = null,
-)
+) {
+  /**
+   * Fluent builder — lets a JAVA caller set a subset of properties.
+   */
+  public class Builder {
+    private var id: Long? = null
+
+    private var name: String? = null
+
+    public fun id(v: Long?): Builder {
+      this.id = v
+      return this
+    }
+
+    public fun name(v: String?): Builder {
+      this.name = v
+      return this
+    }
+
+    public fun build(): Author = Author(
+      id = id,
+      name = name
+    )
+  }
+
+  public companion object {
+    @JvmStatic
+    public fun builder(): Builder = Builder()
+  }
+}

server/java/codegen-kotlin/src/test/resources/snapshots/entity-with-bidirectional-fk/acme/blog/Post.kt

@@ -3,6 +3,7 @@ package acme.blog
 import jakarta.validation.constraints.Size
 import kotlin.Long
 import kotlin.String
+import kotlin.jvm.JvmStatic
 
 /**
  * GENERATED — do not hand-edit. Regenerated from metadata.
@@ -11,4 +12,33 @@ public data class Post(
   public val id: Long? = null,
   @field:Size(max = 200)
   public val title: String? = null,
-)
+) {
+  /**
+   * Fluent builder — lets a JAVA caller set a subset of properties.
+   */
+  public class Builder {
+    private var id: Long? = null
+
+    private var title: String? = null
+
+    public fun id(v: Long?): Builder {
+      this.id = v
+      return this
+    }
+
+    public fun title(v: String?): Builder {
+      this.title = v
+      return this
+    }
+
+    public fun build(): Post = Post(
+      id = id,
+      title = title
+    )
+  }
+
+  public companion object {
+    @JvmStatic
+    public fun builder(): Builder = Builder()
+  }
+}