test(java): jsonb open-bag runtime-write gate + api-contract harness (#98)

Complete the Java side of the jsonb-open-bag cross-port consistency work.

Mandate 1 — OMDB runtime write path audit: OMDB has NO write-path gap for
the open bag (`field.string @dbColumnType:jsonb`). Its write path correctly
serializes + binds a JSON-text value via isOpenJsonbField -> serializeOpenJsonb
-> bindJsonbParameter (Postgres setObject(.., Types.OTHER)). The persistence
corpus never exercised this through the runtime write codec (asset-uuid seeds
payload via raw SQL and only READS; roundtrip-all-types writes the *typed*
@storage:jsonb path), so OpenJsonbWriteRoundtripTest fills the gap: it INSERTs
an Asset whose payload is JSON text through ObjectManagerDB.createObject (NOT
raw SQL) and reads it back parsed.

The apparent "object is rejected" is NOT an OMDB write-path defect: OMDB's
ValueObject model is statically typed by field subtype (ADR-0017), so a
structured value assigned to a field.string is coerced to its java toString()
at SET time (DataObjectBase._setObjectAttribute -> DataConverter.toType(STRING,
..)) — generic field-typing, identical for every string field, by design.
(Verified empirically: a Map bound to the bag binds the malformed text
"{a=1, b=2}" and Postgres rejects it with "invalid input syntax for type
json".) The cross-port "write an OBJECT" half lives at the DTO/serialization
boundary (the generated DTO is Object, #103): a consumer serializes the posted
object to JSON text before it reaches OMDB's field.string, and the read side
re-parses it. No OMDB production change was needed — hence the test() prefix.

Mandate 2 — api-contract Java harness for the jsonb sub-corpus, mirroring the
single-entity Author and m2m/tph harnesses, both lanes:
  - JsonbReferenceServer (hand-rolled JDK HttpServer + Postgres testcontainer).
  - GeneratedJsonbControllerHarness (codegen-spring DocumentController/DocumentDto
    compiled + booted over MockMvc behind the in-memory DocumentRepository seam).
The generated DocumentDto types the bag as Object (#103), so a posted JSON
object binds and reads back PARSED, never a JSON-encoded string. This LOCKS the
API-boundary contract.

Tests (Testcontainers Postgres, mvn -f integration-tests/pom.xml):
  - OpenJsonbWriteRoundtripTest                  1/1 green
  - JsonbApiContractConformanceTest (reference)  1/1 green
  - JsonbGeneratedApiContractConformanceTest     1/1 green
  - existing ApiContract*/M2m*/Tph*              48/48 green (no regression)

Deferred: Kotlin + C# api-contract jsonb harnesses (sibling worktrees); a
cross-port persistence-conformance open-bag roundtrip scenario (would require
all five ports' roundtrip writers, out of this Java-scoped change).

Part of #98

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

Author: dmealing

fixtures/api-contract-conformance/jsonb/README.md

@@ -68,11 +68,17 @@ booted over HTTP) are wired and green for:
   emitted `Document.routes.ts` over Postgres testcontainer).
 - **Python** — reference (FastAPI + pg8000 over Postgres testcontainer) +
   generated (`render_router` emitted router + in-memory seam).
-
-Deferred (corpus is ready; follow-up): **Java**, **Kotlin**, **C#**. Their
-api-contract harnesses bind the per-entity DTO shape statically (the JVM
-generated harness reflects a fixed `Author` constructor arity + ships a
-hand-written in-memory repo source; the C# generated lane is full-stack EF +
-Kestrel), so adding the `Document` entity means a new reference server +
-generated harness per port (mirroring their `m2m/` and `tph/` sub-corpus
-harnesses) rather than a focused fixture edit. Tracked in #98.
+- **Java** — reference (`JsonbReferenceServer`: JDK `HttpServer` + Postgres
+  testcontainer) + generated (`GeneratedJsonbControllerHarness`: codegen-spring
+  `DocumentController`/`DocumentDto` compiled and booted over MockMvc behind the
+  in-memory repo seam). The generated DTO types the bag as `Object` (#103). The
+  runtime/OMDB write half is gated separately by
+  `integration-tests/.../OpenJsonbWriteRoundtripTest` (writes the open bag
+  through `ObjectManagerDB.createObject` and reads it back parsed).
+
+Deferred (corpus is ready; follow-up): **Kotlin**, **C#**. Their
+api-contract harnesses bind the per-entity DTO shape statically (the C#
+generated lane is full-stack EF + Kestrel), so adding the `Document` entity
+means a new reference server + generated harness per port (mirroring their
+`m2m/` and `tph/` sub-corpus harnesses) rather than a focused fixture edit.
+Tracked in #98.

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

@@ -0,0 +1,185 @@
+package com.metaobjects.integration;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.metaobjects.loader.MetaDataLoader;
+import com.metaobjects.manager.ObjectConnection;
+import com.metaobjects.manager.QueryOptions;
+import com.metaobjects.manager.db.ObjectManagerDB;
+import com.metaobjects.manager.db.driver.PostgresDriver;
+import com.metaobjects.manager.exp.Expression;
+import com.metaobjects.object.MetaObject;
+import com.metaobjects.object.value.ValueObject;
+import com.metaobjects.registry.ObjectClassRegistry;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+import javax.sql.DataSource;
+import java.io.PrintWriter;
+import java.nio.file.Path;
+import java.sql.Connection;
+import java.sql.DriverManager;
+import java.sql.SQLException;
+import java.sql.Statement;
+import java.time.LocalDate;
+import java.time.LocalTime;
+import java.time.ZoneOffset;
+import java.util.Collection;
+import java.util.Map;
+import java.util.UUID;
+import java.util.logging.Logger;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+
+/**
+ * Mandate 1 (#98) — the OMDB runtime WRITE gate for an <em>open-JSON-bag</em>
+ * column ({@code field.string @dbColumnType:jsonb}).
+ *
+ * <p><b>Why this test exists.</b> The cross-port jsonb-open-bag contract (#98)
+ * is that the field exposes a <em>parsed</em> JSON value. The persistence corpus
+ * proved the READ side ({@code asset-uuid-roundtrip.yaml} seeds {@code payload}
+ * via raw SQL and reads it back parsed) and the typed {@code @storage:jsonb}
+ * WRITE side ({@code roundtrip-all-types.yaml} writes a {@code Settings}
+ * value-object), but no scenario exercised the <em>open</em>
+ * {@code @dbColumnType:jsonb} bag through OMDB's runtime write codec. This test
+ * fills that gap: it INSERTs an {@code Asset} via
+ * {@link ObjectManagerDB#createObject} (NOT raw SQL) and reads it back.</p>
+ *
+ * <p><b>OMDB's open-bag contract is JSON text.</b> OMDB's {@code ValueObject}
+ * model is statically typed by field subtype (ADR-0017): a {@code field.string}
+ * holds a {@code String}. The open bag is therefore authored as JSON
+ * <em>text</em> — exactly how the asset-uuid seed and the LLM-trace recorder
+ * store it — and OMDB's write path serializes/binds it faithfully through
+ * {@code isOpenJsonbField} → {@code serializeOpenJsonb} → {@code bindJsonbParameter}
+ * (Postgres {@code setObject(.., Types.OTHER)} — a bare {@code setString} is
+ * rejected by jsonb's strict input typing). The "post an OBJECT" half of the
+ * cross-port contract lives at the DTO/serialization boundary (the generated DTO
+ * is {@code Object}, #103): a consumer serializes the posted object to JSON text
+ * before it reaches OMDB's {@code field.string}, and the read side re-parses it.
+ * (Assigning a raw {@code Map} to a {@code field.string} is coerced to its java
+ * {@code toString()} at set-time by the generic field-typing in
+ * {@code DataObjectBase}, identical for every string field — not a jsonb
+ * write-path defect, and out of scope to change here.)</p>
+ *
+ * <p>Postgres-only (Testcontainers). Not part of the default Maven reactor —
+ * run via {@code mvn -f server/java/integration-tests/pom.xml test}.</p>
+ */
+final class OpenJsonbWriteRoundtripTest {
+
+    private static final Path CORPUS = ScenarioLoader.findCorpusRoot();
+    private static final Path CANONICAL = CORPUS.resolve("canonical");
+    private static final ObjectMapper JSON = new ObjectMapper();
+
+    @BeforeAll
+    static void bindEntities() {
+        // Bind Asset to ValueObject so OMDB can instantiate rows without a
+        // project POJO (mirrors QueryScenarioTests.beforeAll). Skip if a prior
+        // test class in the same JVM already published a registry with Asset.
+        if (ObjectClassRegistry.global().resolve("fitness::Asset") != null) return;
+        ObjectClassRegistry reg = new ObjectClassRegistry();
+        reg.register(() -> Map.of("fitness::Asset", ValueObject.class));
+        ObjectClassRegistry.setGlobal(reg);
+    }
+
+    /**
+     * A JSON value written into the open bag through the OMDB runtime write
+     * codec ({@code createObject}, NOT raw SQL) reads back as the same parsed
+     * structure — including a nested object and an array — never a malformed or
+     * double-encoded blob. This is the WRITE complement to the read-only
+     * {@code asset-uuid-roundtrip} scenario.
+     */
+    @Test
+    void openBagJsonValueRoundTripsThroughOmdbWrite() throws Exception {
+        String payloadJson = "{\"k\":\"v\",\"n\":7,\"nested\":{\"deep\":true},\"list\":[1,2,3]}";
+
+        try (PostgresContainer pg = new PostgresContainer()) {
+            MetaDataLoader loader = MetaDataLoader.fromDirectory(
+                "open-jsonb-" + UUID.randomUUID().toString().substring(0, 8), CANONICAL);
+            ObjectManagerDB omdb = newOmdb(pg);
+            provisionSchema(pg);
+
+            MetaObject asset = findByShortName(loader, "Asset");
+            assertNotNull(asset, "canonical loader must contain Asset");
+
+            ValueObject vo = (ValueObject) asset.newInstance();
+            vo.setString("ownerId", "AAAAAAAA-AAAA-4AAA-8AAA-AAAAAAAAAAAA");
+            vo.setString("payload", payloadJson); // open bag = JSON text
+            vo.setDate("recordedAt", instant("2026-05-30T14:30:00Z"));
+            vo.setDate("observedAt", instant("2026-05-30T14:30:00Z"));
+            vo.setDate("asOfDate", java.util.Date.from(
+                LocalDate.parse("2026-05-30").atStartOfDay(ZoneOffset.UTC).toInstant()));
+            vo.setObject("atTime", LocalTime.parse("14:30:00"));
+
+            ObjectConnection oc = omdb.getConnection();
+            try {
+                omdb.createObject(oc, vo); // INSERT via the OMDB runtime write path
+                Object id = vo.get("id");  // app-side minted uuid PK
+                assertNotNull(id, "OMDB should mint the uuid PK on insert");
+
+                Collection<?> rows = omdb.getObjects(oc, asset,
+                    new QueryOptions(new Expression("id", id, Expression.EQUAL)));
+                assertEquals(1, rows.size(), "inserted row must read back");
+                ValueObject readBack = (ValueObject) rows.iterator().next();
+
+                // OMDB returns the jsonb column as raw JSON text. Parse + compare
+                // structurally — a malformed or double-encoded value fails to
+                // parse back to the original tree.
+                Object raw = readBack.get("payload");
+                assertNotNull(raw, "payload must read back");
+                assertEquals(JSON.readTree(payloadJson),
+                             JSON.readTree(String.valueOf(raw)),
+                             "open-bag jsonb value must round-trip through OMDB write+read parsed");
+            } finally {
+                omdb.releaseConnection(oc);
+            }
+        }
+    }
+
+    // -----------------------------------------------------------------------
+    // OMDB + Postgres plumbing (mirrors QueryScenarioRunner)
+    // -----------------------------------------------------------------------
+
+    private static ObjectManagerDB newOmdb(PostgresContainer pg) throws Exception {
+        ObjectManagerDB omdb = new ObjectManagerDB();
+        omdb.setDatabaseDriver(new PostgresDriver());
+        omdb.setDataSource(dataSource(pg));
+        omdb.init();
+        return omdb;
+    }
+
+    private static void provisionSchema(PostgresContainer pg) throws Exception {
+        String ddl = ScenarioLoader.readCanonicalSchema(CORPUS);
+        try (Connection c = openConnection(pg); Statement s = c.createStatement()) {
+            s.execute(ddl);
+        }
+    }
+
+    private static MetaObject findByShortName(MetaDataLoader loader, String shortName) {
+        for (MetaObject mc : loader.getMetaObjects()) {
+            if (mc.getShortName().equals(shortName)) return mc;
+        }
+        return null;
+    }
+
+    private static java.util.Date instant(String iso) {
+        return java.util.Date.from(java.time.Instant.parse(iso));
+    }
+
+    private static Connection openConnection(PostgresContainer pg) throws SQLException {
+        return DriverManager.getConnection(pg.jdbcUrl(), pg.username(), pg.password());
+    }
+
+    private static DataSource dataSource(PostgresContainer pg) {
+        return new DataSource() {
+            @Override public Connection getConnection() throws SQLException { return openConnection(pg); }
+            @Override public Connection getConnection(String u, String p) throws SQLException { return openConnection(pg); }
+            @Override public PrintWriter getLogWriter() { return null; }
+            @Override public void setLogWriter(PrintWriter out) {}
+            @Override public void setLoginTimeout(int seconds) {}
+            @Override public int getLoginTimeout() { return 0; }
+            @Override public Logger getParentLogger() { return Logger.getLogger("open-jsonb-test"); }
+            @Override public <T> T unwrap(Class<T> iface) { return null; }
+            @Override public boolean isWrapperFor(Class<?> iface) { return false; }
+        };
+    }
+}

server/java/integration-tests/src/test/java/com/metaobjects/integration/api/JsonbApiContractConformanceTest.java

@@ -0,0 +1,76 @@
+package com.metaobjects.integration.api;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.metaobjects.integration.PostgresContainer;
+import com.metaobjects.integration.api.ApiContractScenarios.ApiRequest;
+import com.metaobjects.integration.api.ApiContractScenarios.ApiScenario;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.util.List;
+import java.util.stream.Stream;
+
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+
+/**
+ * Cross-port API contract conformance for the jsonb open-bag corpus
+ * ({@code fixtures/api-contract-conformance/jsonb/}) — Java reference lane.
+ *
+ * <p>One JUnit invocation per scenario: a fresh Postgres testcontainer + the
+ * hand-rolled {@link JsonbReferenceServer}, walking the scenario's requests and
+ * asserting each response against the cross-port {@code expect.body.*}
+ * vocabulary ({@link ApiContractAssertions}). Locks the API-boundary half of the
+ * open-bag contract (a posted JSON object reads back PARSED) on the reference
+ * server; {@link JsonbGeneratedApiContractConformanceTest} locks it on the
+ * GENERATED Spring controller.</p>
+ *
+ * <p>Run on-demand:
+ * {@code mvn -f server/java/integration-tests/pom.xml test -Dtest=JsonbApiContractConformanceTest}</p>
+ */
+final class JsonbApiContractConformanceTest {
+
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+    private static final List<ApiScenario> SCENARIOS =
+        ApiContractScenarioLoader.loadScenarios(JsonbCorpus.scenariosDir());
+    private static final List<java.util.Map<String, Object>> SEED_ROWS = JsonbCorpus.seedRows();
+
+    static Stream<Arguments> scenarios() {
+        return SCENARIOS.stream().map(s -> Arguments.of(s.name(), s));
+    }
+
+    @ParameterizedTest(name = "{0}")
+    @MethodSource("scenarios")
+    void scenario(String name, ApiScenario scenario) {
+        assertDoesNotThrow(() -> {
+            try (PostgresContainer pg = new PostgresContainer();
+                 JsonbReferenceServer server = new JsonbReferenceServer(pg, SEED_ROWS)) {
+                HttpClient client = HttpClient.newHttpClient();
+                for (ApiRequest req : scenario.requests()) {
+                    HttpRequest.Builder builder =
+                        HttpRequest.newBuilder(URI.create(server.baseUrl() + req.path()));
+                    HttpRequest.BodyPublisher publisher;
+                    if (req.body() != null) {
+                        builder.header("Content-Type", "application/json");
+                        publisher = HttpRequest.BodyPublishers.ofString(MAPPER.writeValueAsString(req.body()));
+                    } else {
+                        publisher = HttpRequest.BodyPublishers.noBody();
+                    }
+                    switch (req.method()) {
+                        case "GET" -> builder.GET();
+                        case "DELETE" -> builder.DELETE();
+                        default -> builder.method(req.method(), publisher);
+                    }
+                    HttpResponse<String> res = client.send(builder.build(), HttpResponse.BodyHandlers.ofString());
+                    Object parsed = (res.body() == null || res.body().isEmpty())
+                        ? null : MAPPER.readValue(res.body(), Object.class);
+                    ApiContractAssertions.assertResponse(scenario.name(), req, res.statusCode(), parsed);
+                }
+            }
+        });
+    }
+}

server/java/integration-tests/src/test/java/com/metaobjects/integration/api/JsonbCorpus.java

@@ -0,0 +1,51 @@
+package com.metaobjects.integration.api;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Locates the jsonb open-bag sub-corpus
+ * ({@code fixtures/api-contract-conformance/jsonb/}) and loads its seed rows.
+ * Shared by the reference ({@link JsonbApiContractConformanceTest}) and generated
+ * ({@link JsonbGeneratedApiContractConformanceTest}) lanes.
+ */
+final class JsonbCorpus {
+    private JsonbCorpus() {}
+
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+
+    /** The jsonb sub-corpus root ({@code <api-contract-conformance>/jsonb}). */
+    static Path root() {
+        return ApiContractScenarioLoader.findCorpusRoot().resolve("jsonb");
+    }
+
+    static Path scenariosDir() {
+        return root().resolve("scenarios");
+    }
+
+    static Path metaJson() {
+        return root().resolve("meta.json");
+    }
+
+    /** The {@code rows} array from {@code jsonb/seed.json} (payload values are JSON objects). */
+    @SuppressWarnings("unchecked")
+    static List<Map<String, Object>> seedRows() {
+        try {
+            String text = Files.readString(root().resolve("seed.json"), StandardCharsets.UTF_8);
+            Map<String, Object> parsed = MAPPER.readValue(text, Map.class);
+            Object rows = parsed.get("rows");
+            if (!(rows instanceof List<?>))
+                throw new IllegalStateException("jsonb/seed.json: missing 'rows' array");
+            return (List<Map<String, Object>>) rows;
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+    }
+}