feat(fr-035): present-key PATCH tristate — Java port

Green the cross-port `update-explicit-null-clears` gate on the Java GENERATED
api-contract lane (the reference lane already passed). The generated controller
bound the full `@Valid @RequestBody <Entity>Dto`, so a partial PATCH that omits a
@required field 400'd (its @NotNull) and an explicit null was indistinguishable
from absent after Jackson binding — it could neither clear a column nor honor the
tristate. Move the generated update path off full-DTO binding onto a
presence-tracked patch:

- codegen-spring: `SpringDtoGenerator` now emits a `<Entity>Patch` alongside each
  `<Entity>Dto` (settable = scalar fields minus the PK; `has<F>()`/`<f>()`
  accessors; `fromJson(JsonNode, ObjectMapper)` — a non-object body or an explicit
  null on a @required field is a `PatchValidationException`, a present null on a
  non-required field is stored (clears), an absent key is untouched, a present
  value binds via `mapper.treeToValue(node, TypeReference<Type>)` so generic
  element types and inline enums survive). Emitting the Patch from the DTO
  generator — which every consumer already runs — means a re-run of an existing
  `<generators>` config can't produce a controller/repository that references a
  missing `<Entity>Patch`.
- `SpringRepositoryGenerator`: the non-TPH interface gains
  `Optional<Dto> patch(pk, <Entity>Patch)` (keeps `update` for full-merge use;
  the TPH per-subtype interface is untouched).
- `SpringControllerGenerator`: the non-TPH update handler binds `@RequestBody
  JsonNode`, constructor-injects `ObjectMapper`, builds the patch, maps a
  `PatchValidationException` → 400 `{"error":"validation"}`, then calls
  `repository.patch`.
- `SpringDtoGenerator.isRequired` is the SINGLE required-predicate shared by the
  DTO's `@NotNull` and the patch's present-null-on-@required rule (can't drift).
- reference server + in-memory reference repos implement the tristate merge; an
  inline-enum compile-run test (`SpringPatchEnumCompileRunTest`) gates the
  `<Entity>Dto.<EnumName>` qualification.

Known gap (KNOWN_GAPS.md): the partial-PATCH path does not run `@Size`/`@Pattern`/
`@NotBlank`/etc. constraint validation on present VALUES (only null-on-@required
→ 400) — a cross-port PATCH-4 follow-up; TS/Python enforce it, C#/Java don't yet.

Gate green both Java lanes (23/0 each); codegen-spring 165/0; jsonb 1/0, m2m 3/0,
tph generated 5/0; full integration-tests reactor green.

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

Author: dmealing

server/java/codegen-spring/src/main/java/com/metaobjects/generator/spring/KNOWN_GAPS.md

@@ -117,3 +117,18 @@ escaping. Field names and enum members are identifier-safe and alias
 *values* are canonical members, so the only at-risk input is an
 `@enumAlias` *key* containing a `"` or `\`. Add a `javaStringLiteral(...)`
 escape if adopters hit it.
+
+## FR-035 partial PATCH — no present-value constraint validation
+
+The generated `PATCH`/`PUT` handler binds a raw `JsonNode` and builds an
+`<Entity>Patch` (presence-tracked), rather than an `@Valid` DTO. This is what
+gives it the FR-035 tristate (absent ≠ explicit null), but it means the
+`jakarta.validation` constraints the DTO carries — `@Size` / `@Pattern` /
+`@NotBlank` / `@Email` / `@Min` / `@Max` — are **not** enforced on *present
+values* over the PATCH path. The only PATCH-time validation is
+present-null-on-`@required` → HTTP 400 (via `PatchValidationException`).
+
+This is a cross-port PATCH-4 follow-up: TS/Python DO run per-field value
+validation on PATCH; C# and Java do not yet. Tracked here rather than fixed —
+adding constraint validation to the patch path (re-running the same rules the
+DTO's annotations express) is a deliberate, separately-scoped change.

server/java/codegen-spring/src/main/java/com/metaobjects/generator/spring/SpringControllerGenerator.java

@@ -174,6 +174,9 @@ protected void emit(MetaObject entity, Path outRoot) {
         if (!pkg.isEmpty()) {
             src.append("package ").append(pkg).append(";\n\n");
         }
+        src.append("import com.fasterxml.jackson.databind.JsonNode;\n");
+        src.append("import com.fasterxml.jackson.databind.ObjectMapper;\n");
+        src.append("import com.metaobjects.generator.spring.runtime.PatchValidationException;\n");
         src.append("import org.springframework.http.HttpStatus;\n");
         src.append("import org.springframework.http.ResponseEntity;\n");
         src.append("import org.springframework.web.bind.annotation.DeleteMapping;\n");
@@ -210,10 +213,15 @@ protected void emit(MetaObject entity, Path outRoot) {
         src.append(");\n\n");
 
         // Repository wiring — constructor injection (Spring's recommended idiom; avoids
-        // field-injection magic, plays well with final fields + final test seams).
-        src.append("    private final ").append(repoName).append(" repository;\n\n");
-        src.append("    public ").append(controllerName).append("(").append(repoName).append(" repository) {\n");
+        // field-injection magic, plays well with final fields + final test seams). The
+        // ObjectMapper (Spring's configured bean) binds the FR-035 patch body's per-field
+        // values via <Entity>Patch.fromJson, so the same wire codecs apply as on create.
+        src.append("    private final ").append(repoName).append(" repository;\n");
+        src.append("    private final ObjectMapper objectMapper;\n\n");
+        src.append("    public ").append(controllerName).append("(").append(repoName)
+           .append(" repository, ObjectMapper objectMapper) {\n");
         src.append("        this.repository = repository;\n");
+        src.append("        this.objectMapper = objectMapper;\n");
         src.append("    }\n\n");
 
         // GET (list) — pagination + sort + withCount + FR-009 filter operators.
@@ -273,10 +281,23 @@ protected void emit(MetaObject entity, Path outRoot) {
         // Stacking @PatchMapping + @PutMapping on the same method does NOT register both
         // in Spring MVC — only one composed @RequestMapping per method is honored, so the
         // other verb 405s. (Surfaced by the SP-F generated-controller HTTP lane.)
+        // FR-035 present-key PATCH: bind the RAW JsonNode (not the @Valid full DTO, which
+        // conflates absent with null and 400s an omitted @required field), build the
+        // presence-tracked <Entity>Patch, and delegate to repository.patch. An explicit
+        // null clears a nullable column; an explicit null on a @required field throws
+        // PatchValidationException → 400 {"error":"validation"}. update(id, dto) stays on
+        // the interface for programmatic full-DTO use.
+        String patchName = SpringNaming.patchName(shortName);
         src.append("    @RequestMapping(value = \"/{id}\", method = { RequestMethod.PATCH, RequestMethod.PUT })\n");
         src.append("    public ResponseEntity<?> update(@PathVariable ").append(pkType)
-           .append(" id, @Valid @RequestBody ").append(dtoName).append(" dto) {\n");
-        src.append("        return repository.update(id, dto)\n");
+           .append(" id, @RequestBody JsonNode body) {\n");
+        src.append("        ").append(patchName).append(" patch;\n");
+        src.append("        try {\n");
+        src.append("            patch = ").append(patchName).append(".fromJson(body, objectMapper);\n");
+        src.append("        } catch (PatchValidationException e) {\n");
+        src.append("            return ResponseEntity.badRequest().body(Map.of(\"error\", \"validation\"));\n");
+        src.append("        }\n");
+        src.append("        return repository.patch(id, patch)\n");
         src.append("                .<ResponseEntity<?>>map(ResponseEntity::ok)\n");
         src.append("                .orElseGet(() -> ResponseEntity.status(HttpStatus.NOT_FOUND).body(Map.of(\"error\", \"not_found\")));\n");
         src.append("    }\n\n");

server/java/codegen-spring/src/main/java/com/metaobjects/generator/spring/SpringDtoGenerator.java

@@ -9,6 +9,7 @@
 import com.metaobjects.generator.GeneratorIOWriter;
 import com.metaobjects.generator.direct.MultiFileDirectGeneratorBase;
 import com.metaobjects.generator.util.GeneratorUtil;
+import com.metaobjects.identity.MetaIdentity;
 import com.metaobjects.loader.MetaDataLoader;
 import com.metaobjects.object.MetaObject;
 import com.metaobjects.validator.ArrayValidator;
@@ -94,6 +95,17 @@ public void execute(MetaDataLoader loader) {
             // (each folded nullable) so polymorphic + per-subtype endpoints share one wire shape.
             if (TphPlan.isTphBase(entity, loader)) emitTphUnion(entity, loader, outRoot);
             else emit(entity, outRoot);
+            // FR-035: a presence-tracked <Entity>Patch alongside the DTO, for exactly the
+            // entities whose non-TPH repository interface gains patch(...) — a concrete
+            // writable table entity that is neither a TPH base nor a TPH subtype. Emitted
+            // from THIS generator (which every consumer already runs) so a re-run of an
+            // existing <generators> config that omits a separate patch generator cannot
+            // produce a controller/repository that references a missing <Entity>Patch.
+            if (SpringRepositoryGenerator.appliesTo(entity)
+                    && !TphPlan.isTphBase(entity, loader)
+                    && !TphPlan.isTphSubtype(entity)) {
+                emitPatch(entity, outRoot);
+            }
         }
     }
 
@@ -125,6 +137,127 @@ protected void emit(MetaObject entity, Path outRoot) {
         emitRecord(entity, outRoot, fields, annotationsPerField);
     }
 
+    /**
+     * FR-035: emit the presence-tracked {@code <Entity>Patch} — a sibling of the DTO that
+     * carries the absent / null / value tristate a record cannot. Only the caller-settable
+     * fields (scalar fields MINUS the primary key) are members; {@code has<F>()} reports
+     * presence (incl. an explicit null), {@code <f>()} the value. {@code fromJson} rejects a
+     * non-object body, binds present values via Jackson exactly as create does, clears a
+     * non-{@code @required} field on an explicit null, and throws a
+     * {@code PatchValidationException} on an explicit null on a {@code @required} field (the
+     * controller maps both to HTTP 400). Emitted here — from the DTO generator every consumer
+     * already runs — so no separate generator can be forgotten and leave a controller /
+     * repository referencing a missing {@code <Entity>Patch}.
+     */
+    private void emitPatch(MetaObject entity, Path outRoot) {
+        String[] split = SpringNaming.splitFqn(entity.getName());
+        String pkg = split[0];
+        String shortName = split[1];
+        String patchName = SpringNaming.patchName(shortName);
+        String dtoName = SpringNaming.dtoName(shortName);
+        List<MetaField> settable = settableFields(entity);
+
+        StringBuilder src = new StringBuilder();
+        if (!pkg.isEmpty()) src.append("package ").append(pkg).append(";\n\n");
+        src.append("import com.fasterxml.jackson.core.JsonProcessingException;\n");
+        src.append("import com.fasterxml.jackson.core.type.TypeReference;\n");
+        src.append("import com.fasterxml.jackson.databind.JsonNode;\n");
+        src.append("import com.fasterxml.jackson.databind.ObjectMapper;\n");
+        src.append("import com.metaobjects.generator.spring.runtime.PatchValidationException;\n");
+        src.append("import java.util.LinkedHashMap;\n");
+        src.append("import java.util.Map;\n");
+        src.append("import java.util.Set;\n\n");
+        src.append("/** GENERATED — presence-tracked partial-update (PATCH) shape for ")
+           .append(shortName).append(". Do not hand-edit; regenerated from metadata. */\n");
+        src.append("public final class ").append(patchName).append(" {\n\n");
+        src.append("    private final Map<String, Object> assigned;\n\n");
+        src.append("    private ").append(patchName)
+           .append("(Map<String, Object> assigned) { this.assigned = assigned; }\n\n");
+
+        // Per settable field: has<Field>() (presence, incl. explicit null) + <field>() (value).
+        for (MetaField field : settable) {
+            String name = field.getName();
+            String cap = SpringNaming.capitalize(name);
+            String type = patchComponentType(field, entity, dtoName);
+            src.append("    public boolean has").append(cap)
+               .append("() { return assigned.containsKey(\"").append(name).append("\"); }\n");
+            src.append("    public ").append(type).append(' ').append(name).append("() { return (")
+               .append(type).append(") assigned.get(\"").append(name).append("\"); }\n");
+        }
+        src.append("\n    /** The field names ASSIGNED by this patch (present in the body), in order. */\n");
+        src.append("    public Set<String> assignedFields() { return assigned.keySet(); }\n\n");
+
+        // fromJson — the presence-tracked builder.
+        src.append("    /**\n");
+        src.append("     * Build from a JSON body. A non-object body is rejected; an ABSENT key is\n");
+        src.append("     * untouched; a present null CLEARS a non-@required field and is a validation\n");
+        src.append("     * error on a @required one; a present value binds via Jackson exactly as\n");
+        src.append("     * create does. Unknown keys are ignored (FR-035 PATCH-3 deferred).\n");
+        src.append("     */\n");
+        src.append("    public static ").append(patchName)
+           .append(" fromJson(JsonNode body, ObjectMapper mapper) {\n");
+        src.append("        if (!body.isObject()) throw new PatchValidationException(\"(request body)\");\n");
+        src.append("        Map<String, Object> assigned = new LinkedHashMap<>();\n");
+        for (MetaField field : settable) {
+            String name = field.getName();
+            String type = patchComponentType(field, entity, dtoName);
+            boolean required = isRequired(field);
+            // A TypeReference (not a raw Class) so a generic component — e.g. a
+            // field.<scalar> @isArray List<Long> — binds with its element type intact.
+            src.append("        bind(body, mapper, assigned, \"").append(name)
+               .append("\", new TypeReference<").append(type).append(">() {}, ")
+               .append(required).append(");\n");
+        }
+        src.append("        return new ").append(patchName).append("(assigned);\n");
+        src.append("    }\n\n");
+
+        // bind — one settable field. treeToValue lets Jackson handle every subtype (no hand-rolled arms).
+        src.append("    private static void bind(JsonNode body, ObjectMapper mapper, Map<String, Object> assigned,\n");
+        src.append("            String field, TypeReference<?> type, boolean required) {\n");
+        src.append("        if (!body.has(field)) return;                         // absent → untouched\n");
+        src.append("        JsonNode node = body.get(field);\n");
+        src.append("        if (node.isNull()) {\n");
+        src.append("            if (required) throw new PatchValidationException(field);\n");
+        src.append("            assigned.put(field, null);                         // explicit null → clear\n");
+        src.append("            return;\n");
+        src.append("        }\n");
+        src.append("        try {\n");
+        src.append("            assigned.put(field, mapper.treeToValue(node, type));\n");
+        src.append("        } catch (JsonProcessingException e) {\n");
+        src.append("            throw new PatchValidationException(field);\n");
+        src.append("        }\n");
+        src.append("    }\n");
+        src.append("}\n");
+
+        writeJavaFile(entity, outRoot, pkg, patchName, src.toString());
+    }
+
+    /** Scalar (non-object) fields MINUS the primary-key field(s) — the caller-settable set. */
+    private static List<MetaField> settableFields(MetaObject entity) {
+        List<String> pkFields = entity.getIdentities(true).stream()
+            .filter(MetaIdentity::isPrimary)
+            .findFirst()
+            .map(MetaIdentity::getFields)
+            .orElse(List.of());
+        List<MetaField> out = new ArrayList<>();
+        for (MetaField field : scalarFields(entity)) {
+            if (!pkFields.contains(field.getName())) out.add(field);
+        }
+        return out;
+    }
+
+    /** The {@code <Entity>Patch} component type for {@code field}. Identical to the DTO's
+     *  FR-019-aware {@link #componentTypeFr019} EXCEPT for an INLINE {@code field.enum}: its
+     *  enum is declared nested in the DTO record body, so the sibling {@code <Entity>Patch}
+     *  must qualify it as {@code <Entity>Dto.<EnumName>}. A shared / materialized / {@code @provided}
+     *  enum is a top-level type, resolvable unqualified. */
+    private String patchComponentType(MetaField<?> field, MetaObject entity, String dtoName) {
+        if (field instanceof EnumField && Fr019SharedEnum.sharedEnumForField(field) == null) {
+            return SpringTypeMapper.payloadJavaTypeName(field, entity, dtoName + ".");
+        }
+        return componentTypeFr019(field, entity);
+    }
+
     /**
      * FR-017 TPH: emit the discriminator-base DTO as the UNION of the base's own scalar columns
      * (full validation) plus every subtype-only column (folded NULLABLE — no validation, since a
@@ -348,6 +481,14 @@ private static List<String> collectEnumDecls(MetaObject owner, List<MetaField> f
         return decls;
     }
 
+    /** True iff {@code field} is {@code @required} — its own {@code @required} attr OR a
+     *  {@code validator.required} child. The SINGLE required-predicate reused across the
+     *  DTO's {@code @NotNull} and the FR-035 patch's present-null-on-@required → 400 rule
+     *  (the FR-035 patch emit below), so the two cannot drift. */
+    public static boolean isRequired(MetaField<?> field) {
+        return attrBool(field, MetaField.ATTR_REQUIRED) || hasValidator(field, RequiredValidator.class);
+    }
+
     /**
      * Build the space-joined jakarta.validation annotation string for a record
      * component from the field's constraint metadata — both field attrs
@@ -372,7 +513,7 @@ public static String validationAnnotations(MetaField<?> field) {
         boolean isString = field instanceof StringField;
         List<String> out = new ArrayList<>();
 
-        boolean required = attrBool(field, MetaField.ATTR_REQUIRED) || hasValidator(field, RequiredValidator.class);
+        boolean required = isRequired(field);
         if (required) {
             out.add("@NotNull");
             if (isString && !isArray) out.add("@NotBlank");

server/java/codegen-spring/src/main/java/com/metaobjects/generator/spring/SpringNaming.java

@@ -96,6 +96,11 @@ public static String repositoryName(String shortName) {
         return shortName + "Repository";
     }
 
+    /** {@code SpringDtoGenerator} (FR-035): {@code shortName + "Patch"} — the presence-tracked patch shape. */
+    public static String patchName(String shortName) {
+        return shortName + "Patch";
+    }
+
     /** {@code SpringControllerGenerator}: {@code shortName + "Controller"}. */
     public static String controllerName(String shortName) {
         return shortName + "Controller";

server/java/codegen-spring/src/main/java/com/metaobjects/generator/spring/SpringRepositoryGenerator.java

@@ -116,6 +116,12 @@ protected void emit(MetaObject entity, Path outRoot) {
         src.append("    ").append(dtoName).append(" create(").append(dtoName).append(" dto);\n");
         src.append("    Optional<").append(dtoName).append("> update(").append(pkType).append(" id, ")
            .append(dtoName).append(" dto);\n");
+        // FR-035: presence-tracked partial update. The <Entity>Patch carries the
+        // absent/null/value tristate the full DTO cannot, so an explicit null clears a
+        // nullable column (an explicit null on a @required field is rejected at the
+        // controller). Same package as the interface — no import needed.
+        src.append("    Optional<").append(dtoName).append("> patch(").append(pkType).append(" id, ")
+           .append(SpringNaming.patchName(shortName)).append(" patch);\n");
         src.append("    boolean delete(").append(pkType).append(" id);\n");
 
         // FR-018 M:N finders — one per @cardinality:"many" + @through relationship.

server/java/codegen-spring/src/main/java/com/metaobjects/generator/spring/runtime/PatchValidationException.java

@@ -0,0 +1,22 @@
+package com.metaobjects.generator.spring.runtime;
+
+/**
+ * Thrown by a generated {@code <Entity>Patch.fromJson(...)} when a PATCH body fails
+ * FR-035 validation — specifically an explicit {@code null} on a {@code @required}
+ * field. The generated controller catches it and maps it to the cross-port HTTP 400
+ * {@code {"error":"validation"}} envelope.
+ */
+public final class PatchValidationException extends RuntimeException {
+
+    private final String field;
+
+    public PatchValidationException(String field) {
+        super("field '" + field + "' cannot be null");
+        this.field = field;
+    }
+
+    /** The offending field name. */
+    public String field() {
+        return field;
+    }
+}

server/java/codegen-spring/src/test/java/com/metaobjects/generator/spring/GeneratedM2mTraversalCompileRunTest.java

@@ -250,6 +250,7 @@ public InMemoryPostRepository(List<Map<String, Object>> tagRows,
             @Override public Optional<PostDto> findById(Long id) { return Optional.empty(); }
             @Override public PostDto create(PostDto dto) { return dto; }
             @Override public Optional<PostDto> update(Long id, PostDto dto) { return Optional.empty(); }
+            @Override public Optional<PostDto> patch(Long id, PostPatch patch) { return Optional.empty(); }
             @Override public boolean delete(Long id) { return false; }
         }
         """;
@@ -314,6 +315,7 @@ private List<PersonDto> loadPeople(List<Object> ids) {
             @Override public Optional<PersonDto> findById(Long id) { return Optional.empty(); }
             @Override public PersonDto create(PersonDto dto) { return dto; }
             @Override public Optional<PersonDto> update(Long id, PersonDto dto) { return Optional.empty(); }
+            @Override public Optional<PersonDto> patch(Long id, PersonPatch patch) { return Optional.empty(); }
             @Override public boolean delete(Long id) { return false; }
         }
         """;