feat(java): metaJson helper for the GET /_meta contract, reachable from Kotlin

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015NrWUxA6euwvnFcwKxcK6A

Author: dmealing

server/java/metadata-ktx/src/test/kotlin/com/metaobjects/metadata/ktx/MetaEndpointKtxTest.kt

@@ -0,0 +1,27 @@
+package com.metaobjects.metadata.ktx
+
+import com.metaobjects.io.json.CanonicalJsonSerializer
+import com.metaobjects.io.json.MetaEndpoint
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+/**
+ * Kotlin consumes the Java [MetaEndpoint] symbol directly — there is no separate Kotlin
+ * implementation of the GET /_meta contract. These tests prove it is reachable, and behaves
+ * correctly, from the Kotlin facade.
+ */
+class MetaEndpointKtxTest {
+
+    private val tinyJson = """{ "metadata.root": { "package": "acme", "children": [] } }"""
+
+    @Test fun `the route path is the cross-port contract value`() {
+        assertEquals("/_meta", MetaEndpoint.META_ROUTE_PATH)
+    }
+
+    @Test fun `metaJson is callable from kotlin and matches the effective serialization`() {
+        val loader = loadString("meta-endpoint-ktx-test", tinyJson)
+        assertEquals(
+            CanonicalJsonSerializer.canonicalSerializeEffective(loader.root),
+            MetaEndpoint.metaJson(loader.root))
+    }
+}

server/java/metadata/src/main/java/com/metaobjects/io/json/MetaEndpoint.java

@@ -0,0 +1,38 @@
+package com.metaobjects.io.json;
+
+import com.metaobjects.MetaData;
+
+/**
+ * UI-1 — the metadata API contract.
+ *
+ * <p>Java ships the helper and not a mount: {@code core-spring} carries
+ * {@code spring-context} but no {@code spring-web}, and adding a web dependency
+ * for one endpoint would put it on every consumer. Mount it yourself:
+ *
+ * <pre>
+ * &#64;GetMapping(value = "/api" + MetaEndpoint.META_ROUTE_PATH,
+ *             produces = MediaType.APPLICATION_JSON_VALUE)
+ * public String meta() { return MetaEndpoint.metaJson(root); }
+ * </pre>
+ *
+ * <p>Guard that route with your own authorization — {@code /_meta} publishes the
+ * shape of the model, though no row data.
+ */
+public final class MetaEndpoint {
+
+    private MetaEndpoint() {}
+
+    /**
+     * The endpoint path, mounted under the host's API prefix. A cross-port contract
+     * value — one browser read-model works against every backend.
+     */
+    public static final String META_ROUTE_PATH = "/_meta";
+
+    /**
+     * The response body: the model as EFFECTIVE canonical JSON, so a browser reading
+     * it never resolves {@code extends} itself.
+     */
+    public static String metaJson(MetaData root) {
+        return CanonicalJsonSerializer.canonicalSerializeEffective(root);
+    }
+}

server/java/metadata/src/test/java/com/metaobjects/io/json/MetaEndpointTest.java

@@ -0,0 +1,136 @@
+package com.metaobjects.io.json;
+
+import com.google.gson.JsonArray;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import com.google.gson.JsonParser;
+import com.metaobjects.MetaRoot;
+import com.metaobjects.conformance.CorpusRoot;
+import com.metaobjects.loader.InMemoryStringSource;
+import com.metaobjects.loader.LoaderOptions;
+import com.metaobjects.loader.MetaDataLoader;
+import org.junit.Test;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+/**
+ * Tests for {@link MetaEndpoint} — the {@code GET /_meta} cross-port contract helper.
+ *
+ * <p>Uses the {@code extends-abstract-base} conformance fixture
+ * ({@code fixtures/conformance/extends-abstract-base/input/meta.common.json}), which has
+ * real OBJECT-level inheritance: {@code Subscriber extends acme::BaseEntity}, and
+ * {@code BaseEntity} declares {@code createdAt}. That makes {@code canonicalSerialize}
+ * (raw — Subscriber's own children only) and {@code canonicalSerializeEffective}
+ * (Subscriber's children plus everything inherited from BaseEntity) genuinely different
+ * documents, so equality against the effective form is a real discriminator rather than a
+ * call-forwarding smoke test.
+ */
+public class MetaEndpointTest {
+
+    @Test
+    public void metaRoutePathIsTheCrossPortContractValue() {
+        assertEquals("/_meta", MetaEndpoint.META_ROUTE_PATH);
+    }
+
+    @Test
+    public void metaJsonReturnsTheEffectiveCanonicalSerialization() throws IOException {
+        MetaRoot root = loadExtendsAbstractBaseFixture();
+
+        String effective = CanonicalJsonSerializer.canonicalSerializeEffective(root);
+        String raw = CanonicalJsonSerializer.canonicalSerialize(root);
+        assertFalse("control: the fixture must actually exercise inheritance (raw must differ "
+                + "from effective), otherwise this equality proves nothing",
+            raw.equals(effective));
+
+        assertEquals(effective, MetaEndpoint.metaJson(root));
+    }
+
+    /**
+     * Structural discriminator that cannot be fooled by a substring match: the RAW
+     * serialization ALSO contains the string "createdAt" (it's BaseEntity's own field),
+     * so a naive {@code contains("createdAt")} check on the whole document would pass
+     * even for a helper that (bug) called the raw serializer. This test instead locates
+     * Subscriber's own "children" array specifically and checks THAT — true only for the
+     * effective serialization.
+     */
+    @Test
+    public void metaJsonSubscriberChildrenIncludeInheritedCreatedAt() throws IOException {
+        MetaRoot root = loadExtendsAbstractBaseFixture();
+
+        JsonObject effectiveSubscriber = findObjectByName(MetaEndpoint.metaJson(root), "Subscriber");
+        assertTrue("effective Subscriber's own children must include the inherited 'createdAt' field",
+            hasFieldNamed(effectiveSubscriber, "createdAt"));
+
+        JsonObject rawSubscriber =
+            findObjectByName(CanonicalJsonSerializer.canonicalSerialize(root), "Subscriber");
+        assertFalse("raw Subscriber's own children must NOT include the inherited 'createdAt' field",
+            hasFieldNamed(rawSubscriber, "createdAt"));
+    }
+
+    // -----------------------------------------------------------------------
+    // Fixture loading — mirrors the established Java conformance idiom (see
+    // conformance.StrictRunnerHardFailTest / object.ObjectModelConformanceTest): a fresh
+    // manual-subtype MetaDataLoader fed the fixture's input file(s) via InMemoryStringSource.
+    // -----------------------------------------------------------------------
+
+    private static MetaRoot loadExtendsAbstractBaseFixture() throws IOException {
+        Path inputDir = CorpusRoot.locate().resolve("extends-abstract-base").resolve("input");
+        Path metaFile = inputDir.resolve("meta.common.json");
+        String content = new String(Files.readAllBytes(metaFile), StandardCharsets.UTF_8);
+
+        MetaDataLoader loader = new MetaDataLoader(
+            LoaderOptions.create(false, false, true),
+            MetaDataLoader.SUBTYPE_MANUAL, "meta-endpoint-test");
+        loader.init();
+        loader.load(List.of(new InMemoryStringSource(content, "meta.common.json")));
+
+        assertTrue("fixture load must report no errors, got: " + loader.getErrors(),
+            loader.getErrors().isEmpty());
+
+        return loader.getRoot();
+    }
+
+    /** Finds the named {@code object.*} node anywhere in the document and returns its JSON body. */
+    private static JsonObject findObjectByName(String json, String objectName) {
+        JsonElement parsed = JsonParser.parseString(json);
+        JsonArray topChildren = parsed.getAsJsonObject()
+            .getAsJsonObject("metadata.root")
+            .getAsJsonArray("children");
+        for (JsonElement child : topChildren) {
+            JsonObject wrapper = child.getAsJsonObject();
+            for (String key : wrapper.keySet()) {
+                if (!key.startsWith("object.")) continue;
+                JsonObject obj = wrapper.getAsJsonObject(key);
+                if (objectName.equals(obj.get("name").getAsString())) {
+                    return obj;
+                }
+            }
+        }
+        throw new AssertionError("object '" + objectName + "' not found in: " + json);
+    }
+
+    /** True when the given {@code object.*} body has a {@code field.*} child named {@code fieldName}. */
+    private static boolean hasFieldNamed(JsonObject objectEntity, String fieldName) {
+        JsonArray children = objectEntity.getAsJsonArray("children");
+        if (children == null) return false;
+        for (JsonElement child : children) {
+            JsonObject wrapper = child.getAsJsonObject();
+            for (String key : wrapper.keySet()) {
+                if (!key.startsWith("field.")) continue;
+                JsonObject field = wrapper.getAsJsonObject(key);
+                if (fieldName.equals(field.get("name").getAsString())) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+}