feat(java): FR5a — thread source through parser + validation + MetaData.source

Wire the ErrorSource foundation (commit 1) through the canonical JSON
parse pipeline and the per-node validation phase, per ADR-0009.

MetaData base class:
  - Adds `private ErrorSource source = CodeSource.DEFAULT` so every node
    always has a populated provenance (never null per ADR-0009 §Decision).
  - `getSource()` / `setSource(ErrorSource)` API.
  - `freezeSource()` / `isSourceFrozen()` freeze guard — once frozen the
    setter throws IllegalStateException (mirrors the C# private-set +
    Freeze() pattern).
  - `setSource(null)` throws NullPointerException with a CodeSource.DEFAULT
    hint.

MetaDataException:
  - New optional `envelope: ErrorSource` field, exposed via
    `getEnvelope(): Optional<ErrorSource>`.
  - New convenience constructor `(message, ErrorCode, ErrorSource)` for
    loader sites, plus a full 7-arg internal constructor.
  - All existing constructors remain back-compat (envelope defaults to
    null when not provided).

CanonicalJsonParser:
  - Maintains a `JsonPath.Builder` field; pushes/pops keys + indices as
    the tree walk descends. The wrapper key, `children`, the array index,
    and the fused `<type>.<subType>` key are all pushed in order so the
    canonical JSONPath matches the C# / TS oracle byte-identically.
  - `tagNodeWithJsonSource(node)` overwrites `CodeSource.DEFAULT` with a
    fresh JsonSource on every parser-constructed node (root, structural
    children, attr children). Skips if the node already carries a
    JsonSource (overlay path) — the merge phase owns transitions to
    MergedSource (FR5c slot).
  - `currentJsonSource()` builds an envelope at the active JSONPath for
    parse-time errors. Wired into the ERR_UNKNOWN_TYPE root check, the
    ERR_RESERVED_ATTR @-on-reserved-key throw, and the
    ERR_BAD_ATTR_VALUE filter-as-string throw.

ValidationPhase (representative migration; full sweep is incremental):
  - field.enum validators now pass `node.getSource()` into the envelope
    constructor (ERR_BAD_ATTR_VALUE for malformed @values,
    ERR_MISSING_REQUIRED_ATTR when neither own nor inherited @values
    present). Pattern for other ValidationPhase sites that have a node
    in scope is identical.

Canonical JSON serializer: no changes required. The serializer reads
fields explicitly (name, package, extends, @-attrs, children), so the
new `source` field is naturally omitted from output. Round-trip parity
preserved.

Tests:
  - SourceOnNodeTest (9 tests) covers programmatic default
    (CodeSource.DEFAULT), setSource() + freeze guard, the JsonSource
    length-1 invariant, parser-populated JsonSource at every depth
    (root + entity + field), canonical-serializer omission, and
    parse-error envelope propagation (ERR_RESERVED_ATTR).

Java metadata suite: 647/647 baseline → 680/680 after FR5a (+33 new
tests across JsonPath/SemanticDiff/SourceOnNode). No regressions.

Refs: ADR-0009, docs/superpowers/specs/2026-05-25-fr5a-json-shape-loader-errors.md

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

Author: dmealing

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

@@ -22,6 +22,8 @@
 import com.metaobjects.cache.CacheStrategy;
 import com.metaobjects.cache.HybridCache;
 import com.metaobjects.collections.IndexedMetaDataCollection;
+import com.metaobjects.source.CodeSource;
+import com.metaobjects.source.ErrorSource;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -278,6 +280,17 @@ public static void registerTypes() {
     private MetaDataLoader loader = null;
     private ClassLoader metaDataClassLoader=null;
 
+    // FR5a / ADR-0009 — Loader error envelope + source-on-node.
+    //
+    // Every metadata node carries its own provenance. `source` is always populated;
+    // the default for any node not built by a loader phase is CodeSource.DEFAULT
+    // (format == "code"). The loader's parser overwrites this with a JsonSource /
+    // YamlSource / MergedSource / ResolvedSource / DatabaseSource as it builds the
+    // tree. Mirrors C# MetaData.Source ({ get; private set; }) — settable through
+    // setSource(), frozen after freezeSource() is called.
+    private ErrorSource source = CodeSource.DEFAULT;
+    private boolean sourceFrozen = false;
+
     /**
      * Constructs a MetaData object with enhanced type system integration.
      * 
@@ -896,6 +909,71 @@ public boolean hasSuperData() {
         return superData != null;
     }
 
+    ////////////////////////////////////////////////////
+    // FR5a / ADR-0009 — Source-on-node provenance
+
+    /**
+     * Returns the provenance envelope describing where this node was constructed.
+     *
+     * <p>Never returns {@code null}: nodes built programmatically (via the public
+     * Java API without a loader) default to {@link CodeSource#DEFAULT}. Nodes built
+     * by the loader pipeline carry a {@link com.metaobjects.source.JsonSource}
+     * (canonical-JSON parse), and post-load phases may overwrite this with a
+     * {@link com.metaobjects.source.MergedSource} or
+     * {@link com.metaobjects.source.ResolvedSource}.</p>
+     *
+     * @return the provenance envelope; never {@code null}
+     * @since FR5a / ADR-0009
+     */
+    public ErrorSource getSource() {
+        return source;
+    }
+
+    /**
+     * Sets the provenance envelope for this node.
+     *
+     * <p>Honors the freeze guard installed by {@link #freezeSource()}: once frozen,
+     * any further mutation throws {@link IllegalStateException}. The loader
+     * pipeline freezes after construction; this lets phases mutate source during
+     * load while preventing accidental mutation by runtime consumers.</p>
+     *
+     * @param source the provenance envelope; must not be {@code null}
+     * @throws NullPointerException if {@code source} is {@code null}
+     * @throws IllegalStateException if this node's source is already frozen
+     * @since FR5a / ADR-0009
+     */
+    public void setSource(ErrorSource source) {
+        if (source == null) {
+            throw new NullPointerException("MetaData source must not be null — use CodeSource.DEFAULT for the no-loader case");
+        }
+        if (sourceFrozen) {
+            throw new IllegalStateException("MetaData source is frozen and cannot be modified: " + this);
+        }
+        this.source = source;
+    }
+
+    /**
+     * Marks this node's {@code source} as frozen — subsequent {@link #setSource}
+     * calls throw {@link IllegalStateException}.
+     *
+     * <p>Idempotent: calling on an already-frozen node is a no-op.</p>
+     *
+     * @since FR5a / ADR-0009
+     */
+    public void freezeSource() {
+        this.sourceFrozen = true;
+    }
+
+    /**
+     * Returns whether this node's source is currently frozen.
+     *
+     * @return {@code true} if frozen, {@code false} otherwise
+     * @since FR5a / ADR-0009
+     */
+    public boolean isSourceFrozen() {
+        return sourceFrozen;
+    }
+
     ////////////////////////////////////////////////////
     // ATTRIBUTE METHODS
 

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

@@ -7,6 +7,7 @@
 
 package com.metaobjects;
 
+import com.metaobjects.source.ErrorSource;
 import com.metaobjects.util.MetaDataPath;
 
 import java.time.Instant;
@@ -49,6 +50,17 @@ public class MetaDataException extends RuntimeException {
      */
     private final ErrorCode code;
 
+    /**
+     * FR5a / ADR-0009 — Loader error envelope provenance.
+     *
+     * <p>Populated when the exception is constructed via the envelope-aware
+     * constructor. Loader phases that have a node in scope pass
+     * {@code node.getSource()} here so consumers can report file path + JSONPath
+     * for the offending location. {@code null} when the exception was raised
+     * outside a loader context (legacy / runtime callers).</p>
+     */
+    private final ErrorSource envelope;
+
     /**
      * Creates a MetaDataException with a simple message.
      * Backward compatible constructor.
@@ -121,9 +133,31 @@ public MetaDataException(String message, MetaData source, String operation,
     public MetaDataException(String message, MetaData source, String operation,
                            Throwable cause, Map<String, Object> additionalContext,
                            ErrorCode code) {
+        this(message, source, operation, cause, additionalContext, code, null);
+    }
+
+    /**
+     * FR5a / ADR-0009 — Full internal constructor with the loader error envelope.
+     *
+     * <p>When a loader phase has a node in scope, pass {@code node.getSource()} as
+     * {@code envelope} so consumers can report file path + JSONPath for the
+     * offending location.</p>
+     *
+     * @param message           the error message
+     * @param source            the MetaData object where the error occurred (may be null)
+     * @param operation         the operation being performed when the error occurred (may be null)
+     * @param cause             the underlying cause (may be null)
+     * @param additionalContext additional context information (may be empty)
+     * @param code              the structured {@link ErrorCode}; {@code null} if not applicable
+     * @param envelope          the loader error envelope provenance; {@code null} if not applicable
+     */
+    public MetaDataException(String message, MetaData source, String operation,
+                           Throwable cause, Map<String, Object> additionalContext,
+                           ErrorCode code, ErrorSource envelope) {
         super(buildEnhancedMessage(message, source, operation, additionalContext), cause);
 
         this.code = code;
+        this.envelope = envelope;
         this.metaDataPath = source != null ? MetaDataPath.buildPath(source) : null;
         this.operation = operation;
         this.context = new LinkedHashMap<>(additionalContext != null ? additionalContext : Collections.emptyMap());
@@ -139,6 +173,19 @@ public MetaDataException(String message, MetaData source, String operation,
         }
     }
 
+    /**
+     * FR5a / ADR-0009 — Convenience constructor for loader sites: message + code +
+     * envelope.
+     *
+     * @param message  the error message
+     * @param code     the structured {@link ErrorCode}
+     * @param envelope the loader error envelope provenance; {@code null} permitted
+     *                 but defeats the purpose
+     */
+    public MetaDataException(String message, ErrorCode code, ErrorSource envelope) {
+        this(message, null, null, null, Collections.emptyMap(), code, envelope);
+    }
+
     /**
      * Builds an enhanced error message with context information.
      * 
@@ -191,6 +238,19 @@ public Optional<ErrorCode> getCode() {
         return Optional.ofNullable(code);
     }
 
+    /**
+     * FR5a / ADR-0009 — Returns the loader error envelope provenance, if any.
+     *
+     * <p>{@code Optional.empty()} for exceptions raised outside a loader context
+     * (legacy / runtime callers); a populated value for envelope-aware loader
+     * sites.</p>
+     *
+     * @return Optional containing the {@link ErrorSource} envelope, or empty if none
+     */
+    public Optional<ErrorSource> getEnvelope() {
+        return Optional.ofNullable(envelope);
+    }
+
     /**
      * Returns the hierarchical path to the MetaData object where this error occurred.
      *

server/java/metadata/src/main/java/com/metaobjects/loader/ValidationPhase.java

@@ -186,12 +186,13 @@ private static void validateEnumNode(MetaData node) {
         if (node.hasMetaAttr(EnumField.ATTR_VALUES, false)) {
             MetaAttribute<?> valuesAttr = node.getMetaAttr(EnumField.ATTR_VALUES, false);
             if (!EnumField.validateEnumValues(valuesAttr.getValue())) {
+                // FR5a — envelope carries the offending node's provenance.
                 throw new MetaDataException(
                     ErrorMessageConstants.ERR_BAD_ATTR_VALUE
                         + ": field.enum '" + node.getName()
                         + "' @values must be a non-empty list of identifier-safe, unique members"
                         + " (e.g. [\"DRAFT\",\"PUBLISHED\"])",
-                    ErrorCode.ERR_BAD_ATTR_VALUE);
+                    ErrorCode.ERR_BAD_ATTR_VALUE, node.getSource());
             }
             // Own @values present and valid — required check not needed.
             return;
@@ -200,11 +201,12 @@ private static void validateEnumNode(MetaData node) {
         // --- Required check ---
         // No own @values. Valid only if there is a super reference (inheriting @values).
         if (node.getSuperData() == null) {
+            // FR5a — envelope carries the offending node's provenance.
             throw new MetaDataException(
                 ErrorMessageConstants.ERR_MISSING_REQUIRED_ATTR
                     + ": field.enum '" + node.getName()
                     + "' is missing required @values attribute",
-                ErrorCode.ERR_MISSING_REQUIRED_ATTR);
+                ErrorCode.ERR_MISSING_REQUIRED_ATTR, node.getSource());
         }
         // Has a super — inherits @values from the super, which is validated on its own node.
     }