feat(fr-032): T6 — wire ERR_RELATIVE_REF_IN_CANONICAL guard (Java/C#/Python)

dmealing · claude · dmealing · commit af46e655194c · 2026-06-13T13:36:58.000-04:00
Completes FR-032: canonical JSON must reject a relative reference. A
ref value starting with `::` (root-absolute) or `..::` (parent-relative)
is a YAML-authoring affordance the desugar expands — it must never
survive into canonical JSON. TS already had the guard (parser-core.ts);
this wires it in the JVM, C#, and Python canonical-JSON parsers so the
behavior is consistent and cross-port-gated.

- New shared fixture `fixtures/conformance/error-relative-ref-in-canonical/`
  (`extends: "::Base"` in canonical JSON → exactly one
  `ERR_RELATIVE_REF_IN_CANONICAL`; legacy code-set assertion so each
  port need only emit the code, not match jsonPath).
- Java: ErrorCode + ErrorMessageConstants enum/constant; guard in
  CanonicalJsonParser on the `extends` key + inline `@`-ref attrs
  (throws, halting parse → one error). Also FQN-qualified 4 Java-INTERNAL
  test resources (fruitbasket*) that used the now-rejected `::Apple`
  form in canonical JSON.
- C#: ERR_RELATIVE_REF_IN_CANONICAL in Errors.cs; guard in Parser.cs
  (ApplyReservedKeys + ApplyInlineAttrsAndUnknownKeys).
- Python: is_relative_ref() in naming_refs.py; guard in parser.py
  (extends + inline ref attrs), reusing REF_BEARING_ATTR_NAMES.

The guard lives ONLY in each port's canonical-JSON parser (JSON by
construction — no format check), never the YAML desugar. Verified:
new fixture passes in all 5 ports; TS 378/0, Java ConformanceTest 378/0
(full metadata 1040/0), C# 649/0 (codegen 216/0), Python conformance
295/0 (full 1255/0).

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/fixtures/conformance/error-relative-ref-in-canonical/expected-errors.json b/fixtures/conformance/error-relative-ref-in-canonical/expected-errors.json
@@ -0,0 +1 @@
+[{"code":"ERR_RELATIVE_REF_IN_CANONICAL"}]
diff --git a/fixtures/conformance/error-relative-ref-in-canonical/input/meta.bad.json b/fixtures/conformance/error-relative-ref-in-canonical/input/meta.bad.json
@@ -0,0 +1,25 @@
+{
+  "metadata.root": {
+    "package": "demo",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Widget",
+          "extends": "::Base",
+          "children": [
+            { "field.long": { "name": "id" } },
+            { "identity.primary": { "name": "id", "@fields": "id" } }
+          ]
+        }
+      },
+      {
+        "object.entity": {
+          "name": "Base",
+          "children": [
+            { "field.string": { "name": "label" } }
+          ]
+        }
+      }
+    ]
+  }
+}
diff --git a/server/csharp/MetaObjects/Errors.cs b/server/csharp/MetaObjects/Errors.cs
@@ -39,6 +39,10 @@ public enum ErrorCode
     ERR_MALFORMED_YAML,
     ERR_YAML_COERCION,
     ERR_RESERVED_ATTR,
+    // FR-032 (ADR-0032) — a ref-bearing value in canonical JSON used a relative
+    // form (leading "::" or "..::"). Relative refs are YAML-authoring sugar the
+    // desugar expands; they must never appear in canonical (interchange) JSON.
+    ERR_RELATIVE_REF_IN_CANONICAL,
     ERR_INVALID_ORIGIN,
     // FR-024 (ADR-0029) — origin @via inference + cardinality checks. Vocabulary-only
     // here until FR-024 Phase E (the C# loader does not run the inference yet):
diff --git a/server/csharp/MetaObjects/Parser.cs b/server/csharp/MetaObjects/Parser.cs
@@ -226,6 +226,52 @@ private static void ReportProblem(
         st.Warnings.Add(msg);
     }
 
+    // -----------------------------------------------------------------------
+    // FR-032 (ADR-0032) — relative-ref guard for canonical JSON.
+    //
+    // The bare (sigil-free) inline attribute names whose VALUE is a metadata
+    // reference. In canonical JSON these are @-prefixed (@objectRef, …). Mirrors
+    // YamlDesugar.RefBearingAttrNames + the Java/TS REF_BEARING_ATTR_NAMES. The
+    // structural `extends` key is a reference too, but is guarded separately (it
+    // is the bare RESERVED_KEY_EXTENDS body key, not an @-prefixed attr).
+    // -----------------------------------------------------------------------
+
+    private static readonly HashSet<string> RefBearingAttrNames = new(StringComparer.Ordinal)
+    {
+        "objectRef", "references", "from", "of", "via",
+        "payloadRef", "responseRef", "parameterRef",
+    };
+
+    /// <summary>
+    /// FR-032 (ADR-0032) — guard a ref-bearing value against relative forms.
+    /// Canonical JSON is the self-contained interchange form: every ref-bearing
+    /// attribute MUST be fully qualified. A relative authoring form (leading
+    /// <c>::</c> or <c>..::</c>) surviving into canonical JSON is
+    /// <see cref="ErrorCode.ERR_RELATIVE_REF_IN_CANONICAL"/>. The C# canonical
+    /// parser only ever handles canonical JSON (the YAML desugar expands these
+    /// forms before the parser sees them), so no format check is needed. Throwing
+    /// halts the parse so exactly one error is produced, mirroring the
+    /// <see cref="ErrorCode.ERR_RESERVED_ATTR"/> rejection style.
+    /// </summary>
+    private static void GuardRelativeRefInCanonical(string refLabel, string? rawValue, ParseState st)
+    {
+        if (rawValue is null) return;
+        string parentPrefix = PACKAGE_PARENT + PACKAGE_SEPARATOR; // "..::"
+        if (!rawValue.StartsWith(PACKAGE_SEPARATOR, StringComparison.Ordinal)
+            && !rawValue.StartsWith(parentPrefix, StringComparison.Ordinal))
+        {
+            return;
+        }
+        string path = st.Builder.ToString();
+        string msg =
+            $"relative reference '{rawValue}' on {refLabel} at {path} is not allowed in " +
+            $"canonical JSON — canonical JSON must be fully-qualified. Relative forms " +
+            $"(leading '{PACKAGE_SEPARATOR}' or '{parentPrefix}') are YAML-authoring sugar " +
+            $"that the desugar expands.";
+        throw new ParseException(
+            msg, ErrorCode.ERR_RELATIVE_REF_IN_CANONICAL, st.Source, path, st.CurrentSource());
+    }
+
     // -----------------------------------------------------------------------
     // splitTypeKey — split a fused wrapper key into (type, subType, explicit).
     //
@@ -902,6 +948,8 @@ private static void ApplyReservedKeys(
             }
             else
             {
+                // FR-032 — reject a relative `extends` ref in canonical JSON.
+                GuardRelativeRefInCanonical($"\"{RESERVED_KEY_EXTENDS}\"", rawExtends.GetString(), st);
                 model.SetSuper(rawExtends.GetString()!);
             }
         }
@@ -1112,6 +1160,15 @@ private static void ApplyInlineAttrsAndUnknownKeys(
                 continue;
             }
 
+            // FR-032 — reject a relative ref value on a ref-bearing inline @-attr
+            // (@objectRef/@references/@from/@of/@via/@payloadRef/@responseRef/
+            // @parameterRef) in canonical JSON. Only string values can be relative.
+            if (RefBearingAttrNames.Contains(attrName)
+                && rawVal.ValueKind == JsonValueKind.String)
+            {
+                GuardRelativeRefInCanonical($"\"{ATTR_PREFIX}{attrName}\"", rawVal.GetString(), st);
+            }
+
             AttrSchema? attrSpec = st.Registry
                 .AttrsOf(model.Type, model.SubType)
                 .FirstOrDefault(a => a.Name == attrName);
diff --git a/server/java/metadata/src/main/java/com/metaobjects/ErrorCode.java b/server/java/metadata/src/main/java/com/metaobjects/ErrorCode.java
@@ -311,6 +311,15 @@ public enum ErrorCode {
      */
     ERR_REGISTRY_SEALED,
 
+    /**
+     * FR-032 (ADR-0032): a ref-bearing attribute in canonical JSON carries a
+     * relative reference form (a value starting with {@code ::} or {@code ..::}).
+     * Canonical JSON is the self-contained interchange form and MUST be fully
+     * qualified — relative forms are a YAML-authoring affordance the desugar
+     * expands, so they must never survive into canonical JSON.
+     */
+    ERR_RELATIVE_REF_IN_CANONICAL,
+
     /** An internal loader error with no stable error code. */
     ERR_UNKNOWN,
 }
diff --git a/server/java/metadata/src/main/java/com/metaobjects/loader/parser/json/CanonicalJsonParser.java b/server/java/metadata/src/main/java/com/metaobjects/loader/parser/json/CanonicalJsonParser.java
@@ -125,6 +125,24 @@ public class CanonicalJsonParser extends BaseMetaDataParser implements MetaDataF
         KEY_IS_ARRAY, KEY_CHILDREN, KEY_VALUE
     );
 
+    /**
+     * FR-032 (ADR-0032) — the bare (sigil-free) inline attribute names whose VALUE is a
+     * metadata reference. In canonical JSON these are {@code @}-prefixed ({@code @objectRef}, …).
+     * Mirrors {@code YamlDesugar.REF_BEARING_ATTR_NAMES} and the TS {@code REF_BEARING_ATTR_NAMES}.
+     * The structural {@code extends} key is a reference too, but is guarded separately (it is the
+     * bare {@link #KEY_EXTENDS} body key, not an {@code @}-prefixed attr).
+     */
+    private static final Set<String> REF_BEARING_ATTR_NAMES = Set.of(
+        "objectRef", "references", "from", "of", "via",
+        "payloadRef", "responseRef", "parameterRef"
+    );
+
+    /** FR-032 — package separator ({@code ::}); a value with this leading prefix is root-absolute-relative. */
+    private static final String FR032_PKG_SEPARATOR = com.metaobjects.util.MetaDataUtil.SEP;
+
+    /** FR-032 — parent-relative prefix ({@code ..::}). */
+    private static final String FR032_PARENT_PREFIX = ".." + FR032_PKG_SEPARATOR;
+
     // -----------------------------------------------------------------------
     // Constructor
     // -----------------------------------------------------------------------
@@ -227,6 +245,33 @@ private ErrorSource buildCurrentSourceEnvelope() {
         return new JsonSource(List.of(getFilename()), path);
     }
 
+    /**
+     * FR-032 (ADR-0032) — guard a ref-bearing value against relative forms.
+     *
+     * <p>Canonical JSON is the self-contained interchange form: every ref-bearing
+     * attribute MUST be fully qualified. A relative authoring form (leading
+     * {@code ::} or {@code ..::}) surviving into canonical JSON is
+     * {@code ERR_RELATIVE_REF_IN_CANONICAL}. {@link CanonicalJsonParser} only ever
+     * handles canonical JSON (it is JSON by construction), so no format check is
+     * needed — the YAML desugar expands these forms before the parser sees them.
+     * Throwing halts the parse so exactly one error is produced, mirroring the
+     * {@code ERR_RESERVED_ATTR} rejection style.</p>
+     */
+    private void guardRelativeRefInCanonical(String refLabel, String rawValue) {
+        if (rawValue == null) return;
+        if (!rawValue.startsWith(FR032_PKG_SEPARATOR) && !rawValue.startsWith(FR032_PARENT_PREFIX)) {
+            return;
+        }
+        throw new MetaDataException(
+            ErrorMessageConstants.ERR_RELATIVE_REF_IN_CANONICAL
+                + ": relative reference '" + rawValue + "' on " + refLabel
+                + " in file [" + getFilename() + "] is not allowed in canonical JSON — "
+                + "canonical JSON must be fully-qualified. Relative forms (leading '"
+                + FR032_PKG_SEPARATOR + "' or '" + FR032_PARENT_PREFIX + "') are "
+                + "YAML-authoring sugar that the desugar expands.",
+            ErrorCode.ERR_RELATIVE_REF_IN_CANONICAL, currentSourceEnvelope());
+    }
+
     /**
      * FR5a / ADR-0009 — Re-throw a {@link MetaDataException} that escaped a
      * registry/base-parser call site without an envelope, stamping it with the
@@ -618,6 +663,8 @@ private void processNode(MetaData parent, String type, String subType,
         String pkg      = getStringOrNull(body, KEY_PACKAGE);
         // "extends" (canonical) → "super" (base parser slot)
         String superRef = getStringOrNull(body, KEY_EXTENDS);
+        // FR-032 — reject a relative `extends` ref in canonical JSON.
+        guardRelativeRefInCanonical("\"" + KEY_EXTENDS + "\"", superRef);
         // "abstract" (canonical) — handled AFTER node creation as an attribute
         Boolean isAbstract = getBooleanOrNull(body, KEY_ABSTRACT);
         Boolean isOverlay  = getBooleanOrNull(body, KEY_OVERLAY);
@@ -1117,6 +1164,16 @@ private void processAttributes(MetaData md, JsonObject body) {
             // Strip the @ prefix
             String attrName = key.substring(JSON_ATTR_PREFIX.length());
 
+            // FR-032 (ADR-0032) — reject a relative reference value on a ref-bearing
+            // inline attr (@objectRef / @references / @from / @of / @via / @payloadRef /
+            // @responseRef / @parameterRef). Canonical JSON must be fully-qualified.
+            if (REF_BEARING_ATTR_NAMES.contains(attrName)) {
+                JsonElement refVal = entry.getValue();
+                if (refVal.isJsonPrimitive() && refVal.getAsJsonPrimitive().isString()) {
+                    guardRelativeRefInCanonical(key, refVal.getAsString());
+                }
+            }
+
             // ADR-0006 §D1: reserved structural keywords must be written bare in canonical JSON.
             // Writing them as @-prefixed attributes (e.g. @isArray, @name) is unconditionally
             // invalid — there is no registry-exception.
diff --git a/server/java/metadata/src/main/java/com/metaobjects/util/ErrorMessageConstants.java b/server/java/metadata/src/main/java/com/metaobjects/util/ErrorMessageConstants.java
@@ -56,6 +56,15 @@ private ErrorMessageConstants() {
      */
     public static final String ERR_RESERVED_ATTR = "ERR_RESERVED_ATTR";
 
+    /**
+     * FR-032 (ADR-0032): a ref-bearing attribute in canonical JSON carries a
+     * relative reference form (value starting with {@code ::} or {@code ..::}).
+     * Canonical JSON must be fully qualified — relative forms are YAML-authoring
+     * sugar that the desugar expands before lowering to canonical JSON.
+     * Cross-language contract: {@code ERR_RELATIVE_REF_IN_CANONICAL}.
+     */
+    public static final String ERR_RELATIVE_REF_IN_CANONICAL = "ERR_RELATIVE_REF_IN_CANONICAL";
+
     /**
      * Error code emitted when a field origin (passthrough / aggregate / collection)
      * declares an invalid path or attribute (e.g. malformed {@code @via} relationship
diff --git a/server/java/metadata/src/test/resources/com/draagon/meta/loader/simple/fruitbasket-metadata.json b/server/java/metadata/src/test/resources/com/draagon/meta/loader/simple/fruitbasket-metadata.json
@@ -75,14 +75,14 @@
               "field.object": {
                 "name": "apples",
                 "isArray": true,
-                "@objectRef": "::Apple"
+                "@objectRef": "simple::fruitbasket::Apple"
               }
             },
             {
               "field.object": {
                 "name": "oranges",
                 "isArray": true,
-                "@objectRef": "::Orange"
+                "@objectRef": "simple::fruitbasket::Orange"
               }
             }
           ]
diff --git a/server/java/metadata/src/test/resources/com/draagon/meta/loader/simple/fruitbasket-proxy-metadata.json b/server/java/metadata/src/test/resources/com/draagon/meta/loader/simple/fruitbasket-proxy-metadata.json
@@ -85,21 +85,21 @@
               "field.object": {
                 "name": "fruitIds",
                 "isArray": true,
-                "@objectRef": "::Apple"
+                "@objectRef": "simple::fruitbasket::Apple"
               }
             },
             {
               "field.object": {
                 "name": "apples",
                 "isArray": true,
-                "@objectRef": "::Apple"
+                "@objectRef": "simple::fruitbasket::Apple"
               }
             },
             {
               "field.object": {
                 "name": "oranges",
                 "isArray": true,
-                "@objectRef": "::Orange"
+                "@objectRef": "simple::fruitbasket::Orange"
               }
             }
           ]
@@ -128,7 +128,7 @@
                 "@sourceFields": [
                   "basketId"
                 ],
-                "@objectRef": "::Basket"
+                "@objectRef": "simple::fruitbasket::Basket"
               }
             },
             {
@@ -138,7 +138,7 @@
                 "@sourceFields": [
                   "fruitId"
                 ],
-                "@objectRef": "::Fruit"
+                "@objectRef": "simple::fruitbasket::Fruit"
               }
             },
             {
@@ -179,7 +179,7 @@
                 "@sourceFields": [
                   "basketId"
                 ],
-                "@objectRef": "::Basket"
+                "@objectRef": "simple::fruitbasket::Basket"
               }
             },
             {
diff --git a/server/java/metadata/src/test/resources/com/metaobjects/loader/simple/fruitbasket-metadata.json b/server/java/metadata/src/test/resources/com/metaobjects/loader/simple/fruitbasket-metadata.json
@@ -75,14 +75,14 @@
               "field.object": {
                 "name": "apples",
                 "isArray": true,
-                "@objectRef": "::Apple"
+                "@objectRef": "simple::fruitbasket::Apple"
               }
             },
             {
               "field.object": {
                 "name": "oranges",
                 "isArray": true,
-                "@objectRef": "::Orange"
+                "@objectRef": "simple::fruitbasket::Orange"
               }
             }
           ]
diff --git a/server/java/metadata/src/test/resources/com/metaobjects/loader/simple/fruitbasket-proxy-metadata.json b/server/java/metadata/src/test/resources/com/metaobjects/loader/simple/fruitbasket-proxy-metadata.json
@@ -85,21 +85,21 @@
               "field.object": {
                 "name": "fruitIds",
                 "isArray": true,
-                "@objectRef": "::Apple"
+                "@objectRef": "simple::fruitbasket::Apple"
               }
             },
             {
               "field.object": {
                 "name": "apples",
                 "isArray": true,
-                "@objectRef": "::Apple"
+                "@objectRef": "simple::fruitbasket::Apple"
               }
             },
             {
               "field.object": {
                 "name": "oranges",
                 "isArray": true,
-                "@objectRef": "::Orange"
+                "@objectRef": "simple::fruitbasket::Orange"
               }
             }
           ]
@@ -128,7 +128,7 @@
                 "@sourceFields": [
                   "basketId"
                 ],
-                "@objectRef": "::Basket"
+                "@objectRef": "simple::fruitbasket::Basket"
               }
             },
             {
@@ -138,7 +138,7 @@
                 "@sourceFields": [
                   "fruitId"
                 ],
-                "@objectRef": "::Fruit"
+                "@objectRef": "simple::fruitbasket::Fruit"
               }
             },
             {
@@ -179,7 +179,7 @@
                 "@sourceFields": [
                   "basketId"
                 ],
-                "@objectRef": "::Basket"
+                "@objectRef": "simple::fruitbasket::Basket"
               }
             },
             {
diff --git a/server/python/src/metaobjects/naming_refs.py b/server/python/src/metaobjects/naming_refs.py
@@ -51,6 +51,15 @@
 PACKAGE_PARENT = ".."
 PARENT_PREFIX = PACKAGE_PARENT + PACKAGE_SEP  # "..::"
 
+
+def is_relative_ref(raw: str) -> bool:
+    """FR-032 — True when *raw* is a relative reference form (``::Rest`` or
+    ``..::Rest``) that the YAML desugar must expand before canonical JSON.
+    Canonical JSON must be FQN; a relative ref surviving into it is
+    ``ERR_RELATIVE_REF_IN_CANONICAL``. Mirrors TS ``isRelativeRef``.
+    """
+    return raw.startswith(PACKAGE_SEP) or raw.startswith(PARENT_PREFIX)
+
 #: FR-032 — the inline (``@``-prefixed in canonical JSON; bare in YAML) attribute
 #: names whose VALUE is a metadata reference subject to FQN expansion (ADR-0032
 #: §3). The structural ``extends`` key is handled separately (not ``@``-prefixed).
diff --git a/server/python/src/metaobjects/parser.py b/server/python/src/metaobjects/parser.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+[{"code":"ERR_RELATIVE_REF_IN_CANONICAL"}]`
Original file line number	Diff line number	Diff line change
`@@ -75,14 +75,14 @@`
`75`	`75`	`"field.object": {`
`76`	`76`	`"name": "apples",`
`77`	`77`	`"isArray": true,`
`78`		`- "@objectRef": "::Apple"`
	`78`	`+ "@objectRef": "simple::fruitbasket::Apple"`
`79`	`79`	`}`
`80`	`80`	`},`
`81`	`81`	`{`
`82`	`82`	`"field.object": {`
`83`	`83`	`"name": "oranges",`
`84`	`84`	`"isArray": true,`
`85`		`- "@objectRef": "::Orange"`
	`85`	`+ "@objectRef": "simple::fruitbasket::Orange"`
`86`	`86`	`}`
`87`	`87`	`}`
`88`	`88`	`]`
Original file line number	Diff line number	Diff line change
`@@ -85,21 +85,21 @@`
`85`	`85`	`"field.object": {`
`86`	`86`	`"name": "fruitIds",`
`87`	`87`	`"isArray": true,`
`88`		`- "@objectRef": "::Apple"`
	`88`	`+ "@objectRef": "simple::fruitbasket::Apple"`
`89`	`89`	`}`
`90`	`90`	`},`
`91`	`91`	`{`
`92`	`92`	`"field.object": {`
`93`	`93`	`"name": "apples",`
`94`	`94`	`"isArray": true,`
`95`		`- "@objectRef": "::Apple"`
	`95`	`+ "@objectRef": "simple::fruitbasket::Apple"`
`96`	`96`	`}`
`97`	`97`	`},`
`98`	`98`	`{`
`99`	`99`	`"field.object": {`
`100`	`100`	`"name": "oranges",`
`101`	`101`	`"isArray": true,`
`102`		`- "@objectRef": "::Orange"`
	`102`	`+ "@objectRef": "simple::fruitbasket::Orange"`
`103`	`103`	`}`
`104`	`104`	`}`
`105`	`105`	`]`
`@@ -128,7 +128,7 @@`
`128`	`128`	`"@sourceFields": [`
`129`	`129`	`"basketId"`
`130`	`130`	`],`
`131`		`- "@objectRef": "::Basket"`
	`131`	`+ "@objectRef": "simple::fruitbasket::Basket"`
`132`	`132`	`}`
`133`	`133`	`},`
`134`	`134`	`{`
`@@ -138,7 +138,7 @@`
`138`	`138`	`"@sourceFields": [`
`139`	`139`	`"fruitId"`
`140`	`140`	`],`
`141`		`- "@objectRef": "::Fruit"`
	`141`	`+ "@objectRef": "simple::fruitbasket::Fruit"`
`142`	`142`	`}`
`143`	`143`	`},`
`144`	`144`	`{`
`@@ -179,7 +179,7 @@`
`179`	`179`	`"@sourceFields": [`
`180`	`180`	`"basketId"`
`181`	`181`	`],`
`182`		`- "@objectRef": "::Basket"`
	`182`	`+ "@objectRef": "simple::fruitbasket::Basket"`
`183`	`183`	`}`
`184`	`184`	`},`
`185`	`185`	`{`