feat(codegen-kotlin): generated Spring controller stamps @autoset (ADR-0045, #203)

The shipped Kotlin generated Spring controller did its own inline Exposed writes
with zero @autoset awareness — so an adopter deploying it silently lost the
timestamp-stamping FR (#203 shipped it only in KotlinRepositoryGenerator, which
the controller never uses). Surfaced while scoping the cross-port @autoset gate.

ADR-0045 records the durable rule: the generated API surface (the controller/routes
an adopter deploys) must itself guarantee every metamodel write semantic — no
consumer-supplied seam may sit between the guarantee and the wire. Persistence-layer
stamping stays as defense-in-depth for non-HTTP writes.

KotlinSpringControllerGenerator now:
- insert stamps BOTH onCreate + onUpdate columns from ONE captured now()-val per
  temporal type (a fresh row's createdAt == updatedAt exactly), ignoring the caller;
- @autoset columns are excluded from the PATCH-settable set (a caller can no longer
  overwrite createdAt/updatedAt);
- a patch bumps every onUpdate column on EVERY request (even an empty body) and never
  rewrites onCreate;
- byte-identical output for entities with no @autoset field (snapshot suite 14/14).

nowExpr hoisted to KotlinTypeMapper (the type->"Type.now()" mapping's natural home;
no circular dep, unlike KotlinGenUtil). New controller-level @autoset tests in
KotlinAutoSetStampingTest (11/11). TPH+@autoset controller stamping is a documented
follow-up (not exercised by the corpus; no existing test covers it).

This is the Kotlin leg of the ADR-0045 rollout; the Python router leg and the shared
api-contract @autoset gate follow (no scenario lands here, so no lane reds).

Refs #203, #229.

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

Author: dmealing

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

@@ -179,10 +179,33 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
                 (it !is ObjectField || isJsonbObjectColumn(it)) &&
                 // #214: a DERIVED (origin.*) field on a write-through entity has no column on the
                 // write table — it is computed by the read view — so it is never a write/patch target.
-                !(writeThrough && KotlinGenUtil.isDerivedField(it))
+                !(writeThrough && KotlinGenUtil.isDerivedField(it)) &&
+                // #203/ADR-0045: an @autoSet column is server-owned — the generated controller
+                // stamps it (the API surface owns the write semantic); a caller cannot set it via PATCH.
+                !KotlinGenUtil.isAutoSetField(it)
         }
         val hasPatchFields = patchSettableFields.isNotEmpty()
 
+        // #203/ADR-0045: @autoSet columns are stamped by the generated controller, not bound from
+        // the caller. insert stamps BOTH onCreate+onUpdate (a fresh row's updatedAt == createdAt —
+        // captured from ONE now() per temporal type so they are exactly equal); a patch re-stamps
+        // onUpdate on EVERY write (even an empty body) and never rewrites onCreate. An @autoSet
+        // field is a real write-table column (never derived), so only the PK / write-through-derived
+        // guards apply.
+        val insertAutoSetFields = entity.metaFields.filter {
+            KotlinGenUtil.isAutoSetField(it) && it.name != pkFieldName &&
+                !(writeThrough && KotlinGenUtil.isDerivedField(it))
+        }
+        val onUpdateAutoSetFields = insertAutoSetFields.filter {
+            KotlinGenUtil.autoSetPolicy(it) == KotlinGenUtil.AUTO_SET_ON_UPDATE
+        }
+        // One captured now()-val per distinct temporal type, so all same-type @autoSet columns in a
+        // single insert receive the identical value (createdAt == updatedAt exactly).
+        val insertNowVal = LinkedHashMap<String, String>() // nowExpr → local val name
+        insertAutoSetFields.forEach { f ->
+            insertNowVal.getOrPut(KotlinTypeMapper.nowExpr(f)) { "autoSetNow${insertNowVal.size}" }
+        }
+
         // 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
@@ -398,6 +421,8 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
             append("    @PostMapping\n")
             append("    fun create(@RequestBody dto: ${shortName}): ResponseEntity<Any> = transaction {\n")
             append("        if (validator.validate(dto).isNotEmpty()) return@transaction ResponseEntity.badRequest().body(mapOf(\"error\" to \"validation\") as Any)\n")
+            // #203/ADR-0045: capture one now() per temporal type so createdAt == updatedAt exactly.
+            for ((expr, valName) in insertNowVal) append("        val $valName = $expr\n")
             append("        val newId = ${tableObjectName}.insert {\n")
             for (field in entity.metaFields) {
                 // Program D: a field.object value-object jsonb column IS written on create — the
@@ -412,6 +437,12 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
                 // #214: a DERIVED (origin.*) field on a write-through entity has no column on the
                 // write table (computed by the view), so it is never written on create.
                 if (writeThrough && KotlinGenUtil.isDerivedField(field)) continue
+                // #203/ADR-0045: insert stamps onCreate+onUpdate @autoSet columns from the captured
+                // now() (the caller's value is ignored — never bound from the dto).
+                if (KotlinGenUtil.isAutoSetField(field)) {
+                    append("            it[${field.name}] = ${insertNowVal[KotlinTypeMapper.nowExpr(field)]}\n")
+                    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
@@ -449,9 +480,13 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
                     append("        if (body.has(\"${field.name}\") && body.get(\"${field.name}\").isNull) return@transaction ResponseEntity.badRequest().body(mapOf(\"error\" to \"validation\") as Any)\n")
                 }
             }
+            val mustStampOnUpdate = onUpdateAutoSetFields.isNotEmpty()
             if (hasPatchFields) {
                 val settableNamesList = patchSettableFields.joinToString(", ") { "\"${it.name}\"" }
-                append("        if (listOf($settableNamesList).any { body.has(it) }) {\n")
+                // #203/ADR-0045: with onUpdate @autoSet columns the update must run on EVERY patch
+                // (to bump them) — no "any present" guard; otherwise the guard keeps the update out
+                // when the caller sent no settable field (byte-identical to the pre-#203 output).
+                if (!mustStampOnUpdate) 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 — map that to 400, not a 500. Catch
                 // the specific Jackson JsonMappingException so no unrelated exception is swallowed.
@@ -502,6 +537,11 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
                 // Apply the already-bound + validated values. Columns are qualified (`Table.col`)
                 // so a field named like the `body`/`id` params can't shadow them.
                 append("                ${tableObjectName}.update({ ${tableObjectName}.${pkFieldName} eq id }) {\n")
+                // #203/ADR-0045: bump every onUpdate @autoSet column first (server-owned); onCreate
+                // columns are never touched on update (createdAt is immutable).
+                for (field in onUpdateAutoSetFields) {
+                    append("                    it[${tableObjectName}.${field.name}] = ${KotlinTypeMapper.nowExpr(field)}\n")
+                }
                 for (field in patchSettableFields) {
                     val fn = field.name
                     val cap = capitalizeFirst(fn)
@@ -516,6 +556,14 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
                 append("            } catch (e: com.fasterxml.jackson.databind.JsonMappingException) {\n")
                 append("                return@transaction ResponseEntity.badRequest().body(mapOf(\"error\" to \"validation\") as Any)\n")
                 append("            }\n")
+                // Close the "any present" guard only when it was opened (see mustStampOnUpdate above).
+                if (!mustStampOnUpdate) append("        }\n")
+            } else if (mustStampOnUpdate) {
+                // No caller-settable columns, but onUpdate @autoSet must still bump on every patch.
+                append("        ${tableObjectName}.update({ ${tableObjectName}.${pkFieldName} eq id }) {\n")
+                for (field in onUpdateAutoSetFields) {
+                    append("            it[${tableObjectName}.${field.name}] = ${KotlinTypeMapper.nowExpr(field)}\n")
+                }
                 append("        }\n")
             }
             // #214: read the (possibly-updated) row back through the READ object so the response

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

@@ -654,4 +654,18 @@ object KotlinTypeMapper {
             else -> null
         }
     }
+
+    /**
+     * The `now()` expression for [field]'s temporal COLUMN type (issue #203 / ADR-0045) — keyed
+     * off the column type so it generalizes across every temporal subtype: `field.timestamp`
+     * (default) → `java.time.Instant.now()`, `@localTime` → `java.time.LocalDateTime.now()`,
+     * `field.date` → `java.time.LocalDate.now()`, `field.time` → `java.time.LocalTime.now()`. Each
+     * of those `java.time` types exposes a static `now()`. Fully-qualified so no import bookkeeping
+     * is needed (the four types would otherwise collide on simple names across generated files).
+     */
+    fun nowExpr(field: com.metaobjects.field.MetaField<*>): String {
+        val tn = kotlinTypeName(field)
+        val fqn = (tn as? ClassName)?.canonicalName ?: tn.toString()
+        return "$fqn.now()"
+    }
 }

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

@@ -170,6 +170,56 @@ class KotlinAutoSetStampingTest {
             "a date-only @autoSet must not emit Instant.now(); saw:\n$src")
     }
 
+    // === #203 / ADR-0045 — the generated Spring CONTROLLER (the deployed API surface) must ALSO
+    // === stamp @autoSet, not just the repository: the controller does its own inline Exposed writes
+    // === and never delegates to the repository, so an adopter deploying it must still get stamping.
+
+    private fun generateController(name: String, fixture: String, relPath: String): String {
+        val outDir = Files.createTempDirectory("kautoset-ctl-")
+        try {
+            KotlinSpringControllerGenerator().apply { setArgs(mapOf("outputDir" to outDir.toString())) }
+                .execute(loadString(name, fixture))
+            val f = outDir.resolve(relPath)
+            assertTrue(Files.exists(f), "expected generated file $f; files=${Files.walk(outDir).toList()}")
+            return Files.readString(f)
+        } finally {
+            outDir.toFile().deleteRecursively()
+        }
+    }
+
+    @Test fun `controller insert stamps both @autoSet columns from one captured now (createdAt == updatedAt)`() {
+        val src = generateController("autoset-event-ctl", autoSetFixture, "acme/events/EventController.kt")
+        // ONE captured now() val, assigned to BOTH columns → a fresh row's createdAt == updatedAt exactly.
+        assertTrue("val autoSetNow0 = java.time.Instant.now()" in src,
+            "insert must capture one now() val per temporal type; saw:\n$src")
+        assertTrue("it[createdAt] = autoSetNow0" in src && "it[updatedAt] = autoSetNow0" in src,
+            "insert must stamp BOTH @autoSet columns from the captured val; saw:\n$src")
+        assertTrue("dto.createdAt" !in src && "dto.updatedAt" !in src,
+            "an @autoSet column must never be bound from the caller dto; saw:\n$src")
+    }
+
+    @Test fun `controller patch bumps onUpdate on every patch and never rewrites onCreate`() {
+        val src = generateController("autoset-event-ctl2", autoSetFixture, "acme/events/EventController.kt")
+        assertTrue("it[EventTable.updatedAt] = java.time.Instant.now()" in src,
+            "patch must bump the onUpdate column; saw:\n$src")
+        assertTrue("it[EventTable.createdAt]" !in src,
+            "patch/update must never touch the onCreate column createdAt; saw:\n$src")
+        // onUpdate present ⇒ the update runs on EVERY patch (no "any present" guard).
+        assertTrue(".any { body.has(it) }" !in src,
+            "an onUpdate @autoSet controller must not gate the update behind an any-present check; saw:\n$src")
+        // @autoSet columns are not caller-settable in PATCH (never bound from the body).
+        assertTrue("body.get(\"updatedAt\")" !in src && "body.get(\"createdAt\")" !in src,
+            "an @autoSet column must not be a PATCH-bindable field; saw:\n$src")
+    }
+
+    @Test fun `a non-@autoSet controller stays byte-identical - no stamping, keeps the patch guard`() {
+        val src = generateController("autoset-note-ctl", autoSetFixture, "acme/events/NoteController.kt")
+        assertTrue("autoSetNow" !in src, "a non-@autoSet controller must not capture a now() val; saw:\n$src")
+        assertTrue(".now()" !in src, "a non-@autoSet controller must not stamp now(); saw:\n$src")
+        assertTrue(".any { body.has(it) }" in src,
+            "a non-@autoSet controller keeps the any-present patch guard; saw:\n$src")
+    }
+
     @Test fun `the generated repository (with entity + table) compiles against Exposed`() {
         val outDir = Files.createTempDirectory("kautoset-cr-")
         try {

spec/decisions/ADR-0045-generated-api-surface-owns-write-semantics.md

@@ -0,0 +1,42 @@
+# ADR-0045: The generated API surface owns metamodel write semantics
+
+## Status
+
+**Accepted** (2026-07-23). Fixes the Kotlin + Python legs of `field.timestamp @autoSet` (issue #203 follow-up, #229): the shipped Kotlin generated Spring controller and Python generated FastAPI router did not stamp `@autoSet` timestamps, so an adopter deploying those artifacts silently lost a semantic the changelog says shipped in all five ports. Generalizes the FR-036 decision ("constraint validation must be enforced at the wire tier, not left decorative") from validation to *all* metamodel-guaranteed write semantics.
+
+## Context
+
+`field.timestamp @autoSet: onCreate|onUpdate` declares "**the generated CRUD stamps `now()` — the caller does not.**" #203 shipped this across all five ports, but a scoping pass for the cross-port parity gate (#229) found the stamping is implemented in a **different architectural layer per port**, and two ports' outermost generated write artifact does not honor it:
+
+| Port | `@autoSet` stamped in | Generated **API-surface** artifact guarantees it? |
+|---|---|---|
+| TS | codegen Zod validators, called by the emitted routes | ✅ |
+| C# | generated routes (`RoutesGenerator`) | ✅ |
+| Java | generated controller/DTO (`stampForInsert` / `stampAutoSetOnUpdate`), *then* delegates to the consumer repository seam | ✅ |
+| Python | `ObjectManager` runtime only — the generated router delegates raw DTOs to a consumer repository seam | ❌ guarantee lives *below* the seam, in a MetaObjects runtime package the adopter may not wire |
+| Kotlin | generated Exposed **repository** only — the generated controller does its own inline `transaction { Table.insert{} }` writes, never uses the repository, has zero `@autoSet` awareness | ❌ shipped controller does not stamp |
+
+The generated **API surface** (the REST controller/routes an adopter deploys) is the outermost write artifact. When the `@autoSet` guarantee lives *below* a consumer-supplied seam (Python's repository `Protocol`; Kotlin's ignored repository), a metamodel-guaranteed semantic silently becomes a property of **hand-written consumer code** — a direct violation of "pattern-derivable from metadata = codegen, never hand-code." It also breaks the substrate promise: Python's only shipped stamping is in `ObjectManager` (a MetaObjects runtime package), so an adopter who wires their own persistence into the generated router gets a deployed API that quietly drops a shipped FR. "Generated code runs without MetaObjects" must include running *with the declared semantics* without MetaObjects.
+
+The gap survived because **no `@autoSet` scenario existed in `api-contract-conformance` or `persistence-conformance`** — the wire tier was never gated for it. This is the same class of hole FR-036 closed for constraint validation (decorative in C#/Python until the wire tier was made to enforce it).
+
+## Decision
+
+**The outermost generated write-path artifact an adopter deploys must itself guarantee every metamodel-declared write semantic. No consumer-supplied seam may sit between the guarantee and the wire.**
+
+1. **API surface stamps.** A generated REST controller / route handler stamps `@autoSet` (and enforces the analogous FR-036 constraint checks) in the generated code, before any consumer-supplied persistence seam. Java is the canonical shape: stamp in the controller/DTO, *then* delegate to the repository — layering and semantic-ownership are orthogonal.
+2. **Persistence-layer stamping stays** as the carrier for non-HTTP writes (the runtime pillar) and as defense-in-depth. Kotlin's generated repository, Python's `ObjectManager`, and any ORM-tier stamping are retained. Double-stamping is idempotent-harmless (two `now()` reads, same semantics). The rule is **not** "only the API layer stamps"; it is "the generated API artifact never *depends* on an unspecified layer beneath it for a metamodel-guaranteed write semantic."
+3. **Conformance gates the wire tier.** The `@autoSet` write contract is gated in `api-contract-conformance` on every port's generated *and* reference lane, with **behavioral** assertions (a fresh insert's `createdAt == updatedAt`; a later update leaves `createdAt` and bumps `updatedAt`; caller-supplied `@autoSet` values are ignored) — field-vs-field comparisons, not exact-match, since `now()` is nondeterministic. The absence of such an assertion vocabulary is what let a non-stamping controller ship green.
+4. **Not breaking, no new vocabulary.** `@autoSet` is an existing registered attr; this changes only *where* the guarantee is enforced in generated output. Output for entities with no `@autoSet` field is byte-identical (pinned by no-churn tests).
+
+### Why not the alternatives
+
+- **Rewire the Kotlin controller to delegate to the generated repository** (so the repository's stamping applies): rejected as the vehicle for this fix. The generated controller already handles TPH, #214 write-through read-views, M:N traversal, and FR-009 filters; the generated repository is FR-035 Phase-2 work with explicit gaps (no TPH polymorphic surface, no read-only view repository). Routing the controller through it is a feature-parity project that would churn all generated output and block a semantics bug on Phase-2 completion. It may be reconsidered later on its own merits; it is not this decision.
+- **Leave stamping persistence-only + document it**: rejected — the shipped artifact violates a contract the changelog states shipped in all five ports. That is a bug, not a documentable choice.
+- **Move *all* ports to persistence-only stamping** (make Python/Kotlin the model): rejected — it inverts the substrate promise (the deployable artifact would depend on a specific persistence layer for a declared semantic) and diverges from TS/C#/Java, where the API surface already owns it.
+
+### Precedent alignment
+
+- **FR-036** (constraint validation must be enforced at the wire tier across all ports) is the same call for the sibling write semantic; `@autoSet` and constraint-validation even interlock (every port's insert schema already makes an `@autoSet @required` field optional-on-POST *because* the server fills it).
+- **ADR-0023** (strict provenance) is unaffected: no new vocabulary, purely where a generator enforces an existing attr.
+- Ships as a coordinated bug-fix change (Kotlin controller + Python router/model + the api-contract `@autoSet` gate), landed together so no lane reds — per the repo's "never commit a scenario ports can't pass" rule.