fix(codegen-kotlin): expose field.string @dbColumnType:jsonb as a parsed JSON value in REST payloads (#98)

The `field.string @dbColumnType=jsonb` open JSON bag had its physical column
emitted as JSONB but was typed `String` everywhere, forcing REST clients to
double-encode (`"{\"k\":\"v\"}"` instead of `{"k":"v"}`). Per the maintainer
decision on #98, expose the bag at the serialization/REST payload boundary as a
parsed JSON value, uniformly (matching TS `z.unknown()` #97, Python `Any` #99).

Two layers, treated differently:
- Persistence (unchanged): the Exposed column stays the identity-codec
  `jsonb(name, { it }, { it })` and the entity data-class property stays
  `String` — the JDBC driver returns jsonb as raw text. `KotlinTypeMapper.kotlinTypeName`
  / `exposedColumnSpec` are untouched (existing `KotlinTypeMapperTest` stays green).
- REST payload (fixed): add `KotlinTypeMapper.payloadTypeName` — identical to
  `kotlinTypeName` except the jsonb open bag maps to kotlinx `JsonElement` (the
  `@Serializable` payload substrate this port already uses). `KotlinPayloadGenerator`
  now resolves field types through it; the lenient->strict extract mapper bridges
  `String -> JsonElement` via `Json.parseToJsonElement`; api-docs documents the
  payload field as the parsed value it actually emits.

The type mapper is shared between persistence and the payload surface, so the
split is made by a dedicated `payloadTypeName` path keyed on the new
`isJsonbOpenBag` predicate (single source of truth for payload + extractor).

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

Author: dmealing

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

@@ -311,6 +311,14 @@ open class KotlinExtractorGenerator : MultiFileDirectGeneratorBase<MetaObject>()
             else "m.$name!!.filterNotNull().map { $conv }"
         }
 
+        // jsonb open bag (`field.string @dbColumnType=jsonb`): the strict payload types this as a
+        // parsed JSON value (kotlinx `JsonElement`, via KotlinTypeMapper.payloadTypeName — issue #98)
+        // while the lenient mirror leaf stays `String` (the LLM emits text). Bridge String → JsonElement
+        // by parsing. FQN-qualified so the emitted code resolves without an import (as elsewhere here).
+        if (KotlinTypeMapper.isJsonbOpenBag(field)) {
+            return "kotlinx.serialization.json.Json.parseToJsonElement(m.$name!!)"
+        }
+
         // Scalar (single): mirror is T?, strict is T — null-assert.
         return "m.$name!!"
     }
@@ -331,6 +339,13 @@ open class KotlinExtractorGenerator : MultiFileDirectGeneratorBase<MetaObject>()
      * FAILS LOUD at codegen time ([GeneratorException]) rather than emitting non-compiling code.</p>
      */
     private fun scalarArrayElementConversion(field: MetaField<*>): String? {
+        // jsonb open bag element (`field.string @dbColumnType=jsonb` + isArray): the strict payload
+        // element is a parsed JSON value (kotlinx `JsonElement`, via payloadTypeName — issue #98);
+        // the mirror element stays `String`. Parse each element. Checked first because the generic
+        // dispatch below keys on kotlinTypeName, which (correctly, for persistence) reports `String`.
+        if (KotlinTypeMapper.isJsonbOpenBag(field)) {
+            return "kotlinx.serialization.json.Json.parseToJsonElement(it)"
+        }
         // Same path the payload generator wraps in List<…> for a scalar-array element.
         val elementType = KotlinTypeMapper.kotlinTypeName(field)
         return when (elementType) {

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

@@ -43,7 +43,9 @@ import java.nio.file.Paths
  *       (@agg sum/min/max) — type of the referenced `@of` field.</li>
  *   <li>{@code origin.collection} (@via "Parent.rel") — {@code List<TargetPayload>}, and the
  *       nested payload class is recursively emitted alongside (deduped per execute() run).</li>
- *   <li>No origin child — fall back to {@link KotlinTypeMapper#kotlinTypeName(MetaField)}.</li>
+ *   <li>No origin child — fall back to {@link KotlinTypeMapper#payloadTypeName(MetaField)}
+ *       (parsed JSON value for a `field.string @dbColumnType=jsonb` open bag; otherwise the
+ *       same mapping as {@code kotlinTypeName}).</li>
  * </ul>
  */
 open class KotlinPayloadGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
@@ -133,8 +135,9 @@ open class KotlinPayloadGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
 
     /**
      * Resolve the Kotlin TypeName of a single payload-VO field, honoring any
-     * `origin.*` child. Falls back to [KotlinTypeMapper.kotlinTypeName] when no
-     * origin is present.
+     * `origin.*` child. Falls back to [KotlinTypeMapper.payloadTypeName] when no
+     * origin is present (parsed JSON value for a `field.string @dbColumnType=jsonb` open
+     * bag, otherwise identical to `kotlinTypeName`).
      */
     protected open fun resolveFieldType(
         field: MetaField<*>,
@@ -154,7 +157,7 @@ open class KotlinPayloadGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
                 is CollectionOrigin -> resolveCollectionType(
                     origin, loader, nestedPkg, outRoot, emittedNestedFqns, emittedEnumFqns, field
                 )
-                else -> KotlinTypeMapper.kotlinTypeName(field)
+                else -> KotlinTypeMapper.payloadTypeName(field)
             }
         }
 
@@ -185,7 +188,7 @@ open class KotlinPayloadGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
         // Scalar array (`isArray: true` on a non-object field): model as List<ElementType> in the
         // strict payload (matching the cross-port payload shape). Without this, `kotlinTypeName`
         // returns the bare element type and the array semantics are lost.
-        val scalarType = KotlinTypeMapper.kotlinTypeName(field)
+        val scalarType = KotlinTypeMapper.payloadTypeName(field)
         if (field.isArrayType()) {
             return ClassName("kotlin.collections", "List").parameterizedBy(scalarType)
         }
@@ -207,7 +210,7 @@ open class KotlinPayloadGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
         emittedNestedFqns: MutableSet<String>,
         emittedEnumFqns: MutableSet<String>,
     ): TypeName {
-        val fallbackType = { KotlinTypeMapper.kotlinTypeName(field) }
+        val fallbackType = { KotlinTypeMapper.payloadTypeName(field) }
         val target = try {
             field.objectRef
         } catch (e: RuntimeException) {
@@ -248,10 +251,10 @@ open class KotlinPayloadGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
         loader: MetaDataLoader,
         fallbackField: MetaField<*>,
     ): TypeName {
-        val from = origin.from ?: return KotlinTypeMapper.kotlinTypeName(fallbackField)
+        val from = origin.from ?: return KotlinTypeMapper.payloadTypeName(fallbackField)
         val sourceField = resolveDottedFieldRef(loader, from)
-            ?: return KotlinTypeMapper.kotlinTypeName(fallbackField)
-        return KotlinTypeMapper.kotlinTypeName(sourceField)
+            ?: return KotlinTypeMapper.payloadTypeName(fallbackField)
+        return KotlinTypeMapper.payloadTypeName(sourceField)
     }
 
     /**
@@ -269,12 +272,12 @@ open class KotlinPayloadGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
             MetaOrigin.AGG_COUNT -> LONG
             MetaOrigin.AGG_AVG -> DOUBLE
             MetaOrigin.AGG_SUM, MetaOrigin.AGG_MIN, MetaOrigin.AGG_MAX -> {
-                val of = origin.of ?: return KotlinTypeMapper.kotlinTypeName(fallbackField)
+                val of = origin.of ?: return KotlinTypeMapper.payloadTypeName(fallbackField)
                 val sourceField = resolveDottedFieldRef(loader, of)
-                    ?: return KotlinTypeMapper.kotlinTypeName(fallbackField)
-                KotlinTypeMapper.kotlinTypeName(sourceField)
+                    ?: return KotlinTypeMapper.payloadTypeName(fallbackField)
+                KotlinTypeMapper.payloadTypeName(sourceField)
             }
-            else -> KotlinTypeMapper.kotlinTypeName(fallbackField)
+            else -> KotlinTypeMapper.payloadTypeName(fallbackField)
         }
     }
 
@@ -293,7 +296,7 @@ open class KotlinPayloadGenerator : MultiFileDirectGeneratorBase<MetaObject>() {
         emittedEnumFqns: MutableSet<String>,
         fallbackField: MetaField<*>,
     ): TypeName {
-        val fallbackType = { KotlinTypeMapper.kotlinTypeName(fallbackField) }
+        val fallbackType = { KotlinTypeMapper.payloadTypeName(fallbackField) }
         val via = origin.via ?: return fallbackType()
         val (parentName, relName) = KotlinGenUtil.splitDottedRef(via) ?: return fallbackType()
         val parent = KotlinGenUtil.resolveObjectByShortOrFqn(loader, parentName) ?: return fallbackType()

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

@@ -118,6 +118,18 @@ object KotlinTypeMapper {
     /** FQN of the Exposed `jsonb` extension function (raw-string open-JSON path). */
     private const val EXPOSED_JSONB_IMPORT = "org.jetbrains.exposed.sql.json.jsonb"
 
+    /**
+     * The kotlinx-serialization JSON-value type a `field.string @dbColumnType=jsonb` open-bag is
+     * exposed as in the REST/serialization PAYLOAD (issue #98). `JsonElement` is the idiomatic
+     * "any JSON value" type for the `@Serializable` payload data classes [KotlinPayloadGenerator]
+     * emits (kotlinx is already this port's payload substrate — the same `Json` used by the
+     * `jsonb(...)` column codec for `field.map`), so a client sends/receives a real JSON object
+     * rather than a double-encoded string. The PERSISTENCE side is deliberately unaffected: the
+     * entity data-class property ([kotlinTypeName]) stays `String` (raw text from the JDBC driver)
+     * and the Exposed column ([exposedColumnSpec]) stays the identity-codec `jsonb(name,{it},{it})`.
+     */
+    private val PAYLOAD_JSON_VALUE_TYPE = ClassName("kotlinx.serialization.json", "JsonElement")
+
     /**
      * Name of the generated, file-local Exposed extension function emitted for a
      * `@dbColumnType=timestamp_with_tz` [TimestampField]. It returns a
@@ -250,6 +262,33 @@ object KotlinTypeMapper {
         )
     }
 
+    /**
+     * True iff [field] is the `field.string @dbColumnType=jsonb` open JSON bag — the sanctioned
+     * "arbitrary JSON value" pattern whose physical column is JSONB while its logical subtype stays
+     * `string`. The single source of truth both the payload type ([payloadTypeName]) and the
+     * extract-mapper bridge ([KotlinExtractorGenerator]) dispatch on, so the two sites stay in
+     * lockstep. Resolved THROUGH the `extends` chain (same as [dbColumnType]) so a projection field
+     * that binds a base-entity jsonb column via `extends:` inherits the open-bag treatment.
+     */
+    fun isJsonbOpenBag(field: MetaField<*>): Boolean =
+        field is StringField && dbColumnType(field) == DB_COLUMN_TYPE_JSONB
+
+    /**
+     * Map a MetaField to its KotlinPoet TypeName for a REST/serialization **payload** property
+     * (the `@Serializable` projection data classes emitted by [KotlinPayloadGenerator]).
+     *
+     * Identical to [kotlinTypeName] for every subtype EXCEPT the `field.string @dbColumnType=jsonb`
+     * open bag, which becomes the parsed JSON value [PAYLOAD_JSON_VALUE_TYPE] instead of `String`
+     * (issue #98). This is the deliberate payload/persistence split: the persistence holder
+     * ([kotlinTypeName]) and the Exposed column ([exposedColumnSpec]) keep the raw-text `String`
+     * contract; only the API/wire boundary exposes the bag as a real JSON value (matching the
+     * TS `unknown` / Python `Any` ports). Generators that drive PERSISTENCE (entity data class,
+     * Exposed table, the entity-CRUD controller DTO, which reuses the entity data class) must keep
+     * calling [kotlinTypeName], not this.
+     */
+    fun payloadTypeName(field: MetaField<*>): TypeName =
+        if (isJsonbOpenBag(field)) PAYLOAD_JSON_VALUE_TYPE else kotlinTypeName(field)
+
     /**
      * The Kotlin value TypeName for a scalar-valued [MapField] (the type named by its
      * `@valueType` attr — string/int/long/double/float/decimal/boolean/date/time/

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

@@ -381,18 +381,26 @@ class KotlinApiModelBuilder {
         val rows = mutableListOf<FieldShape>()
         for (f in vo.metaFields) {
             if (f is ObjectField) continue
-            rows.add(FieldShape(f.name, kotlinTypeLabel(f, vo), optional = !KotlinGenUtil.isRequiredField(f)))
+            rows.add(FieldShape(f.name, kotlinTypeLabel(f, vo, forPayload = true), optional = !KotlinGenUtil.isRequiredField(f)))
         }
         return rows
     }
 
-    /** The simple Kotlin type label for a documented field (enum → generated enum class name). */
-    private fun kotlinTypeLabel(field: MetaField<*>, owner: MetaObject): String {
+    /**
+     * The simple Kotlin type label for a documented field (enum → generated enum class name).
+     *
+     * [forPayload] selects the payload type path ([KotlinTypeMapper.payloadTypeName]) so a
+     * `field.string @dbColumnType=jsonb` open bag is documented as the parsed JSON value
+     * (`JsonElement`) the payload data class actually emits (issue #98); the entity model field
+     * (forPayload = false) stays `String`, matching its data-class property. Keeps the documented
+     * type == the generated type on both surfaces.
+     */
+    private fun kotlinTypeLabel(field: MetaField<*>, owner: MetaObject, forPayload: Boolean = false): String {
         KotlinTypeMapper.enumTypeName(field, owner)?.let { enumType ->
             val simple = enumType.simpleName
             return if (field.isArrayType) "List<$simple>" else simple
         }
-        val tn = KotlinTypeMapper.kotlinTypeName(field)
+        val tn = if (forPayload) KotlinTypeMapper.payloadTypeName(field) else KotlinTypeMapper.kotlinTypeName(field)
         val simple = (tn as? com.squareup.kotlinpoet.ClassName)?.simpleName ?: tn.toString()
         return if (field.isArrayType) "List<$simple>" else simple
     }

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

@@ -40,6 +40,44 @@ class KotlinPayloadGeneratorTest {
         }
     }
 
+    @Test fun `jsonb open-bag field is a parsed JSON value in the payload, plain string stays String`() {
+        // Issue #98: a `field.string @dbColumnType=jsonb` payload property is exposed as a parsed
+        // JSON value (kotlinx `JsonElement`), NOT a (double-encoded) String. A sibling plain
+        // `field.string` on the same VO stays `String`, proving the divergence is scoped to the
+        // jsonb open-bag. The persistence side (Exposed column / entity data class) is unaffected —
+        // KotlinPayloadGenerator emits no table/row code.
+        val fx = """{
+          "metadata.root": { "package": "acme::demo", "children": [
+            { "object.value": { "name": "Settings", "children": [
+                { "field.long":   { "name": "id" } },
+                { "field.string": { "name": "config", "@dbColumnType": "jsonb" } },
+                { "field.string": { "name": "label" } }
+            ] } },
+            { "template.prompt": { "name": "SettingsPrompt",
+                "@payloadRef": "Settings", "@textRef": "demo/settings" } }
+          ] }
+        }""".trimIndent()
+
+        val outDir = Files.createTempDirectory("kpay-jsonb-")
+        try {
+            val gen = KotlinPayloadGenerator()
+            gen.setArgs(mapOf("outputDir" to outDir.toString()))
+            gen.execute(loadString("test-jsonb", fx))
+
+            val emitted = outDir.resolve("acme/demo/prompts/SettingsPromptPayload.kt")
+            assertTrue(Files.exists(emitted),
+                "expected $emitted; files=${Files.walk(outDir).toList()}")
+            val src = Files.readString(emitted)
+            // The open-bag field → parsed JSON value.
+            assertTrue("val config: JsonElement" in src, src)
+            assertTrue("import kotlinx.serialization.json.JsonElement" in src, src)
+            // The plain string field → String (no double-encoding).
+            assertTrue("val label: String" in src, src)
+        } finally {
+            outDir.toFile().deleteRecursively()
+        }
+    }
+
     // -----------------------------------------------------------------------
     // origin.* coverage — FR-004 payload-VO field-value provenance
     // -----------------------------------------------------------------------

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

@@ -231,6 +231,37 @@ class KotlinTypeMapperTest {
         assertEquals("org.jetbrains.exposed.sql.json.jsonb", KotlinTypeMapper.exposedColumnImport(f))
     }
 
+    @Test fun `string field with dbColumnType=jsonb exposes a parsed JSON value in the REST payload`() {
+        // Issue #98 (cross-port jsonb open-bag REST contract). A `field.string @dbColumnType=jsonb`
+        // is the sanctioned "open JSON bag": the physical column is JSONB but the LOGICAL subtype
+        // stays `string`. The two layers are deliberately split:
+        //   - PERSISTENCE (kotlinTypeName / exposedColumnSpec): the Exposed column stays the
+        //     identity-codec `jsonb(name, { it }, { it })` and the entity data-class property stays
+        //     `String` — the JDBC driver returns jsonb as raw text, so String is correct here.
+        //   - REST PAYLOAD (payloadTypeName): the typed projection exposes the bag as a PARSED JSON
+        //     value (kotlinx `JsonElement`) so a client sends/receives a real JSON object, never a
+        //     double-encoded string. Matches TS `z.unknown()` (#97) and Python `Any` (#99).
+        val f = StringField("rubricWeights")
+        f.addMetaAttr(StringAttribute.create("dbColumnType", "jsonb"))
+
+        // REST payload → parsed JSON value (the fix).
+        assertEquals(
+            ClassName("kotlinx.serialization.json", "JsonElement"),
+            KotlinTypeMapper.payloadTypeName(f),
+        )
+        // Persistence stays String — the entity data-class property is the raw-JSON holder for the
+        // identity-codec jsonb column. (This MUST NOT regress; the column assertion above gates it.)
+        assertEquals(STRING, KotlinTypeMapper.kotlinTypeName(f))
+        assertEquals("jsonb(\"rubric_weights\", { it }, { it })", KotlinTypeMapper.exposedColumnSpec(f))
+    }
+
+    @Test fun `plain string field payload stays String`() {
+        // payloadTypeName only diverges from kotlinTypeName for the jsonb open-bag; a plain
+        // `field.string` payload property is still `String` (no double-encoding concern).
+        val f = StringField("name")
+        assertEquals(STRING, KotlinTypeMapper.payloadTypeName(f))
+    }
+
     @Test fun `string field with dbColumnType=jsonb is case-insensitive`() {
         // `@dbColumnType` lookup case-folds (see `KotlinTypeMapper.dbColumnType`); both
         // `"JSONB"` and `"jsonb"` route to the JSONB branch.