feat(conformance): Phase B Unit 3 — Java read-path (temporal + projection)

Make Java's persistence-conformance pass the Phase B temporal + projection
scenarios against Testcontainers Postgres, matching the cross-port canonical
wire contract (fixtures/persistence-conformance/normalization.md). All work is
in the integration-tests runner — OMDB's generic metadata-driven read path is
unchanged.

Normalization.java:
  - TIME → "HH:MM:SS" (LocalTime/Time.toString() elided whole-second :00).
  - DATE → "YYYY-MM-DD" via an explicit formatter; added a java.util.Date branch
    (OMDB's DateField codec stores a DATE column as a midnight-anchored
    java.util.Date, which previously fell through to Date.toString()).
  - TIMESTAMPTZ → "...Z": added an OffsetDateTime branch that renders the UTC
    instant with a Z suffix; plain TIMESTAMP (Timestamp/LocalDateTime) renders
    with no Z. java.sql.Timestamp is matched before the generic java.util.Date
    branch (both extend java.util.Date).

ObjectManagerDbAdapter.java — coerceWireType reconciles OMDB's MetaField-typed
value with the ACTUAL SQL column type (the wire shape is column-driven, not
field.*-driven):
  - tz-flagged field.timestamp (@dbColumnType: timestamp_with_tz) → surface as
    an OffsetDateTime in UTC so Normalization appends Z. OMDB reads both plain
    and tz timestamps as the same java.sql.Timestamp and cannot tell them apart.
  - aggregate MIN/MAX(int) are declared field.long but are INTEGER view columns:
    INTEGER → JSON number, BIGINT → JSON string. OMDB reads both as Long; narrow
    to Integer when the catalog reports INTEGER/SMALLINT so the number form wins.

QueryScenarioRunner.java — probe each entity's primary relation (table or view)
column SQL types once via ResultSetMetaData (SELECT * ... WHERE 1=0), cached per
MetaObject, and thread the map into the adapter.

3 new query scenarios (normalization-wire-types, projection-passthrough,
projection-aggregates) + the Unit-1-updated existing ones now pass. Full Java
integration suite green: NormalizationFloatTest 4, QueryScenarioTests 14,
ApiContractConformanceTest 20 = 38, BUILD SUCCESS. No shared fixtures edited.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

server/java/integration-tests/src/test/java/com/metaobjects/integration/Normalization.java

@@ -10,6 +10,8 @@
 import java.time.LocalDate;
 import java.time.LocalDateTime;
 import java.time.LocalTime;
+import java.time.OffsetDateTime;
+import java.time.ZoneOffset;
 import java.time.format.DateTimeFormatter;
 import java.util.ArrayList;
 import java.util.Base64;
@@ -33,6 +35,10 @@ private Normalization() {}
 
     private static final DateTimeFormatter TIMESTAMP_FMT =
         DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss");
+    private static final DateTimeFormatter DATE_FMT =
+        DateTimeFormatter.ofPattern("yyyy-MM-dd");
+    private static final DateTimeFormatter TIME_FMT =
+        DateTimeFormatter.ofPattern("HH:mm:ss");
 
     public static Map<String, Object> normalizeRow(Map<String, Object> row) {
         TreeMap<String, Object> out = new TreeMap<>();
@@ -53,12 +59,29 @@ public static Object normalizeValue(Object v) {
         if (v instanceof BigDecimal bd) return canonicalDecimal(bd);
         if (v instanceof UUID u)   return u.toString().toLowerCase(java.util.Locale.ROOT);
         if (v instanceof byte[] bytes) return Base64.getEncoder().encodeToString(bytes);
-        if (v instanceof LocalDate d)  return d.toString();
-        if (v instanceof LocalTime t)  return t.toString();
-        if (v instanceof Time t)       return t.toLocalTime().toString();
-        if (v instanceof Timestamp ts) return ts.toLocalDateTime().format(TIMESTAMP_FMT);
+        if (v instanceof LocalDate d)  return d.format(DATE_FMT);
+        if (v instanceof LocalTime t)  return t.format(TIME_FMT);
+        if (v instanceof Time t)       return t.toLocalTime().format(TIME_FMT);
+        // TIMESTAMPTZ → UTC instant + "Z" suffix. The runner surfaces tz-aware
+        // timestamp columns as OffsetDateTime (normalized to UTC in
+        // ObjectManagerDbAdapter) so the zone discriminator survives — a plain
+        // TIMESTAMP arrives as Timestamp/LocalDateTime and renders with no Z.
+        if (v instanceof OffsetDateTime odt)
+            return odt.withOffsetSameInstant(ZoneOffset.UTC).toLocalDateTime().format(TIMESTAMP_FMT) + "Z";
         if (v instanceof LocalDateTime ts) return ts.format(TIMESTAMP_FMT);
-        if (v instanceof java.sql.Date sd)  return sd.toLocalDate().toString();
+        // java.sql.Date / java.sql.Timestamp BOTH extend java.util.Date, so order
+        // matters: the sql.Date (DATE column) → "YYYY-MM-DD"; sql.Timestamp and a
+        // plain util.Date carry a wall clock → "YYYY-MM-DDTHH:MM:SS" (no Z; a tz
+        // column is handled by the OffsetDateTime branch above). The JVM default
+        // zone is pinned to UTC by QueryScenarioTests so the wall clock is the UTC
+        // wall clock the cross-port fixtures expect.
+        if (v instanceof java.sql.Date sd)  return sd.toLocalDate().format(DATE_FMT);
+        if (v instanceof Timestamp ts) return ts.toLocalDateTime().format(TIMESTAMP_FMT);
+        if (v instanceof java.util.Date d) {
+            // OMDB's DateField codec stores a DATE column as a midnight-anchored
+            // java.util.Date; render the calendar date (UTC) per the DATE wire rule.
+            return DATE_FMT.format(d.toInstant().atZone(ZoneOffset.UTC));
+        }
         if (v instanceof CharSequence) return v.toString();
         if (v instanceof Map<?, ?> m) {
             TreeMap<String, Object> sorted = new TreeMap<>();

server/java/integration-tests/src/test/java/com/metaobjects/integration/ObjectManagerDbAdapter.java

@@ -12,6 +12,8 @@
 import com.metaobjects.object.MetaObject;
 import com.metaobjects.object.value.ValueObject;
 
+import java.sql.Types;
+import java.time.ZoneOffset;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.LinkedHashMap;
@@ -39,7 +41,8 @@ private ObjectManagerDbAdapter() {}
      *   <li>{@code op:count} → {@code Long}</li>
      * </ul>
      */
-    static Object execute(ObjectManagerDB omdb, ObjectConnection conn, MetaObject mc, QuerySpec spec) throws Exception {
+    static Object execute(ObjectManagerDB omdb, ObjectConnection conn, MetaObject mc, QuerySpec spec,
+                          Map<String, Integer> columnSqlTypes) throws Exception {
         Expression filter = buildFilter(spec.by(), spec.filter());
 
         if ("count".equals(spec.op())) {
@@ -53,7 +56,7 @@ static Object execute(ObjectManagerDB omdb, ObjectConnection conn, MetaObject mc
 
         Collection<?> raw = omdb.getObjects(conn, mc, opts);
         List<Map<String, Object>> rows = new ArrayList<>(raw.size());
-        for (Object o : raw) rows.add(toRowMap(mc, o));
+        for (Object o : raw) rows.add(toRowMap(mc, o, columnSqlTypes));
 
         if ("get".equals(spec.op())) return rows.isEmpty() ? null : rows.get(0);
         return rows; // op:list
@@ -221,20 +224,68 @@ private static Range buildRange(Integer offset, int limit) {
      * For non-ValueObject types the row is keyed by the field's metadata
      * name and the value is what {@link ObjectManagerDB} loaded.</p>
      */
-    private static Map<String, Object> toRowMap(MetaObject mc, Object instance) {
+    private static Map<String, Object> toRowMap(MetaObject mc, Object instance,
+                                                Map<String, Integer> columnSqlTypes) {
         Map<String, Object> row = new LinkedHashMap<>();
         if (instance instanceof ValueObject vo) {
-            for (MetaField<?> mf : mc.getMetaFields()) row.put(mf.getName(), maybeParseJson(mf, vo.get(mf.getName())));
+            for (MetaField<?> mf : mc.getMetaFields())
+                row.put(mf.getName(), coerceWireType(mf, maybeParseJson(mf, vo.get(mf.getName())), columnSqlTypes));
             return row;
         }
         // Fallback: ask each MetaField for its value off the object.
         for (MetaField<?> mf : mc.getMetaFields()) {
-            try { row.put(mf.getName(), maybeParseJson(mf, mf.getObject(instance))); }
+            try { row.put(mf.getName(), coerceWireType(mf, maybeParseJson(mf, mf.getObject(instance)), columnSqlTypes)); }
             catch (Exception ignored) { row.put(mf.getName(), null); }
         }
         return row;
     }
 
+    /**
+     * Reconcile OMDB's MetaField-typed value with the ACTUAL SQL column type so the
+     * canonical wire shape ({@code fixtures/persistence-conformance/normalization.md})
+     * is driven by the column, not the {@code field.*} declaration. OMDB collapses
+     * every numeric column to its field subtype's Java type and reads both plain and
+     * tz-aware timestamps as the same {@link java.sql.Timestamp}; two corpus cases
+     * need the lost distinction restored:
+     *
+     * <ul>
+     *   <li><b>Aggregate INTEGER projections.</b> {@code MIN(int)}/{@code MAX(int)}
+     *       are declared {@code field.long} on the view but are INTEGER columns —
+     *       INTEGER → JSON <em>number</em>, BIGINT → JSON <em>string</em>. OMDB reads
+     *       both as {@link Long}; narrow to {@link Integer} when the catalog reports
+     *       an INTEGER/SMALLINT column so {@link Normalization} emits a number.</li>
+     *   <li><b>TIMESTAMPTZ.</b> A {@code field.timestamp} flagged
+     *       {@code @dbColumnType: timestamp_with_tz} is an absolute instant whose wire
+     *       form carries a {@code Z}; surface it as an {@link java.time.OffsetDateTime}
+     *       in UTC so {@link Normalization} appends the suffix (a plain TIMESTAMP stays
+     *       a {@link java.sql.Timestamp} and renders with no {@code Z}).</li>
+     * </ul>
+     */
+    private static Object coerceWireType(MetaField<?> mf, Object value, Map<String, Integer> columnSqlTypes) {
+        if (value == null) return null;
+        if (isTimestampTzField(mf) && value instanceof java.util.Date d) {
+            return d.toInstant().atOffset(ZoneOffset.UTC);
+        }
+        if (value instanceof Long l) {
+            Integer sqlType = columnSqlTypes.get(mf.getName());
+            if (sqlType != null && (sqlType == Types.INTEGER || sqlType == Types.SMALLINT || sqlType == Types.TINYINT)) {
+                return l.intValue();
+            }
+        }
+        return value;
+    }
+
+    /** True for a {@code field.timestamp} carrying {@code @dbColumnType: timestamp_with_tz}. */
+    private static boolean isTimestampTzField(MetaField<?> mf) {
+        try {
+            return mf.hasMetaAttr(com.metaobjects.database.CoreDBMetaDataProvider.DB_COLUMN_TYPE)
+                && com.metaobjects.database.CoreDBMetaDataProvider.DB_COLUMN_TYPE_TIMESTAMP_TZ.equals(
+                    mf.getMetaAttr(com.metaobjects.database.CoreDBMetaDataProvider.DB_COLUMN_TYPE).getValueAsString());
+        } catch (Exception e) {
+            return false;
+        }
+    }
+
     private static final com.fasterxml.jackson.databind.ObjectMapper JSON =
         new com.fasterxml.jackson.databind.ObjectMapper();
 

server/java/integration-tests/src/test/java/com/metaobjects/integration/QueryScenarioRunner.java

@@ -13,8 +13,12 @@
 import java.nio.file.Path;
 import java.sql.Connection;
 import java.sql.DriverManager;
+import java.sql.ResultSet;
+import java.sql.ResultSetMetaData;
 import java.sql.SQLException;
 import java.sql.Statement;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.UUID;
@@ -60,20 +64,54 @@ public static void run(QueryScenario scenario, PostgresContainer pg, Path canoni
 
         // 3. Run queries.
         ObjectConnection oc = omdb.getConnection();
+        // Per-entity actual SQL column types, probed once from the catalog. OMDB
+        // collapses a column to its field-subtype Java type (losing INTEGER vs
+        // BIGINT), but the canonical wire shape is driven by the real column type
+        // — see ObjectManagerDbAdapter.coerceWireType.
+        Map<MetaObject, Map<String, Integer>> columnTypeCache = new HashMap<>();
         try {
             for (QuerySpec spec : scenario.queries()) {
                 MetaObject mc = findEntityByShortName(loader, spec.entity());
                 if (mc == null) throw new AssertionError(
                     scenario.sourcePath() + " / " + spec.name() +
                     ": no MetaObject named '" + spec.entity() + "' in canonical loader");
-                Object actual = ObjectManagerDbAdapter.execute(omdb, oc, mc, spec);
+                Map<String, Integer> columnSqlTypes = columnTypeCache.computeIfAbsent(
+                    mc, m -> probeColumnSqlTypes(pg, m));
+                Object actual = ObjectManagerDbAdapter.execute(omdb, oc, mc, spec, columnSqlTypes);
                 assertResult(scenario.sourcePath(), spec, actual);
             }
         } finally {
             omdb.releaseConnection(oc);
         }
     }
 
+    /**
+     * Probe the actual JDBC column type ({@link java.sql.Types}) of each column on
+     * the entity's primary physical relation (table or view), keyed by column name.
+     * The corpus declares no {@code @column} renames, so a column name equals its
+     * {@code field.*} name; {@link ObjectManagerDbAdapter} keys the result by field
+     * name. A {@code SELECT * ... WHERE 1=0} returns no rows but a fully-typed
+     * {@link ResultSetMetaData}. Returns an empty map for a non-persistent object.
+     */
+    private static Map<String, Integer> probeColumnSqlTypes(PostgresContainer pg, MetaObject mc) {
+        String relation = mc.getPrimaryRdbViewName();
+        if (relation == null) relation = mc.getPrimaryRdbTableName();
+        if (relation == null) return Map.of();
+        Map<String, Integer> types = new LinkedHashMap<>();
+        String sql = "SELECT * FROM \"" + relation + "\" WHERE 1=0";
+        try (Connection c = openConnection(pg);
+             Statement s = c.createStatement();
+             ResultSet rs = s.executeQuery(sql)) {
+            ResultSetMetaData md = rs.getMetaData();
+            for (int i = 1; i <= md.getColumnCount(); i++) {
+                types.put(md.getColumnName(i), md.getColumnType(i));
+            }
+        } catch (SQLException e) {
+            throw new RuntimeException("Failed to probe column types for relation '" + relation + "'", e);
+        }
+        return types;
+    }
+
     /**
      * Walk the loader's MetaObjects looking for a match by bare name. The
      * cross-port corpus references entities by short name ("Program",