Merge worktree-fr5d-java-2026-05-27 — FR5d Java (resolved envelopes; surfaces cross-port FQN divergence — Java emits package-qualified vs TS/C#/Python bare, to reconcile at finalize)

dmealing · dmealing · commit 260b814fe485 · 2026-05-27T04:49:22.000-04:00
diff --git a/server/java/metadata/conformance-expected-failures.json b/server/java/metadata/conformance-expected-failures.json
@@ -1,5 +1,11 @@
 {
   "language": "java",
-  "_comment": "FR5a envelope-shape gates: empty ledger.",
-  "fixtures": []
+  "_comment": "FR5d (2026-05-27): Java port emits format=resolved for reference-resolution errors (extends:, @via, @of, @payloadRef, @requiredSlots). Fixtures still encode the FR5a-era format=json envelope per the cross-port-safety stance — these will migrate once all four ports ship FR5d, at which point the ledger entries can be removed.",
+  "fixtures": [
+    "error-extends-nonexistent",
+    "error-origin-bad-via-path",
+    "error-template-payload-ref-not-value",
+    "error-template-payload-ref-unresolved",
+    "error-template-required-slot-missing"
+  ]
 }
diff --git a/server/java/metadata/src/main/java/com/metaobjects/loader/MetaDataLoader.java b/server/java/metadata/src/main/java/com/metaobjects/loader/MetaDataLoader.java
@@ -208,15 +208,21 @@ private void resolvePendingExtends() {
                 }
             }
             if (superData == null) {
-                // FR5a / ADR-0009 — pass the unresolved child's source envelope so
-                // the cross-port harness can report the offending node's
-                // file + JSONPath rather than a root-of-file shape.
+                // FR5d — emit format=resolved with referrer + target. The referrer's
+                // parse-time source supplies files + jsonPath (the location of the
+                // broken `extends:` on disk); referrer = the declaring node's FQN;
+                // target = the unresolved supertype ref. Mirrors TS
+                // `resolveDeferredSupers` in server/typescript/packages/metadata/
+                // src/loader/meta-data-loader.ts.
+                com.metaobjects.source.ErrorSource envelope =
+                    com.metaobjects.source.ResolvedSource.from(
+                        p.child.getSource(), p.child.getName(), p.superName);
                 throw new com.metaobjects.MetaDataException(
                     "Invalid MetaData [" + p.typeName + "][" + p.child.getShortName()
                         + "], the SuperClass [" + p.superName + "] does not exist (deferred resolution)"
                         + " in file [" + p.filename + "]",
                     com.metaobjects.ErrorCode.ERR_UNRESOLVED_SUPER,
-                    p.child.getSource());
+                    envelope);
             }
             p.child.setSuperData(superData);
         }
diff --git a/server/java/metadata/src/main/java/com/metaobjects/loader/ValidationPhase.java b/server/java/metadata/src/main/java/com/metaobjects/loader/ValidationPhase.java
@@ -34,6 +34,7 @@
 import com.metaobjects.origin.PassthroughOrigin;
 import com.metaobjects.relationship.MetaRelationship;
 import com.metaobjects.source.MetaSource;
+import com.metaobjects.source.ResolvedSource;
 import com.metaobjects.template.MetaTemplate;
 import com.metaobjects.template.OutputTemplate;
 import com.metaobjects.template.PromptTemplate;
@@ -572,11 +573,11 @@ private static void validateOriginNode(MetaRoot root, MetaObject obj,
                         + ": missing @from.",
                     ErrorCode.ERR_INVALID_ORIGIN, origin.getSource());
             }
-            validateFromOrOfPath(from, root, obj.getName(), field.getName(),
+            validateFromOrOfPath(from, root, obj, field.getName(),
                 "origin.passthrough.@from", origin.getSource());
             String via = origin.getVia();
             if (via != null && !via.isEmpty()) {
-                validateViaPath(via, root, obj.getName(), field.getName(), origin.getSource());
+                validateViaPath(via, root, obj, field.getName(), origin.getSource());
             }
             return;
         }
@@ -603,7 +604,7 @@ private static void validateOriginNode(MetaRoot root, MetaObject obj,
                         + ": missing @of.",
                     ErrorCode.ERR_INVALID_ORIGIN, origin.getSource());
             }
-            validateFromOrOfPath(of, root, obj.getName(), field.getName(),
+            validateFromOrOfPath(of, root, obj, field.getName(),
                 "origin.aggregate.@of", origin.getSource());
 
             String via = origin.getVia();
@@ -614,7 +615,7 @@ private static void validateOriginNode(MetaRoot root, MetaObject obj,
                         + ": missing @via (aggregates require a relationship path).",
                     ErrorCode.ERR_INVALID_ORIGIN, origin.getSource());
             }
-            validateViaPath(via, root, obj.getName(), field.getName(), origin.getSource());
+            validateViaPath(via, root, obj, field.getName(), origin.getSource());
             return;
         }
 
@@ -1068,11 +1069,14 @@ private static void validateTemplateNode(MetaRoot root, MetaTemplate template) {
 
         MetaObject payloadVo = findRootObject(root, payloadRef);
         if (payloadVo == null || !MetaObject.SUBTYPE_VALUE.equals(payloadVo.getSubType())) {
+            // FR5d — @payloadRef is a reference; emit format=resolved with
+            // referrer=template FQN, target=the unresolved payloadRef string.
             throw new MetaDataException(
                 ErrorMessageConstants.ERR_INVALID_TEMPLATE
                     + ": template '" + template.getName() + "' @payloadRef '" + payloadRef
                     + "' does not resolve to an object.value at root",
-                ErrorCode.ERR_INVALID_TEMPLATE, template.getSource());
+                ErrorCode.ERR_INVALID_TEMPLATE,
+                ResolvedSource.from(template.getSource(), template.getName(), payloadRef));
         }
 
         // R3 — every @requiredSlots member must be a field on the payload VO
@@ -1084,12 +1088,17 @@ private static void validateTemplateNode(MetaRoot root, MetaTemplate template) {
         for (String slot : required) {
             if (slot == null || slot.isEmpty()) continue;
             if (!available.contains(slot)) {
+                // FR5d — @requiredSlots is a field-on-payload reference; emit
+                // format=resolved with referrer=template FQN, target=`payloadRef.slot`
+                // (the dotted ref that did not resolve to a payload field).
                 throw new MetaDataException(
                     ErrorMessageConstants.ERR_INVALID_TEMPLATE
                         + ": template.prompt '" + template.getName()
                         + "' @requiredSlots includes '" + slot
                         + "' which is not a field on payload '" + payloadRef + "'",
-                    ErrorCode.ERR_INVALID_TEMPLATE, template.getSource());
+                    ErrorCode.ERR_INVALID_TEMPLATE,
+                    ResolvedSource.from(template.getSource(), template.getName(),
+                        payloadRef + "." + slot));
             }
         }
     }
@@ -1112,31 +1121,48 @@ private static Set<String> collectPayloadFieldNames(MetaObject payloadVo) {
      * and aggregate's @of). The entity must exist at the root, and the field
      * must exist on that entity (inherited fields are included via the standard
      * children() traversal).
+     *
+     * <p>FR5d: emits {@code format=resolved} envelopes for every throw. The
+     * referrer FQN format is {@code "<projection-FQN>::<fieldName>"} (mirrors
+     * the TS {@code _validateFromPath} contract); the target is the bad ref
+     * string itself.</p>
+     *
+     * @param projection the projection node that owns the field carrying the origin
      */
     private static void validateFromOrOfPath(String pathAttr, MetaRoot root,
-                                             String projectionName, String fieldName,
+                                             MetaObject projection, String fieldName,
                                              String label,
                                              com.metaobjects.source.ErrorSource envelope) {
+        // FR5d — referrer is `<projection-FQN>::<fieldName>` (the canonical
+        // "where the broken reference lives" identifier).
+        String projectionName = projection.getName();
+        String referrer = projection.getName() + "::" + fieldName;
         int dotIdx = pathAttr.indexOf('.');
         if (dotIdx < 1 || dotIdx == pathAttr.length() - 1) {
+            // Malformed shape (not "Entity.field") — not a reference resolution
+            // failure per se, but emit format=resolved with target=the bad string
+            // so consumers see the same envelope shape across all FR5d sites.
             throw new MetaDataException(
                 ErrorMessageConstants.ERR_INVALID_ORIGIN
                     + ": " + label + " \"" + pathAttr + "\" on "
                     + projectionName + "." + fieldName
                     + ": must be of form \"Entity.field\".",
-                ErrorCode.ERR_INVALID_ORIGIN, envelope);
+                ErrorCode.ERR_INVALID_ORIGIN,
+                ResolvedSource.from(envelope, referrer, pathAttr));
         }
         String entityName = pathAttr.substring(0, dotIdx);
         String targetFieldName = pathAttr.substring(dotIdx + 1);
 
         MetaObject sourceObj = findRootObject(root, entityName);
         if (sourceObj == null) {
+            // FR5d — entity half of the ref didn't resolve. target = full ref.
             throw new MetaDataException(
                 ErrorMessageConstants.ERR_INVALID_ORIGIN
                     + ": " + label + " \"" + pathAttr + "\" on "
                     + projectionName + "." + fieldName
                     + ": no such entity \"" + entityName + "\".",
-                ErrorCode.ERR_INVALID_ORIGIN, envelope);
+                ErrorCode.ERR_INVALID_ORIGIN,
+                ResolvedSource.from(envelope, referrer, pathAttr));
         }
 
         // Inherited fields included — getChildren(..., true) walks super data.
@@ -1148,13 +1174,15 @@ private static void validateFromOrOfPath(String pathAttr, MetaRoot root,
             }
         }
         if (!fieldExists) {
+            // FR5d — entity resolved, field on it did not. target = full ref.
             throw new MetaDataException(
                 ErrorMessageConstants.ERR_INVALID_ORIGIN
                     + ": " + label + " \"" + pathAttr + "\" on "
                     + projectionName + "." + fieldName
                     + ": no such field \"" + targetFieldName
                     + "\" on " + entityName + ".",
-                ErrorCode.ERR_INVALID_ORIGIN, envelope);
+                ErrorCode.ERR_INVALID_ORIGIN,
+                ResolvedSource.from(envelope, referrer, pathAttr));
         }
     }
 
@@ -1166,16 +1194,20 @@ private static void validateFromOrOfPath(String pathAttr, MetaRoot root,
      * which becomes the next hop's current entity.
      */
     private static void validateViaPath(String viaAttr, MetaRoot root,
-                                        String projectionName, String fieldName,
+                                        MetaObject projection, String fieldName,
                                         com.metaobjects.source.ErrorSource envelope) {
+        // FR5d — referrer is `<projection-FQN>::<fieldName>`.
+        String projectionName = projection.getName();
+        String referrer = projection.getName() + "::" + fieldName;
         String[] segments = viaAttr.split("\\.");
         if (segments.length < 2) {
             throw new MetaDataException(
                 ErrorMessageConstants.ERR_INVALID_ORIGIN
                     + ": origin.@via \"" + viaAttr + "\" on "
                     + projectionName + "." + fieldName
                     + ": must be of form \"Entity.relationship[.relationship...]\".",
-                ErrorCode.ERR_INVALID_ORIGIN, envelope);
+                ErrorCode.ERR_INVALID_ORIGIN,
+                ResolvedSource.from(envelope, referrer, viaAttr));
         }
         String entityName = segments[0];
         MetaObject currentObj = findRootObject(root, entityName);
@@ -1185,19 +1217,30 @@ private static void validateViaPath(String viaAttr, MetaRoot root,
                     + ": origin.@via \"" + viaAttr + "\" on "
                     + projectionName + "." + fieldName
                     + ": no such entity \"" + entityName + "\".",
-                ErrorCode.ERR_INVALID_ORIGIN, envelope);
-        }
+                ErrorCode.ERR_INVALID_ORIGIN,
+                ResolvedSource.from(envelope, referrer, viaAttr));
+        }
+        // FR5d — track the deepest-valid-prefix as we walk. The prefix grows
+        // segment-by-segment; on a hop failure the error message names the prefix
+        // that DID resolve, so authors can fix multi-hop typos quickly. After the
+        // entity lookup above, the deepest valid prefix is just the entity name;
+        // each successful relationship hop appends a segment.
+        java.util.List<String> validSegments = new java.util.ArrayList<>();
+        validSegments.add(entityName);
         for (int i = 1; i < segments.length; i++) {
             String relName = segments[i];
             MetaRelationship rel = findRelationship(currentObj, relName);
             if (rel == null) {
+                String prefix = String.join(".", validSegments);
                 throw new MetaDataException(
                     ErrorMessageConstants.ERR_INVALID_ORIGIN
                         + ": origin.@via \"" + viaAttr + "\" on "
                         + projectionName + "." + fieldName
                         + ": no such relationship \"" + relName
-                        + "\" on " + currentObj.getName() + ".",
-                    ErrorCode.ERR_INVALID_ORIGIN, envelope);
+                        + "\" on " + currentObj.getName() + ". "
+                        + "Deepest valid prefix was \"" + prefix + "\".",
+                    ErrorCode.ERR_INVALID_ORIGIN,
+                    ResolvedSource.from(envelope, referrer, viaAttr));
             }
             String refTarget = rel.hasMetaAttr(MetaRelationship.ATTR_OBJECT_REF)
                 ? rel.getMetaAttr(MetaRelationship.ATTR_OBJECT_REF).getValueAsString()
@@ -1209,18 +1252,25 @@ private static void validateViaPath(String viaAttr, MetaRoot root,
                         + projectionName + "." + fieldName
                         + ": relationship \"" + relName + "\" on "
                         + currentObj.getName() + " is missing @objectRef.",
-                    ErrorCode.ERR_INVALID_ORIGIN, envelope);
+                    ErrorCode.ERR_INVALID_ORIGIN,
+                    ResolvedSource.from(envelope, referrer, viaAttr));
             }
             MetaObject nextObj = findRootObject(root, refTarget);
             if (nextObj == null) {
+                // FR5d — relationship's @objectRef points at a missing entity. This
+                // is the @objectRef-resolution edge of the via-path walk (the "5th
+                // site" in FR5d's scope list for @objectRef references encountered
+                // transitively). Target = the @objectRef value (the missing entity name).
                 throw new MetaDataException(
                     ErrorMessageConstants.ERR_INVALID_ORIGIN
                         + ": origin.@via \"" + viaAttr + "\" on "
                         + projectionName + "." + fieldName
                         + ": relationship \"" + relName
                         + "\" points to non-existent entity \"" + refTarget + "\".",
-                    ErrorCode.ERR_INVALID_ORIGIN, envelope);
+                    ErrorCode.ERR_INVALID_ORIGIN,
+                    ResolvedSource.from(envelope, referrer, refTarget));
             }
+            validSegments.add(relName);
             currentObj = nextObj;
         }
     }
diff --git a/server/java/metadata/src/main/java/com/metaobjects/source/ResolvedSource.java b/server/java/metadata/src/main/java/com/metaobjects/source/ResolvedSource.java
@@ -41,6 +41,60 @@ public ResolvedSource(List<String> files) {
         this(files, null, null, null);
     }
 
+    /**
+     * FR5d — build a {@code format: "resolved"} envelope from a referrer node's
+     * source envelope (typically a {@link JsonSource} or {@link YamlSource}
+     * parse-time source) plus the referrer FQN and unresolved target string.
+     *
+     * <p>The resolved envelope carries:</p>
+     * <ul>
+     *   <li>{@code files}: the referrer's source files (so editors can jump to it),</li>
+     *   <li>{@code jsonPath}: the referrer's jsonPath when known (the location of
+     *       the broken reference on disk),</li>
+     *   <li>{@code referrer}: the FQN of the metadata node that declared the broken
+     *       reference (e.g. {@code "acme::Premium"}),</li>
+     *   <li>{@code target}: the unresolved reference string itself (e.g.
+     *       {@code "BaseEntity"}, {@code "Program.weeks.invalid"},
+     *       {@code "DoesNotExist"}).</li>
+     * </ul>
+     *
+     * <p>{@code referrerSource} may be any {@link ErrorSource} variant — we read its
+     * files/jsonPath best-effort and fall back to an empty {@code files: []} when
+     * the referrer's source is itself a {@link CodeSource}/{@link DatabaseSource}
+     * envelope. Mirrors the TS {@code resolvedSource(referrerSource, referrer, target)}
+     * helper in {@code server/typescript/packages/metadata/src/source.ts}.</p>
+     *
+     * @param referrerSource the source envelope of the node declaring the broken reference
+     * @param referrer the FQN of the referrer node; may be {@code null}
+     * @param target the unresolved reference string; may be {@code null}
+     * @return a {@code format: "resolved"} envelope populated from the referrer
+     */
+    public static ResolvedSource from(ErrorSource referrerSource, String referrer, String target) {
+        List<String> files;
+        String jsonPath;
+        if (referrerSource instanceof JsonSource js) {
+            files = js.files();
+            jsonPath = js.jsonPath();
+        } else if (referrerSource instanceof YamlSource ys) {
+            files = ys.files();
+            jsonPath = ys.jsonPath();
+        } else if (referrerSource instanceof MergedSource ms) {
+            files = ms.files();
+            jsonPath = ms.jsonPath();
+        } else if (referrerSource instanceof ResolvedSource rs) {
+            files = rs.files();
+            jsonPath = rs.jsonPath();
+        } else if (referrerSource instanceof DatabaseSource ds) {
+            files = List.of();
+            jsonPath = ds.jsonPath();
+        } else {
+            // CodeSource or null
+            files = List.of();
+            jsonPath = null;
+        }
+        return new ResolvedSource(files, jsonPath, referrer, target);
+    }
+
     @Override
     public String format() {
         return "resolved";
diff --git a/server/java/metadata/src/test/java/com/metaobjects/loader/Fr5dReferenceResolutionTest.java b/server/java/metadata/src/test/java/com/metaobjects/loader/Fr5dReferenceResolutionTest.java

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,11 @@`
`1`	`1`	`{`
`2`	`2`	`"language": "java",`
`3`		`- "_comment": "FR5a envelope-shape gates: empty ledger.",`
`4`		`- "fixtures": []`
	`3`	`+ "_comment": "FR5d (2026-05-27): Java port emits format=resolved for reference-resolution errors (extends:, @via, @of, @payloadRef, @requiredSlots). Fixtures still encode the FR5a-era format=json envelope per the cross-port-safety stance — these will migrate once all four ports ship FR5d, at which point the ledger entries can be removed.",`
	`4`	`+ "fixtures": [`
	`5`	`+ "error-extends-nonexistent",`
	`6`	`+ "error-origin-bad-via-path",`
	`7`	`+ "error-template-payload-ref-not-value",`
	`8`	`+ "error-template-payload-ref-unresolved",`
	`9`	`+ "error-template-required-slot-missing"`
	`10`	`+ ]`
`5`	`11`	`}`