@@ -199,3 +199,21 @@ requests:
       primaryMarker: { label: null, score: 4 }
     expect:
       status: 400
+
+  # --- PATCH wrong SHAPE: a JSON object for an array-of-VO column -> 400 (not 500) ---
+  - id: r21
+    method: PATCH
+    path: /api/documents/1
+    body:
+      markers: { label: "x", score: 1 }
+    expect:
+      status: 400
+
+  # --- PATCH wrong SHAPE: a JSON array for a single-VO column -> 400 (not 500) ---
+  - id: r22
+    method: PATCH
+    path: /api/documents/1
+    body:
+      primaryMarker: [ { label: "x", score: 1 } ]
+    expect:
+      status: 400
@@ -98,6 +98,11 @@
       "tier": "native",
       "ports": ["java"]
     },
+    "value-object": {
+      "concept": "Per-value-object Spring record with jakarta constraints (the DTO/Patch bind target for a field.object jsonb column).",
+      "tier": "native",
+      "ports": ["java"]
+    },
     "exposed-table": {
       "concept": "Per-entity Kotlin Exposed table object.",
       "tier": "native",
 
@@ -500,7 +500,13 @@ private static void AppendCreateHandler(
         sb.Append(string.Join(", ", requiredKeys.Select(k => "\"" + k + "\"")));
         sb.AppendLine(" })");
         sb.AppendLine("                if (!__present.Contains(__req)) return Results.BadRequest(new { error = \"validation\" });");
-        sb.AppendLine($"            var input = System.Text.Json.JsonSerializer.Deserialize<{cls}>(__body.RootElement.GetRawText(), jsonOpts);");
+        // A malformed body (e.g. a JSON array for a single-VO / scalar for an object column)
+        // throws JsonException — return the cross-port 400 {error:"validation"} rather than an
+        // unhandled 500 (matches the no-required-keys path's automatic model-binding 400, and
+        // every other port). Program D — the VO columns make wrong-shaped bodies reachable.
+        sb.AppendLine($"            {cls} input;");
+        sb.AppendLine("            try { input = System.Text.Json.JsonSerializer.Deserialize<" + cls + ">(__body.RootElement.GetRawText(), jsonOpts); }");
+        sb.AppendLine("            catch (System.Text.Json.JsonException) { return Results.BadRequest(new { error = \"validation\" }); }");
         sb.AppendLine("            if (input is null) return Results.BadRequest(new { error = \"validation\" });");
         AppendCreateValidation(sb);
         AppendCreateVoValidation(sb, voFields);
@@ -610,7 +616,12 @@ private static void AppendPartialMergeLoop(StringBuilder sb, string? discProp, I
                 sb.AppendLine("                        continue;");
             }
             sb.AppendLine("                    }");
-            sb.AppendLine($"                    var {v} = System.Text.Json.JsonSerializer.Deserialize<{vf.DeserType}>(prop.Value.GetRawText(), jsonOpts);");
+            // A wrong-shaped VO value (e.g. a JSON array for a single-VO column, an object for an
+            // array column) throws JsonException — return the cross-port 400 rather than an
+            // unhandled 500 (matches every other port + this port's own reference lane).
+            sb.AppendLine($"                    {vf.DeserType} {v};");
+            sb.AppendLine($"                    try {{ {v} = System.Text.Json.JsonSerializer.Deserialize<{vf.DeserType}>(prop.Value.GetRawText(), jsonOpts); }}");
+            sb.AppendLine("                    catch (System.Text.Json.JsonException) { return Results.BadRequest(new { error = \"validation\" }); }");
             sb.AppendLine($"                    if (!ValueObjectValidator.Validate({v})) return Results.BadRequest(new {{ error = \"validation\" }});");
             sb.AppendLine($"                    existing.{vf.Nav} = {v}{(vf.Required ? "!" : "")};");
             sb.AppendLine("                    continue;");
 
@@ -161,7 +161,11 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
         // ctor param / TypeReference import (they'd be unused → allWarningsAsErrors).
         val patchSettableFields = entity.metaFields.filter {
             it !is MapField && it.name != pkFieldName &&
-                !KotlinTypeMapper.isJsonbOpenBag(it)
+                !KotlinTypeMapper.isJsonbOpenBag(it) &&
+                // Program D: only a jsonb value-object column is settable. A flattened object
+                // field (@storage:flattened) is materialised by the Exposed table as per-subfield
+                // columns — there is no single `Table.<field>` to bind — so it stays excluded.
+                (it !is ObjectField || isJsonbObjectColumn(it))
         }
         val hasPatchFields = patchSettableFields.isNotEmpty()
 
@@ -303,7 +307,9 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
             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 MapField) continue
+                // MapField (staged out) and a flattened object field (materialised as per-subfield
+                // columns, no single `Table.<field>`) are skipped — the data class defaults them.
+                if (field is MapField || (field is ObjectField && !isJsonbObjectColumn(field))) continue
                 append("    ${field.name} = row[${tableObjectName}.${field.name}],\n")
             }
             append(")\n\n")
@@ -378,8 +384,9 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
             for (field in entity.metaFields) {
                 // 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
+                // encodes it to jsonb. MapField (dict-of-VO) stays skipped (staged out); a flattened
+                // object field (no single `Table.<field>`) is skipped too.
+                if (field is MapField || (field is ObjectField && !isJsonbObjectColumn(field))) 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.
@@ -1310,6 +1317,19 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
         return runCatching { field.getMetaAttr(ObjectField.ATTR_OBJECTREF, true).valueAsString }.getOrNull()
     }
 
+    /**
+     * True iff [field] is a `field.object` stored as a single jsonb column (`@storage` != flattened,
+     * the default). The Exposed table emits one `Table.<field>` column only for these — a flattened
+     * object field is materialised as per-subfield columns, so the controller must NOT reference
+     * `Table.<field>` for it (it is skipped, defaulting to null in the data class). Mirrors
+     * [KotlinExposedTableGenerator]'s `readStorage != STORAGE_FLATTENED` column check.
+     */
+    private fun isJsonbObjectColumn(field: ObjectField): Boolean {
+        if (!field.hasMetaAttr(ObjectField.ATTR_STORAGE, true)) return true   // default = single jsonb column
+        val storage = runCatching { field.getMetaAttr(ObjectField.ATTR_STORAGE, true).valueAsString }.getOrNull()
+        return !STORAGE_FLATTENED.equals(storage?.trim(), ignoreCase = true)
+    }
+
     /**
      * 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
@@ -1327,6 +1347,11 @@ open class KotlinSpringControllerGenerator : MultiFileDirectGeneratorBase<MetaOb
         /** Default primary-key field name when the entity declares no identity.primary. */
         const val DEFAULT_PK_FIELD = "id"
 
+        /** `@storage:flattened` on a field.object — the one storage mode the controller excludes
+         *  (materialised as per-subfield columns, not a single jsonb `Table.<field>`). Cross-language
+         *  @storage vocabulary; mirrors KotlinExposedTableGenerator's constant. */
+        const val STORAGE_FLATTENED = "flattened"
+
         @JvmStatic
         val LOG = LoggerFactory.getLogger(KotlinSpringControllerGenerator::class.java)
     }
 
@@ -11,6 +11,7 @@
 import com.metaobjects.generator.spring.SpringPayloadGenerator;
 import com.metaobjects.generator.spring.SpringRenderHelperGenerator;
 import com.metaobjects.generator.spring.SpringRepositoryGenerator;
+import com.metaobjects.generator.spring.SpringValueObjectGenerator;
 import com.metaobjects.render.templategen.TemplateGenerator;
 
 import java.util.Collections;
@@ -119,6 +120,9 @@ private static Map<String, GeneratorInfo> buildRegistry() {
                 "Per-entity Spring Data repository.", Tier.NATIVE);
         register(m, "dto", SpringDtoGenerator.class.getName(),
                 "Per-entity Spring DTO record.", Tier.NATIVE);
+        register(m, "value-object", SpringValueObjectGenerator.class.getName(),
+                "Per-value-object Spring record with jakarta constraints — the typed "
+                    + "component the DTO/Patch bind for a field.object @storage:jsonb column.", Tier.NATIVE);
         register(m, "trace-helper", LlmTraceHelperGenerator.class.getName(),
                 "Per-entity typed record<Entity> LLM-trace helper (extract + buildLlmCallRow + persist; "
                     + "LlmCallBase-derived entities only).", Tier.NATIVE);
 
@@ -57,13 +57,15 @@ private JavaFieldShapes() { /* no instances */ }
 
     /**
      * The DTO record's documented field shapes for {@code entity}: one
-     * {@link FieldShape} per scalar field the {@link SpringDtoGenerator} emits.
-     * Reuses the generator's scalar-field iteration, component-type mapping, and
-     * validation-annotation derivation so the docs can't drift from the record.
+     * {@link FieldShape} per component field the {@link SpringDtoGenerator} emits —
+     * scalars PLUS value-object jsonb columns (Program D), matching the record's own
+     * {@link SpringDtoGenerator#dtoComponentFields} iteration. Reuses the generator's
+     * component-type mapping and validation-annotation derivation so the docs can't
+     * drift from the record (a @required VO column shows @NotNull → required).
      */
     public static List<FieldShape> dtoFields(MetaObject entity) {
         List<FieldShape> out = new ArrayList<>();
-        for (MetaField field : SpringDtoGenerator.scalarFields(entity)) {
+        for (MetaField field : SpringDtoGenerator.dtoComponentFields(entity)) {
             String type = SpringDtoGenerator.componentType(field, entity);
             String annotations = SpringDtoGenerator.validationAnnotations(field);
             // Required iff the DTO component carries @NotNull or @NotBlank — read
 
@@ -238,8 +238,22 @@ private Map<String, Object> rowFrom(ResultSet rs) throws SQLException {
 
     // --- nested value-object validation (Program D — mirrors the cross-port contract) --------
 
-    /** CREATE: primaryMarker required + valid; a present optional/array VO valid. */
+    /**
+     * The scalar {@code title} is {@code @required @maxLength 200}. A present title must be a
+     * non-empty string within the cap (FR-036: non-empty, whitespace allowed); a present-null /
+     * empty / over-length is a 400 — matching the generated {@code DocumentPatch}/DTO, so the
+     * reference lane does not instead hit the NOT NULL column and 500. Absence is the caller's
+     * concern (required on CREATE, untouched on PATCH).
+     */
+    private static boolean titlePresentValueValid(Map<String, Object> body) {
+        if (!body.containsKey("title")) return true;
+        Object t = body.get("title");
+        return t instanceof String s && !s.isEmpty() && s.length() <= 200;
+    }
+
+    /** CREATE: title required + valid; primaryMarker required + valid; a present optional/array VO valid. */
     private static boolean voValidForCreate(Map<String, Object> body) {
+        if (!body.containsKey("title") || !titlePresentValueValid(body)) return false;
         Object pm = body.get("primaryMarker");
         if (!body.containsKey("primaryMarker") || pm == null || !validMarker(pm)) return false;
         if (body.containsKey("optionalMarker")) {
@@ -253,8 +267,9 @@ private static boolean voValidForCreate(Map<String, Object> body) {
         return true;
     }
 
-    /** PATCH: present-null on required primaryMarker → invalid; a present value must be a valid VO. */
+    /** PATCH: a present title/VO value must be valid; present-null on a @required field → invalid. */
     private static boolean voValidForPatch(Map<String, Object> body) {
+        if (!titlePresentValueValid(body)) return false;   // present-null/empty/over-length title → 400
         if (body.containsKey("primaryMarker")) {
             Object pm = body.get("primaryMarker");
             if (pm == null || !validMarker(pm)) return false;   // present-null on @required → 400
 
@@ -10,7 +10,7 @@ import {
   FIELD_SUBTYPE_BOOLEAN, FIELD_SUBTYPE_UUID, FIELD_SUBTYPE_OBJECT,
   FIELD_ATTR_REQUIRED, FIELD_ATTR_MAX_LENGTH, FIELD_ATTR_DEFAULT,
   FIELD_ATTR_DB_COLUMN_TYPE, DB_COLUMN_TYPE_JSONB, FIELD_ATTR_OBJECT_REF,
-  PACKAGE_SEPARATOR,
+  PACKAGE_SEPARATOR, OBJECT_SUBTYPE_VALUE,
   VALIDATOR_ATTR_MIN, VALIDATOR_ATTR_MAX, VALIDATOR_ATTR_PATTERN,
 } from "@metaobjectsdev/metadata";
 import type { ValidationFailure } from "./errors.js";
@@ -211,18 +211,22 @@ export function runValidators(
 
 /** Resolve a `field.object`'s `@objectRef` to its value-object MetaData by walking
  *  to the tree root. The ref may be a bare name or a `pkg::Name` FQN. Mirrors the
- *  extract-object resolver. Returns undefined when unresolvable (→ no VO recursion).
+ *  extract-object resolver. Returns undefined when unresolvable OR when the target
+ *  is not an `object.value` (→ no VO recursion). Cross-port parity: C#/Java/Kotlin
+ *  gate the recursion on the ref being a value object, so a `field.object @objectRef`
+ *  pointing at a non-value object validates identically (skipped) on every port.
  *  ADR-0039: resolving — @objectRef may be inherited via extends. */
 function resolveVoRef(field: MetaData): MetaData | undefined {
   const ref = field.attr(FIELD_ATTR_OBJECT_REF);
   if (typeof ref !== "string" || ref.length === 0) return undefined;
   const root = field.root();
   if (!(root instanceof MetaRoot)) return undefined;
-  const direct = root.findObject(ref);
-  if (direct !== undefined) return direct;
-  const sep = ref.lastIndexOf(PACKAGE_SEPARATOR);
-  if (sep >= 0) return root.findObject(ref.slice(sep + PACKAGE_SEPARATOR.length));
-  return undefined;
+  let target = root.findObject(ref);
+  if (target === undefined) {
+    const sep = ref.lastIndexOf(PACKAGE_SEPARATOR);
+    if (sep >= 0) target = root.findObject(ref.slice(sep + PACKAGE_SEPARATOR.length));
+  }
+  return target?.subType === OBJECT_SUBTYPE_VALUE ? target : undefined;
 }
 
 function isRequired(field: MetaData): boolean {