feat(java): FR5a foundation — ErrorSource hierarchy, JsonPath, SemanticDiff

Per ADR-0009 / the FR5a cross-port spec, lay down the Java realization of the
loader error-envelope + source-on-node foundation. New classes only — no
modifications yet to the loader/parser/MetaData; commit 2 wires them in.

The sealed-interface hierarchy mirrors the C# closed `abstract record`
hierarchy (`server/csharp/MetaObjects/Source/ErrorSource.cs`):

  ErrorSource (sealed)
    ├── JsonSource(files [size==1], jsonPath)     ← FR5a populates
    ├── YamlSource(files, jsonPath, yamlPosition) ← FR5b slot
    ├── MergedSource(files, jsonPath, contributors) ← FR5c slot
    ├── ResolvedSource(files, jsonPath, referrer, target) ← FR5d slot
    ├── DatabaseSource(dbLocation, jsonPath)      ← FR5e slot
    └── CodeSource(caller)                         ← programmatic default

JsonSource enforces the FR5a length-1 invariant at construction
(throws IllegalArgumentException; points at MergedSource for multi-file)
to match the C# constraint exactly.

CodeSource.DEFAULT is the canonical singleton returned for any node not
built by a loader phase.

JsonPath ships the canonical builder + static one-shot helpers:
  - dot notation for identifier-safe keys
  - bracket-quoted form for everything else (escaping ' as \\')
  - bracket form for array indices
  - root is `$`

SemanticDiff ships the skeleton + tests now even though FR5a doesn't
exercise it — FR5c will consume the boolean for the
WARN_DUPLICATE_DECLARATION path.

LoaderError / LoaderWarning are envelope records ready for adoption when
the loader gains a non-exception error channel (future).

24 new unit tests (14 JsonPath, 10 SemanticDiff) — all green.

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/source/CodeSource.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2003 Doug Mealing LLC dba Meta Objects. All Rights Reserved.
+ *
+ * This software is the proprietary information of Doug Mealing LLC dba Meta Objects.
+ * Use is subject to license terms.
+ */
+package com.metaobjects.source;
+
+/**
+ * Programmatic / test-construction provenance — the default for any node not
+ * built by a loader phase.
+ *
+ * <p>Mirrors {@code CodeSource} in
+ * {@code server/csharp/MetaObjects/Source/ErrorSource.cs}. The
+ * {@link #DEFAULT} singleton is the canonical no-caller instance returned by
+ * {@code MetaData.getSource()} when nothing has been set.</p>
+ *
+ * @param caller optional human label (e.g. {@code "QueriesTest.makePost"});
+ *               may be {@code null}
+ */
+public record CodeSource(String caller) implements ErrorSource {
+
+    /** Canonical singleton for the no-caller case. */
+    public static final CodeSource DEFAULT = new CodeSource(null);
+
+    /** Convenience constructor: no caller label. */
+    public CodeSource() {
+        this(null);
+    }
+
+    @Override
+    public String format() {
+        return "code";
+    }
+}

server/java/metadata/src/main/java/com/metaobjects/source/Contributor.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2003 Doug Mealing LLC dba Meta Objects. All Rights Reserved.
+ *
+ * This software is the proprietary information of Doug Mealing LLC dba Meta Objects.
+ * Use is subject to license terms.
+ */
+package com.metaobjects.source;
+
+/**
+ * One contributor in a {@link MergedSource} (FR5c reserved slot).
+ *
+ * <p>Mirrors {@code Contributor} in
+ * {@code server/csharp/MetaObjects/Source/ErrorSource.cs}.</p>
+ *
+ * @param file project-root-relative path with forward slashes
+ * @param role one of {@code "overlay-base"} / {@code "overlay-extension"} /
+ *             {@code "extends-base"} / {@code "extends-extension"}
+ */
+public record Contributor(String file, String role) {
+}

server/java/metadata/src/main/java/com/metaobjects/source/DatabaseSource.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2003 Doug Mealing LLC dba Meta Objects. All Rights Reserved.
+ *
+ * This software is the proprietary information of Doug Mealing LLC dba Meta Objects.
+ * Use is subject to license terms.
+ */
+package com.metaobjects.source;
+
+/**
+ * Future provenance: database-sourced metadata (FR5e — reserved slot, gated on
+ * FR-003; FR5a does not populate this variant).
+ *
+ * <p>Mirrors {@code DatabaseSource} in
+ * {@code server/csharp/MetaObjects/Source/ErrorSource.cs}.</p>
+ *
+ * @param dbLocation database table + id of the originating row
+ * @param jsonPath optional canonical JSONPath within the row's payload; may be {@code null}
+ */
+public record DatabaseSource(DbLocation dbLocation, String jsonPath) implements ErrorSource {
+
+    /**
+     * Canonical constructor: rejects a null {@code dbLocation}.
+     *
+     * @throws NullPointerException if {@code dbLocation} is {@code null}
+     */
+    public DatabaseSource {
+        if (dbLocation == null) {
+            throw new NullPointerException("DatabaseSource dbLocation must not be null");
+        }
+    }
+
+    /** Convenience constructor: no JSONPath. */
+    public DatabaseSource(DbLocation dbLocation) {
+        this(dbLocation, null);
+    }
+
+    @Override
+    public String format() {
+        return "database";
+    }
+}

server/java/metadata/src/main/java/com/metaobjects/source/DbLocation.java

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2003 Doug Mealing LLC dba Meta Objects. All Rights Reserved.
+ *
+ * This software is the proprietary information of Doug Mealing LLC dba Meta Objects.
+ * Use is subject to license terms.
+ */
+package com.metaobjects.source;
+
+/**
+ * Database location for a node sourced from a row (FR5e reserved slot).
+ *
+ * <p>Mirrors {@code DbLocation} in
+ * {@code server/csharp/MetaObjects/Source/ErrorSource.cs}.</p>
+ *
+ * @param table table name (no schema prefix unless the row is in a non-default schema)
+ * @param id identifier of the originating row (string-form regardless of underlying type)
+ */
+public record DbLocation(String table, String id) {
+}

server/java/metadata/src/main/java/com/metaobjects/source/ErrorSource.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2003 Doug Mealing LLC dba Meta Objects. All Rights Reserved.
+ *
+ * This software is the proprietary information of Doug Mealing LLC dba Meta Objects.
+ * Use is subject to license terms.
+ */
+package com.metaobjects.source;
+
+/**
+ * Provenance envelope for a metadata node or loader error (FR5a / ADR-0009).
+ *
+ * <p>Discriminated union over the provenance variants a metadata node or error
+ * can carry. Cross-port-aligned: every metaobjects port emits the same envelope
+ * shape so a tool consuming errors from multiple language ports can compare
+ * them byte-identically.</p>
+ *
+ * <p>This Java realization uses a {@code sealed interface} with {@code record}
+ * permits, mirroring the C# {@code abstract record} hierarchy
+ * ({@code server/csharp/MetaObjects/Source/ErrorSource.cs}). Pattern-match on
+ * the concrete subtype (e.g. {@code switch (src) { case JsonSource js -> ...; }})
+ * to access variant-specific fields.</p>
+ *
+ * <p>The {@link #format()} method returns the discriminant tag (one of
+ * {@code "json"}, {@code "yaml"}, {@code "merged"}, {@code "resolved"},
+ * {@code "database"}, {@code "code"}).</p>
+ *
+ * @see JsonSource for FR5a authoring-time single-file JSON provenance
+ * @see CodeSource for the programmatic / test-construction default
+ */
+public sealed interface ErrorSource
+    permits JsonSource, YamlSource, MergedSource, ResolvedSource, DatabaseSource, CodeSource {
+
+    /**
+     * The discriminant tag — one of {@code "json"} / {@code "yaml"} /
+     * {@code "merged"} / {@code "resolved"} / {@code "database"} / {@code "code"}.
+     *
+     * @return the canonical format tag for this provenance variant
+     */
+    String format();
+}

server/java/metadata/src/main/java/com/metaobjects/source/JsonPath.java

@@ -0,0 +1,160 @@
+/*
+ * Copyright 2003 Doug Mealing LLC dba Meta Objects. All Rights Reserved.
+ *
+ * This software is the proprietary information of Doug Mealing LLC dba Meta Objects.
+ * Use is subject to license terms.
+ */
+package com.metaobjects.source;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.regex.Pattern;
+
+/**
+ * Canonical JSONPath builder (FR5a / ADR-0009).
+ *
+ * <p>Construction rules — cross-port-aligned; every port emits this canonical
+ * form byte-identically:</p>
+ * <ul>
+ *   <li>Root is {@code $}.</li>
+ *   <li>Object keys matching {@code ^[A-Za-z_][A-Za-z0-9_]*$} use dot notation:
+ *       {@code .foo}.</li>
+ *   <li>All other keys use single-quoted bracket form: {@code ['my-key']},
+ *       {@code ['@attr']}.</li>
+ *   <li>Array indices use bracket form: {@code [N]}.</li>
+ *   <li>Embedded single quotes are escaped as {@code \'}.</li>
+ *   <li>No trailing dots, no whitespace.</li>
+ * </ul>
+ *
+ * <p>Mirrors {@code JsonPathBuilder} in
+ * {@code server/csharp/MetaObjects/Source/JsonPath.cs} and
+ * {@code typescript/packages/metadata/src/json-path.ts}.</p>
+ *
+ * <p>Static one-shot helpers ({@link #segmentForKey(String)},
+ * {@link #segmentForIndex(int)}) cover the cases where a builder is overkill.</p>
+ */
+public final class JsonPath {
+
+    /** Identifier regex for dot-vs-bracket dispatch. Package-private so the builder can share it. */
+    static final Pattern IDENT = Pattern.compile("^[A-Za-z_][A-Za-z0-9_]*$");
+
+    private JsonPath() {
+        // Static-only utility.
+    }
+
+    /**
+     * Render a single object-key segment as it would appear in canonical form,
+     * without the leading {@code $} — i.e. {@code .foo} or {@code ['my-key']}.
+     *
+     * @param key the object key
+     * @return the segment rendering
+     */
+    public static String segmentForKey(String key) {
+        if (IDENT.matcher(key).matches()) {
+            return "." + key;
+        }
+        return "['" + escapeSingleQuotes(key) + "']";
+    }
+
+    /**
+     * Render a single array-index segment: {@code [N]}.
+     *
+     * @param idx the zero-based array index
+     * @return the segment rendering
+     */
+    public static String segmentForIndex(int idx) {
+        return "[" + idx + "]";
+    }
+
+    /**
+     * Escape embedded single quotes in a key for bracket-quoted output.
+     *
+     * <p>The canonical form escapes {@code '} as {@code \'} (mirrors the C# /
+     * TS implementations).</p>
+     */
+    static String escapeSingleQuotes(String s) {
+        if (s.indexOf('\'') < 0) {
+            return s;
+        }
+        return s.replace("'", "\\'");
+    }
+
+    /**
+     * Mutable builder that mirrors the parser's tree-walk: push a key or index
+     * when descending into a child, pop when returning.
+     *
+     * <p>This class is intentionally not {@link Cloneable} — each parse uses
+     * its own builder. Not thread-safe.</p>
+     */
+    public static final class Builder {
+
+        private final List<Segment> segments = new ArrayList<>();
+
+        /** Push an object-key segment (e.g. {@code .foo} or {@code ['my-key']}). */
+        public void pushKey(String key) {
+            segments.add(new Segment(SegmentKind.KEY, key, 0));
+        }
+
+        /** Push an array-index segment (e.g. {@code [2]}). */
+        public void pushIndex(int idx) {
+            segments.add(new Segment(SegmentKind.INDEX, null, idx));
+        }
+
+        /**
+         * Pop the most recently pushed segment.
+         *
+         * <p>No-op when the stack is empty — pop balance is the caller's
+         * responsibility, but a defensive bottom matches the C# behavior so
+         * the builder never throws on imbalanced parse paths.</p>
+         */
+        public void pop() {
+            if (!segments.isEmpty()) {
+                segments.remove(segments.size() - 1);
+            }
+        }
+
+        /** Number of segments currently on the stack (root is segment 0; not counted). */
+        public int depth() {
+            return segments.size();
+        }
+
+        /**
+         * Render the current stack as a canonical JSONPath string.
+         *
+         * @return the canonical form (always starts with {@code $})
+         */
+        @Override
+        public String toString() {
+            // ~8 chars per segment is a reasonable starting cap.
+            StringBuilder sb = new StringBuilder(segments.size() * 8 + 1);
+            sb.append('$');
+            for (Segment seg : segments) {
+                if (seg.kind == SegmentKind.INDEX) {
+                    sb.append('[').append(seg.index).append(']');
+                } else {
+                    String key = seg.key;
+                    if (IDENT.matcher(key).matches()) {
+                        sb.append('.').append(key);
+                    } else {
+                        sb.append("['").append(escapeSingleQuotes(key)).append("']");
+                    }
+                }
+            }
+            return sb.toString();
+        }
+
+        private enum SegmentKind { KEY, INDEX }
+
+        private static final class Segment {
+            final SegmentKind kind;
+            final String key;
+            final int index;
+
+            Segment(SegmentKind kind, String key, int index) {
+                this.kind = kind;
+                this.key = key;
+                this.index = index;
+            }
+        }
+    }
+}

server/java/metadata/src/main/java/com/metaobjects/source/JsonSource.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2003 Doug Mealing LLC dba Meta Objects. All Rights Reserved.
+ *
+ * This software is the proprietary information of Doug Mealing LLC dba Meta Objects.
+ * Use is subject to license terms.
+ */
+package com.metaobjects.source;
+
+import java.util.List;
+
+/**
+ * Authoring-time provenance: a single JSON file (FR5a).
+ *
+ * <p>Mirrors {@code JsonSource} in {@code server/csharp/MetaObjects/Source/ErrorSource.cs}.
+ * FR5a invariant: <strong>exactly one file path</strong> — multi-file provenance
+ * lives on {@link MergedSource} (FR5c). The invariant is enforced at construction
+ * so the type can be trusted by cross-port comparison.</p>
+ *
+ * @param files length-1 file list; project-root-relative path with forward slashes
+ * @param jsonPath canonical JSONPath string for the node within {@code files[0]}
+ */
+public record JsonSource(List<String> files, String jsonPath) implements ErrorSource {
+
+    /**
+     * Canonical constructor: validates the FR5a length-1 invariant and returns
+     * an immutable copy of the input list.
+     *
+     * @throws IllegalArgumentException if {@code files} does not contain exactly one entry
+     * @throws NullPointerException if {@code files} or {@code jsonPath} is {@code null}
+     */
+    public JsonSource {
+        if (files == null) {
+            throw new NullPointerException("JsonSource files must not be null");
+        }
+        if (jsonPath == null) {
+            throw new NullPointerException("JsonSource jsonPath must not be null");
+        }
+        if (files.size() != 1) {
+            throw new IllegalArgumentException(
+                "JsonSource requires exactly one file path; got " + files.size()
+                    + ". Use MergedSource for multi-file provenance.");
+        }
+        // Defensive copy to enforce immutability of the record component.
+        files = List.copyOf(files);
+    }
+
+    @Override
+    public String format() {
+        return "json";
+    }
+}