fix(metadata): #37 — Java echoes authored extends-ref verbatim (cross-port parity) + fixture gates same-package-FQN extends

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

Author: dmealing

fixtures/conformance/flattened-kitchen-sink/expected-effective.json

@@ -585,7 +585,7 @@
       {
         "object.entity": {
           "name": "ProductSummary",
-          "extends": "Product",
+          "extends": "acme::catalog::Product",
           "@description": "Read-only projection: aggregates, passthrough and a collection origin.",
           "@uiHints": {
             "group": "inventory",

fixtures/conformance/flattened-kitchen-sink/expected.json

@@ -509,7 +509,7 @@
       {
         "object.entity": {
           "name": "ProductSummary",
-          "extends": "Product",
+          "extends": "acme::catalog::Product",
           "@description": "Read-only projection: aggregates, passthrough and a collection origin.",
           "children": [
             {

fixtures/conformance/flattened-kitchen-sink/input/meta.catalog.json

@@ -221,7 +221,7 @@
       {
         "object.entity": {
           "name": "ProductSummary",
-          "extends": "Product",
+          "extends": "acme::catalog::Product",
           "@description": "Read-only projection: aggregates, passthrough and a collection origin.",
           "children": [
             { "source.rdb": { "@kind": "view", "@view": "v_product_summary" } },

server/java/metadata/src/main/java/com/metaobjects/MetaData.java

@@ -302,6 +302,15 @@ public static void registerTypes() {
     // byte-parity with the TS / Python oracles.
     private boolean packageAuthored = false;
 
+    // The raw `extends` (super) reference string EXACTLY as authored in the
+    // source file (e.g. "Product", "acme::catalog::Product", a relative ref).
+    // The parser resolves this string to a concrete super node (getSuperData),
+    // but the canonical serializer must echo the AUTHORED form verbatim — never
+    // a recomputed short-vs-FQN form — to stay byte-identical with the TS / C# /
+    // Python oracles (which all preserve and re-emit the raw `superRef`). See
+    // CanonicalJsonSerializer's `extends` emission and the TS `model.superRef`.
+    private String authoredSuperRef = null;
+
     /**
      * Constructs a MetaData object with enhanced type system integration.
      * 
@@ -871,6 +880,25 @@ public void setPackageAuthored(boolean packageAuthored) {
         this.packageAuthored = packageAuthored;
     }
 
+    /**
+     * Returns the raw {@code extends} (super) reference string exactly as it was
+     * authored in the source file, or {@code null} if no {@code extends} was
+     * authored on this node. The canonical serializer echoes this verbatim. See
+     * the {@code authoredSuperRef} field doc for context.
+     */
+    public String getAuthoredSuperRef() {
+        return authoredSuperRef;
+    }
+
+    /**
+     * Records the raw, as-authored {@code extends} (super) reference string.
+     * Called by the canonical JSON / YAML parser when the body declares an
+     * {@code "extends"} key, so the serializer can re-emit it verbatim.
+     */
+    public void setAuthoredSuperRef(String authoredSuperRef) {
+        this.authoredSuperRef = authoredSuperRef;
+    }
+
     /**
      * Retrieve the MetaObject short name
      * @return the short name of this metadata without package prefix

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

@@ -323,27 +323,23 @@ private static JsonObject serializeBody(MetaData node, boolean effective, String
             }
         }
 
-        // 3. extends — emit when super data is set
-        // Use the short name when the super is in the same package as the node;
-        // use the fully-qualified name when the super lives in a different package
-        // so that round-trip loading can resolve it correctly.
+        // 3. extends — echo the AUTHORED super-ref string VERBATIM.
+        //
+        // Cross-port contract: TS / C# / Python all preserve the raw `superRef`
+        // the parser read and re-emit it unchanged (TS `model.superRef`). Java
+        // must do the same. Recomputing a short-vs-FQN form (the prior behavior)
+        // only happened to byte-match fixtures that authored cross-package
+        // extends as FQN and same-package extends as short names — a same-package
+        // extends authored as a full FQN (or a relative ref) would diverge.
+        //
+        // The parser stores the as-authored string via setAuthoredSuperRef when
+        // it sees an `extends` key; fall back to the resolved super FQN only when
+        // no authored string is available (e.g. a programmatically-built tree).
         if (node.hasSuperData()) {
-            MetaData superData = node.getSuperData();
-            // For "same-package" detection we want the NODE's AUTHORING context
-            // (closest MetaObject/MetaRoot ancestor's package — a field `status`
-            // inside `Order` in `acme` has getPackage() == "acme::Order" but
-            // authors think of it as living in "acme") compared against the
-            // SUPER's own declared package (from its FQN), so synthetic
-            // tree-misalignments still emit FQN extends when the names diverge.
-            String authoringPackage = authoringPackageFor(node);
-            String superPackage = resolveNodePackage(superData);
-            String superRef;
-            if (authoringPackage != null && !authoringPackage.isEmpty()
-                    && authoringPackage.equals(superPackage)) {
-                superRef = superData.getShortName();
-            } else {
-                superRef = superData.getName();
-            }
+            String authoredSuperRef = node.getAuthoredSuperRef();
+            String superRef = (authoredSuperRef != null && !authoredSuperRef.isEmpty())
+                ? authoredSuperRef
+                : node.getSuperData().getName();
             if (superRef != null && !superRef.isEmpty()) {
                 body.addProperty(KEY_EXTENDS, superRef);
             }
@@ -508,42 +504,6 @@ private static String canonicalMatchName(MetaData node) {
     // Helpers — package resolution
     // ---------------------------------------------------------------------------
 
-    /**
-     * Returns the "authoring package" of a node — the package context an author
-     * would use to write its {@code extends} ref. For a node that is itself a
-     * top-level type (a child of the MetaRoot — an object / template / abstract
-     * field), this is the node's OWN package. For a node nested inside an entity
-     * it walks up to the nearest MetaObject and returns that ancestor's package.
-     * Used by extends-ref serialization so a sibling in the same package is
-     * referenced by short name (not by FQN).
-     *
-     * <p>Cross-port correctness for the flattened multi-file case: a single
-     * loader builds ONE MetaRoot whose name is just the first input file's
-     * package. The other files contribute children in OTHER packages. The
-     * root's own package is therefore NOT the authoring context for those
-     * children — each node's own {@link MetaData#getPackage()} (the effective
-     * package of its FQN) is. So we never fall back to the root's package; we
-     * fall back to the node's own package.</p>
-     */
-    private static String authoringPackageFor(MetaData node) {
-        MetaData current = node;
-        while (current != null) {
-            MetaData parent = current.getParent();
-            if (parent == null || parent instanceof MetaRoot) {
-                // `current` is a top-level type — its own package IS the
-                // authoring context (not the shared root's package).
-                return current.getPackage();
-            }
-            if (parent instanceof com.metaobjects.object.MetaObject) {
-                // current is a child of an entity → authoring context = entity's package
-                return parent.getPackage();
-            }
-            // Non-MetaObject parent: keep walking up.
-            current = parent;
-        }
-        return node.getPackage();
-    }
-
     /**
      * Returns the "canonical package" for a node.
      *

server/java/metadata/src/main/java/com/metaobjects/loader/parser/json/CanonicalJsonParser.java

@@ -656,6 +656,15 @@ private void processNode(MetaData parent, String type, String subType,
             md.setPackageAuthored(true);
         }
 
+        // Preserve the raw, as-authored `extends` reference so the canonical
+        // serializer can echo it VERBATIM (matching the TS / C# / Python oracles
+        // which all re-emit the raw superRef). Without this Java would recompute
+        // a short-vs-FQN form and diverge on, e.g., a same-package extends that
+        // the author wrote as a full FQN.
+        if (md != null && superRef != null && !superRef.isEmpty()) {
+            md.setAuthoredSuperRef(superRef);
+        }
+
         if (md == null) {
             log.warn("createOrOverlayMetaData returned null for [{}:{}:{}] in file [{}]",
                 type, subType, name, getFilename());

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

@@ -213,7 +213,13 @@ public void testAttrsInAlphabeticalOrder() {
     }
 
     // -----------------------------------------------------------------------
-    // Test 7 — extends emitted when super data is set
+    // Test 7 — extends emitted when super data is set (no authored ref → FQN)
+    //
+    // Cross-port contract (matches TS / C# / Python): the serializer echoes the
+    // AUTHORED `extends` string verbatim. A programmatically-built tree that sets
+    // super via setSuperData() (never the parser) carries NO authored ref, so the
+    // serializer falls back to the resolved super FQN. The serializer must never
+    // recompute a short-vs-FQN form — that was the latent divergence (#37).
     // -----------------------------------------------------------------------
     @Test
     public void testExtendsEmittedWhenSuperDataSet() {
@@ -229,7 +235,46 @@ public void testExtendsEmittedWhenSuperDataSet() {
 
         String json = CanonicalJsonSerializer.canonicalSerialize(root);
 
-        assertTrue("expected extends key with short name, got: " + json, json.contains("\"extends\": \"BaseEntity\""));
+        // No authored ref on this programmatic tree → fall back to resolved FQN.
+        assertTrue("expected extends key with resolved FQN, got: " + json,
+                json.contains("\"extends\": \"test::pkg::BaseEntity\""));
+    }
+
+    // -----------------------------------------------------------------------
+    // Test 7b — extends echoes the AUTHORED ref VERBATIM (cross-port contract)
+    //
+    // When the authored `extends` string is preserved (as the canonical parser
+    // does via setAuthoredSuperRef), the serializer re-emits it byte-for-byte —
+    // regardless of whether the super lives in the same or a different package.
+    // This is the contract gated by the flattened-kitchen-sink fixture's
+    // same-package-FQN extends; here we assert it directly on a synthetic tree.
+    // -----------------------------------------------------------------------
+    @Test
+    public void testExtendsEchoesAuthoredRefVerbatim() {
+        MetaRoot root = new MetaRoot("test::pkg");
+
+        ValueMetaObject base = ValueMetaObject.create("test::pkg::Base");
+        base.addMetaAttr(BooleanAttribute.create(MetaData.ATTR_IS_ABSTRACT, true));
+        root.addChild(base);
+
+        // Same package as the super, but authored as a FULL FQN — must echo FQN.
+        ValueMetaObject derivedFqn = ValueMetaObject.create("test::pkg::DerivedFqn");
+        derivedFqn.setSuperData(base);
+        derivedFqn.setAuthoredSuperRef("test::pkg::Base");
+        root.addChild(derivedFqn);
+
+        // Same package, authored as a SHORT name — must echo the short name.
+        ValueMetaObject derivedShort = ValueMetaObject.create("test::pkg::DerivedShort");
+        derivedShort.setSuperData(base);
+        derivedShort.setAuthoredSuperRef("Base");
+        root.addChild(derivedShort);
+
+        String json = CanonicalJsonSerializer.canonicalSerialize(root);
+
+        assertTrue("authored FQN extends must echo verbatim, got: " + json,
+                json.contains("\"extends\": \"test::pkg::Base\""));
+        assertTrue("authored short extends must echo verbatim, got: " + json,
+                json.contains("\"extends\": \"Base\""));
     }
 
     // -----------------------------------------------------------------------
@@ -330,13 +375,16 @@ public void testExtendsEmittedAsFQNWhenSuperInDifferentPackage() {
     }
 
     // -----------------------------------------------------------------------
-    // Test 12 — extends emitted as short name when super is in the same package
+    // Test 12 — no authored ref → serializer falls back to the resolved FQN
     //
-    // Both Base and Derived are in "test::pkg".  The existing Test 7 covers
-    // same-package extends; this test makes the intent explicit.
+    // Both Base and Derived are in "test::pkg", super set programmatically with
+    // NO authored ref. Under the echo-verbatim contract (#37) the serializer no
+    // longer recomputes a short name for same-package supers — it emits the
+    // resolved FQN fallback. The short-vs-FQN choice is the AUTHOR's (echoed
+    // verbatim; see Test 7b), not the serializer's to recompute.
     // -----------------------------------------------------------------------
     @Test
-    public void testExtendsEmittedAsShortNameWhenSamePackage() {
+    public void testExtendsFallsBackToFqnWhenNoAuthoredRef() {
         MetaRoot root = new MetaRoot("test::pkg");
 
         ValueMetaObject base = ValueMetaObject.create("test::pkg::Base");
@@ -349,11 +397,8 @@ public void testExtendsEmittedAsShortNameWhenSamePackage() {
 
         String json = CanonicalJsonSerializer.canonicalSerialize(root);
 
-        // Same package — short name is unambiguous and preferred.
-        assertTrue("extends must be the short name when super is in the same package, got: " + json,
-                json.contains("\"extends\": \"Base\""));
-        // Must NOT use the FQN — that would be unnecessarily verbose.
-        assertFalse("extends must NOT be the FQN when super is in the same package",
+        // No authored ref → resolved FQN fallback (no short-name recompute).
+        assertTrue("extends must be the resolved FQN when no ref was authored, got: " + json,
                 json.contains("\"extends\": \"test::pkg::Base\""));
     }