refactor(metadata): tighten WA2 commonAttrs additions — name the universal-tier key, drop ATTR_PREFIX alias, sharpen comments

Behavior-preserving simplifications across the WA2 commonAttrs surface:

- MetaDataRegistry: extract UNIVERSAL_PARENT_KEY constant for the "*.*"
  globalRequirements tier (named over magic string; 3 usages).
- MetaDataRegistry.isArrayShapedValue: switch to pattern-matching instanceof
  (Java 21) and add Javadoc clarifying that the empty-string branch handles
  the desugar-invariant case (post-`[]` token), not author input.
- CanonicalJsonParser: drop the private @deprecated ATTR_PREFIX alias and
  use JSON_ATTR_PREFIX directly at its 3 sites; the alias was internal-only
  so no external consumer is affected (only the public JSON_ATTR_PREFIX is
  referenced from codegen-base).
- BaseMetaDataParser: add a real import for CommonAttributeDef to drop the
  fully-qualified reference in the lookup body.
- ConformanceTest: add a "maintenance caveat" comment on PROVIDER_ALIASES
  per code-review feedback — if any of the 8 backing Java provider ids is
  renamed or removed, the cross-language alias silently disappears.

Tests: metadata 608/0/0, ConformanceTest 168/0/0. Downstream codegen-base
compiles unchanged.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: dmealing

server/java/metadata/src/main/java/com/metaobjects/loader/parser/BaseMetaDataParser.java

@@ -10,6 +10,7 @@
 import com.metaobjects.identity.MetaIdentity;
 import com.metaobjects.loader.MetaDataLoader;
 import com.metaobjects.object.MetaObject;
+import com.metaobjects.registry.CommonAttributeDef;
 import com.metaobjects.registry.MetaDataRegistry;
 import com.metaobjects.registry.TypeDefinition;
 import com.metaobjects.registry.ChildRequirement;
@@ -864,8 +865,7 @@ protected String getExpectedAttributeSubTypeFromRegistry(TypeDefinition typeDef,
         // honour its declared value subtype. Checked BEFORE the wildcard "attr,*"
         // fallback so a non-string common attr (e.g. a future boolean) is not
         // silently coerced to "string" by the open-policy default.
-        com.metaobjects.registry.CommonAttributeDef commonDef =
-            getTypeRegistry().getCommonAttribute(attrName);
+        CommonAttributeDef commonDef = getTypeRegistry().getCommonAttribute(attrName);
         if (commonDef != null) {
             return commonDef.valueType();
         }

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

@@ -102,10 +102,6 @@ public class CanonicalJsonParser extends BaseMetaDataParser implements MetaDataF
      */
     public static final String JSON_ATTR_PREFIX = "@";
 
-    /** @deprecated use {@link #JSON_ATTR_PREFIX} */
-    @Deprecated
-    private static final String ATTR_PREFIX = JSON_ATTR_PREFIX;
-
     /** All reserved body keys — keys handled structurally (not as @-attrs). */
     private static final List<String> RESERVED_KEYS = Arrays.asList(
         KEY_NAME, KEY_PACKAGE, KEY_EXTENDS, KEY_ABSTRACT, KEY_OVERLAY,
@@ -546,7 +542,7 @@ private void processAttributes(MetaData md, JsonObject body) {
                 continue;
             }
 
-            if (!key.startsWith(ATTR_PREFIX)) {
+            if (!key.startsWith(JSON_ATTR_PREFIX)) {
                 // Non-reserved, non-@-prefixed key — warn and skip
                 log.warn("Unknown key '{}' on node [{}:{}:{}] in file [{}] — " +
                     "must be reserved or @-prefixed",
@@ -555,7 +551,7 @@ private void processAttributes(MetaData md, JsonObject body) {
             }
 
             // Strip the @ prefix
-            String attrName = key.substring(ATTR_PREFIX.length());
+            String attrName = key.substring(JSON_ATTR_PREFIX.length());
 
             // ADR-0006 §D1: reserved structural keywords must be written bare in canonical JSON.
             // Writing them as @-prefixed attributes (e.g. @isArray, @name) is unconditionally
@@ -564,7 +560,7 @@ private void processAttributes(MetaData md, JsonObject body) {
                 throw new MetaDataException(
                     ErrorMessageConstants.ERR_RESERVED_ATTR
                         + ": reserved structural key '" + attrName + "' must not be "
-                        + ATTR_PREFIX + "-prefixed on " + md.getType() + "." + md.getSubType()
+                        + JSON_ATTR_PREFIX + "-prefixed on " + md.getType() + "." + md.getSubType()
                         + " '" + md.getName() + "' in file [" + getFilename() + "] — write it bare",
                     ErrorCode.ERR_RESERVED_ATTR);
             }

server/java/metadata/src/main/java/com/metaobjects/registry/MetaDataRegistry.java

@@ -86,6 +86,14 @@ public class MetaDataRegistry {
      */
     private final Map<String, CommonAttributeDef> commonAttributes = new ConcurrentHashMap<>();
 
+    /**
+     * Fully-global parent-key tier in {@link #globalRequirements} — matches any
+     * (parentType, parentSubType). Used by {@link #registerCommonAttribute} so
+     * common attrs surface on every node via {@link #acceptsChild} /
+     * {@link #getChildRequirements}.
+     */
+    private static final String UNIVERSAL_PARENT_KEY = "*.*";
+
     private volatile boolean initialized = false;
 
     /**
@@ -355,8 +363,8 @@ public boolean acceptsChild(String parentType, String parentSubType,
             }
         }
 
-        // Check fully-global "*.*" requirements (common attributes on any node)
-        List<ChildRequirement> universalReqs = globalRequirements.get("*.*");
+        // Check fully-global universal requirements (common attributes on any node)
+        List<ChildRequirement> universalReqs = globalRequirements.get(UNIVERSAL_PARENT_KEY);
         if (universalReqs != null) {
             for (ChildRequirement req : universalReqs) {
                 if (req.matches(childType, childSubType, childName)) {
@@ -398,8 +406,8 @@ public List<ChildRequirement> getChildRequirements(String parentType, String par
             requirements.addAll(wildcardReqs);
         }
 
-        // Add fully-global "*.*" requirements (common attributes on any node)
-        List<ChildRequirement> universalReqs = globalRequirements.get("*.*");
+        // Add fully-global universal requirements (common attributes on any node)
+        List<ChildRequirement> universalReqs = globalRequirements.get(UNIVERSAL_PARENT_KEY);
         if (universalReqs != null) {
             requirements.addAll(universalReqs);
         }
@@ -493,8 +501,8 @@ public void registerCommonAttribute(String name, String valueType, boolean isArr
         CommonAttributeDef def = new CommonAttributeDef(name, valueType, isArray);
         commonAttributes.put(name, def);
 
-        // 1. Global ChildRequirement under "*.*" — makes acceptsChild() return true
-        //    for this attr on any (parentType, parentSubType) pair.
+        // 1. Global ChildRequirement under the UNIVERSAL_PARENT_KEY tier — makes
+        //    acceptsChild() return true for this attr on any (parentType, parentSubType) pair.
         ChildRequirement req = new ChildRequirement(name, MetaAttribute.TYPE_ATTR, valueType, false);
         addGlobalChildRequirement("*", "*", req);
 
@@ -554,14 +562,19 @@ public boolean hasCommonAttributes() {
      * {@code null} is permitted (optional), bracketed or comma-delimited string
      * forms are permitted. The actual structured list value (post-desugar) is a
      * {@code List<?>} which we also accept.
+     *
+     * <p>The empty-string acceptance is the desugar-invariant case (not author
+     * input): the canonical bare-string desugar in CanonicalJsonParser may emit
+     * an empty token through {@code convertJsonArrayToCommaDelimited} for an
+     * empty JSON array {@code []}. Authored empty values arrive as {@code null}
+     * via the optional-attr path.</p>
      */
     private static boolean isArrayShapedValue(Object value) {
         if (value == null) return true; // optional
         if (value instanceof List<?>) return true;
-        if (value instanceof String) {
-            String s = (String) value;
+        if (value instanceof String s) {
             return (s.startsWith("[") && s.endsWith("]")) || s.contains(",")
-                || s.isEmpty(); // empty post-desugar
+                || s.isEmpty(); // empty post-desugar (see Javadoc)
         }
         return false;
     }

server/java/metadata/src/test/java/com/metaobjects/conformance/ConformanceTest.java

@@ -99,6 +99,13 @@ public class ConformanceTest {
      *
      * <p>Declared BEFORE {@link #AVAILABLE_PROVIDERS} so it is initialised first
      * (JLS §12.4 — class-init runs static fields top-to-bottom).</p>
+     *
+     * <p><strong>Maintenance caveat:</strong> if Java ever drops or renames one
+     * of the 8 backing provider ids below, the {@code metaobjects-core-types}
+     * alias will silently disappear from {@link #AVAILABLE_PROVIDERS} and any
+     * fixture requiring it will fail honestly (as a missing-provider gap, not a
+     * silent skip). Keep this list in sync with the actual provider IDs declared
+     * in {@code META-INF/services/com.metaobjects.registry.MetaDataTypeProvider}.</p>
      */
     private static final java.util.Map<String, List<String>> PROVIDER_ALIASES =
         java.util.Map.of(