fix(#214): Kotlin write-through — exclude derived value-object columns; document re-read scope

Cross-port divergence audit follow-ups for the #214 fan-out (Kotlin).

- D3 (latent bug): KotlinExposedTableGenerator.buildObjectColumns iterated the
  object/map fields with no derived filter, and its output was emitted for BOTH
  the write `<Short>Table` and the read `<Short>View`, so a DERIVED (origin.*)
  `field.object` / `field.map` became a phantom column on the write table —
  declared but never written (create/patch skip derived) and never selected
  (reads use the view). Latent for a nullable derived VO; a @required one would
  break Exposed insert. Thread `excludeDerived` through buildObjectColumns
  (mirroring the scalar-column loop's existing guard) so the write table drops
  derived VO/map columns; the read view keeps them. Byte-identical for a vanilla
  entity and the view (the guard is a no-op without a derived VO field).

- D1/D4 (documentation): the by-PK re-read keys on the SINGLE primary key (a
  composite-PK write-through entity is out of scope — this repository already
  skips composite PKs, matching the other ports) and uses Exposed `.single()`,
  which assumes the replica view surfaces the just-written row (true for a plain
  `@kind:view`; a `@kind:materializedView`/filtered replica throws — the data-
  oriented ports degrade to the write row). Both noted in the generator and in
  KNOWN_GAPS.

The remaining audit findings are architecture-driven, not bugs: a guaranteed-
non-null aggregate-derived field reads as nullable on the single-shape ports
(Java/Kotlin) vs non-null on the two-shape ports (TS/C#/Python) — the documented
cost of the shared read/create DTO; and Java's read→view routing lives in the
consumer repository (SQL-free port, ADR-0015). Recorded, not changed.

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

@@ -81,3 +81,18 @@ value → set). Notes:
   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.
+
+## Write-through read-view re-read assumes a 1:1 replica (#214)
+
+**Status:** documented limitation (a cross-port audit finding, D1).
+
+A write-through entity's generated repository/controller re-reads a
+create/update through the replica view by primary key using Exposed
+`.single()`, which assumes the view surfaces the just-written row. That holds
+for a plain `@kind:view` replica (a live query over the write table). A
+`@kind:materializedView` (unrefreshed) or a filtered replica that does not
+surface the row makes `.single()` throw → HTTP 500, whereas the data-oriented
+ports (Python `ObjectManager`, C# routes) degrade to returning the write row
+(derived fields absent). A materialized/filtered replica on a write-through
+entity is an unusual shape; the graceful table-row fallback (a second, derived-
+free row mapper) is deferred until a real consumer needs it.

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

@@ -410,7 +410,7 @@ open class KotlinExposedTableGenerator : MultiFileDirectGeneratorBase<MetaObject
         // Views never carry a generated default (they inherit the underlying PK).
         val uuidGeneratedPk = primary?.isUuid == true && !isView && singlePrimaryFieldName != null
 
-        val objectColumns = buildObjectColumns(entity, primaryFieldSet, loader)
+        val objectColumns = buildObjectColumns(entity, primaryFieldSet, loader, excludeDerivedFields)
         // A `field.string @dbColumnType=jsonb` open bag now decodes to a kotlinx `JsonElement`
         // (issue #98) via `{ Json.parseToJsonElement(it) }`, so its table file needs the
         // `kotlinx.serialization.json.Json` import too (that open bag is the ONLY column that still
@@ -706,9 +706,16 @@ open class KotlinExposedTableGenerator : MultiFileDirectGeneratorBase<MetaObject
         entity: MetaObject,
         primaryFieldNames: Set<String>,
         loader: MetaDataLoader,
+        // #214: on the WRITE table of a write-through entity, a DERIVED (origin.*) field.object /
+        // field.map has no physical column (it is computed by the read view) — exclude it, exactly
+        // as the scalar-column loop does. Without this a derived value-object column becomes a
+        // phantom on the write `<Short>Table` (declared but never written/selected; a @required one
+        // would break Exposed insert). Default false → byte-identical for a vanilla entity + the view.
+        excludeDerived: Boolean = false,
     ): List<ObjectColumnSpec> {
         val result = mutableListOf<ObjectColumnSpec>()
         for (field in entity.metaFields) {
+            if (excludeDerived && KotlinGenUtil.isDerivedField(field)) continue
             // field.map → a single jsonb column (the JSON object). Keys are always strings;
             // never flattened, never a native array. Same JSONB emission as a jsonb-stored
             // field.object.

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

@@ -168,6 +168,14 @@ open class KotlinRepositoryGenerator : MultiFileDirectGeneratorBase<MetaObject>(
         fun StringBuilder.appendInsertBody(preserve: Boolean) {
             // Writes target the write table; the by-PK read-back routes to the read object
             // (the view for a write-through entity) so the returned entity carries derived fields.
+            // #214 cross-port notes: (D4) the re-read keys on the SINGLE primary key
+            // ($pkFieldName) — a write-through entity with a composite PK is out of scope here
+            // (this repository already skips composite-PK entities), matching the other ports'
+            // single-PK re-read. (D1) the re-read uses `.single()` — it assumes the replica view
+            // surfaces the just-written row, TRUE for a plain `@kind:view` (a live query over the
+            // table). A `@kind:materializedView` (unrefreshed) or a filtered replica that does not
+            // surface the row throws here; that is an unsupported write-through replica shape (the
+            // data-oriented ports degrade to the table row instead) — a documented limitation.
             when {
                 incrementPk -> {
                     append("        val newId = $writeObj.insert {\n")