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

Mirrors the TS + C# FR5a foundation (per ADR-0009): a new
`metaobjects.source` module ships the cross-port-aligned error envelope
types, the canonical JSONPath builder, and the SemanticDiff skeleton that
FR5c will consume for duplicate-with-no-change detection.

  * `error_source.py` — `@dataclass(frozen=True)` discriminated union:
    `ErrorSource` (abstract base) + `JsonSource` / `YamlSource` /
    `MergedSource` / `ResolvedSource` / `DatabaseSource` / `CodeSource`.
    Supporting types: `Contributor`, `NodeContext`, `YamlPosition`,
    `DbLocation`, `LoaderError`, `LoaderWarning`. `JsonSource.__post_init__`
    enforces the FR5a length-1 invariant — multi-file provenance is
    `MergedSource` (FR5c) territory.
  * `json_path.py` — `JsonPathBuilder` (push_key / push_index / pop) +
    `JsonPath.segment_for_key` / `segment_for_index`. Identifier-safe keys
    use dot notation; everything else (including `@`-prefixed attrs and
    fused-key wrappers like `object.entity`) uses single-quoted bracket
    form with `'` escaped to `\\'`. Matches the C# / TS canonical regex
    `^[A-Za-z_][A-Za-z0-9_]*$` byte-identically.
  * `semantic_diff.py` — `semantic_diff(a, b) -> bool` over MetaData (via
    canonical_serialize) or raw JSON values; key-order independent for
    objects, ordered for arrays, `source` excluded. Skeleton ships now;
    FR5c consumes it.

Tests: +21 new (13 JsonPath edge cases mirroring the C# fixture; 8
SemanticDiff smoke cases including identical-tree and divergent-tree
MetaData diffs).

Author: dmealing

server/python/src/metaobjects/source/__init__.py

@@ -0,0 +1,57 @@
+"""FR5a / ADR-0009 — Loader error envelope + source-on-node.
+
+Cross-port-aligned types: every metaobjects port emits the same envelope shape
+so a tool consuming errors from multiple language ports can compare them
+byte-identically.
+
+Public surface re-exported here:
+    * ErrorSource hierarchy (abstract base + 6 variants).
+    * JsonPathBuilder + JsonPath helpers (canonical JSONPath construction).
+    * LoaderError / LoaderWarning / NodeContext / Contributor envelope types.
+    * semantic_diff(a, b) for FR5c overlay-merge consumption.
+
+See `docs/superpowers/specs/2026-05-25-fr5a-json-shape-loader-errors.md` and
+`spec/decisions/ADR-0009-loader-error-envelope-and-source-on-node.md`.
+"""
+from __future__ import annotations
+
+from .error_source import (
+    CodeSource,
+    Contributor,
+    DatabaseSource,
+    DbLocation,
+    ErrorSource,
+    JsonSource,
+    LoaderError,
+    LoaderWarning,
+    MergedSource,
+    NodeContext,
+    ResolvedSource,
+    YamlPosition,
+    YamlSource,
+)
+from .json_path import JsonPath, JsonPathBuilder
+from .semantic_diff import semantic_diff
+
+__all__ = [
+    # ErrorSource hierarchy
+    "ErrorSource",
+    "JsonSource",
+    "YamlSource",
+    "MergedSource",
+    "ResolvedSource",
+    "DatabaseSource",
+    "CodeSource",
+    # Supporting types
+    "Contributor",
+    "DbLocation",
+    "NodeContext",
+    "YamlPosition",
+    "LoaderError",
+    "LoaderWarning",
+    # JSONPath
+    "JsonPathBuilder",
+    "JsonPath",
+    # Semantic diff
+    "semantic_diff",
+]

server/python/src/metaobjects/source/error_source.py

@@ -0,0 +1,207 @@
+"""FR5a / ADR-0009 — ErrorSource discriminated union + envelope types.
+
+Closed hierarchy over the provenance variants a metadata node or error can
+carry. The cross-port realization in Python uses ``@dataclass(frozen=True)`` so
+each variant is value-equal, hashable, and immutable.
+
+Pattern-match on the concrete subtype (``isinstance(src, JsonSource)``) to
+access variant-specific fields, or read ``src.format`` for the discriminant
+tag.
+
+Mirrors:
+    * TS  — `server/typescript/packages/metadata/src/source.ts`
+    * C#  — `server/csharp/MetaObjects/Source/ErrorSource.cs`
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import ClassVar, Optional
+
+
+# ---------------------------------------------------------------------------
+# Discriminated union: ErrorSource hierarchy
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ErrorSource:
+    """Provenance envelope for a metadata node or loader error.
+
+    Abstract base — never instantiated directly. Every concrete variant
+    declares a class-level ``format`` constant that names its discriminant tag
+    in the cross-port wire shape.
+    """
+
+    # Subclasses override this class-level constant. Declared here as a
+    # placeholder so static type-checkers see a string attribute on the base.
+    format: ClassVar[str] = ""
+
+
+@dataclass(frozen=True)
+class JsonSource(ErrorSource):
+    """Authoring-time: single JSON file (FR5a).
+
+    Args:
+        files: Length-1 tuple of project-root-relative file paths. The FR5a
+            invariant guarantees exactly one file — multi-file provenance lives
+            on :class:`MergedSource` (FR5c). Enforced at construction.
+        json_path: Canonical JSONPath string for the node within ``files[0]``.
+    """
+
+    files: tuple[str, ...]
+    json_path: str
+    format: ClassVar[str] = "json"
+
+    def __post_init__(self) -> None:
+        # FR5a invariant: exactly one file. Multi-file provenance is
+        # MergedSource (FR5c) territory; enforce here so the type can be
+        # trusted by cross-port comparison.
+        if len(self.files) != 1:
+            raise ValueError(
+                f"JsonSource requires exactly one file path; got {len(self.files)}. "
+                "Use MergedSource for multi-file provenance."
+            )
+
+
+@dataclass(frozen=True)
+class YamlPosition:
+    """Optional YAML line/col source position (FR5b). 1-based."""
+
+    line: int
+    col: int
+
+
+@dataclass(frozen=True)
+class YamlSource(ErrorSource):
+    """Authoring-time: single YAML file with optional source-map positions (FR5b)."""
+
+    files: tuple[str, ...]
+    json_path: str
+    yaml_position: Optional[YamlPosition] = None
+    format: ClassVar[str] = "yaml"
+
+
+@dataclass(frozen=True)
+class Contributor:
+    """One contributor in a :class:`MergedSource`.
+
+    Args:
+        file: Path to the contributing file (project-root relative; forward slashes).
+        role: One of ``"overlay-base"``, ``"overlay-extension"``,
+            ``"extends-base"``, ``"extends-extension"``.
+    """
+
+    file: str
+    role: str
+
+
+@dataclass(frozen=True)
+class MergedSource(ErrorSource):
+    """Post-load: overlay merge that produced semantic change (FR5c)."""
+
+    files: tuple[str, ...]
+    json_path: str
+    contributors: tuple[Contributor, ...]
+    format: ClassVar[str] = "merged"
+
+
+@dataclass(frozen=True)
+class ResolvedSource(ErrorSource):
+    """Post-load: extends / @via / @objectRef / @payloadRef resolution failure (FR5d)."""
+
+    files: tuple[str, ...]
+    json_path: Optional[str] = None
+    referrer: Optional[str] = None
+    target: Optional[str] = None
+    format: ClassVar[str] = "resolved"
+
+
+@dataclass(frozen=True)
+class DbLocation:
+    """Database location for a node sourced from a row."""
+
+    table: str
+    id: str
+
+
+@dataclass(frozen=True)
+class DatabaseSource(ErrorSource):
+    """Future: database-sourced metadata (FR5e, gated on FR-003)."""
+
+    db_location: DbLocation
+    json_path: Optional[str] = None
+    format: ClassVar[str] = "database"
+
+
+@dataclass(frozen=True)
+class CodeSource(ErrorSource):
+    """Programmatic / test construction.
+
+    The default for any node not built by a loader phase. Mirrors TS
+    ``codeSource(caller?)``.
+
+    Args:
+        caller: Optional human label (e.g. ``"QueriesTest.makePost"``).
+    """
+
+    caller: Optional[str] = None
+    format: ClassVar[str] = "code"
+
+
+# Canonical singleton for the no-caller case. Frozen dataclasses are
+# hash-equal across instances, but a single shared default makes intent
+# explicit and matches the C# `CodeSource.Default` convention.
+CodeSource.DEFAULT = CodeSource(caller=None)  # type: ignore[attr-defined]
+
+
+# ---------------------------------------------------------------------------
+# Envelope types: error / warning structures
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class NodeContext:
+    """Optional structural context attached to a loader error.
+
+    RECOMMENDED per ADR-0009; conformance does not enforce population.
+    """
+
+    type: Optional[str] = None
+    sub_type: Optional[str] = None
+    name: Optional[str] = None
+    fqn: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class LoaderError:
+    """Envelope shape every loader error conforms to. ADR-0009 §Decision.
+
+    ``code``, ``message`` and ``source`` are REQUIRED (conformance-enforced).
+    The remaining fields are RECOMMENDED; FR5a does not populate them, FR5b–FR5e
+    may.
+    """
+
+    code: str
+    message: str
+    source: ErrorSource
+    suggestions: tuple[str, ...] = field(default_factory=tuple)
+    fixture: Optional[str] = None
+    node: Optional[NodeContext] = None
+
+
+@dataclass(frozen=True)
+class LoaderWarning:
+    """Warning envelope — same shape as :class:`LoaderError` but a ``WARN_*`` code.
+
+    Today's only initial warning code is ``WARN_DUPLICATE_DECLARATION``
+    (emitted by overlay-merge when a duplicate-with-no-change is detected;
+    FR5c will produce these). FR5a does not raise warnings via this channel —
+    legacy ``warnings: list[str]`` continues to flow through the loader.
+    """
+
+    code: str
+    message: str
+    source: ErrorSource
+    suggestions: tuple[str, ...] = field(default_factory=tuple)
+    fixture: Optional[str] = None
+    node: Optional[NodeContext] = None

server/python/src/metaobjects/source/json_path.py

@@ -0,0 +1,106 @@
+"""FR5a / ADR-0009 — Canonical JSONPath builder.
+
+Construction rules (cross-port-aligned; every port emits this canonical form
+byte-identically):
+    * Root is ``$``.
+    * Object keys matching ``^[A-Za-z_][A-Za-z0-9_]*$`` use dot notation: ``.foo``.
+    * All other keys use single-quoted bracket form: ``['my-key']``,
+      ``['@attr']``. Embedded single quotes are escaped with ``\\'``.
+    * Array indices use bracket form: ``[N]`` (zero-based).
+    * No trailing dots, no whitespace.
+
+Mirrors:
+    * TS  — `server/typescript/packages/metadata/src/json-path.ts`
+    * C#  — `server/csharp/MetaObjects/Source/JsonPath.cs`
+"""
+from __future__ import annotations
+
+import re
+from typing import Optional, Union
+
+# Identifier regex shared with the static :class:`JsonPath` helpers. Compiled
+# once at module load.
+_IDENT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def _render_key_segment(key: str) -> str:
+    """Render a single object-key segment: dot notation if identifier-safe, else bracket form."""
+    if _IDENT_RE.match(key):
+        return f".{key}"
+    escaped = key.replace("'", "\\'")
+    return f"['{escaped}']"
+
+
+def _render_index_segment(idx: int) -> str:
+    """Render a single array-index segment: ``[N]``."""
+    return f"[{idx}]"
+
+
+class JsonPathBuilder:
+    """Builds the canonical JSONPath string for a node as the parser walks the
+    JSON tree. Push a key or index when descending; pop when returning.
+
+    Mirrors ``JsonPathBuilder`` in
+    ``typescript/packages/metadata/src/json-path.ts`` and the C# implementation.
+    """
+
+    __slots__ = ("_segments",)
+
+    def __init__(self) -> None:
+        # Each segment is (kind, payload): kind is "key" or "index".
+        self._segments: list[tuple[str, Union[str, int]]] = []
+
+    def push_key(self, key: str) -> None:
+        """Push an object key segment (e.g. ``.foo`` or ``['my-key']``)."""
+        self._segments.append(("key", key))
+
+    def push_index(self, idx: int) -> None:
+        """Push an array-index segment (e.g. ``[2]``)."""
+        self._segments.append(("index", idx))
+
+    def pop(self) -> None:
+        """Pop the most recently pushed segment."""
+        if self._segments:
+            self._segments.pop()
+
+    @property
+    def depth(self) -> int:
+        """Number of segments currently on the stack (root is segment 0; not counted)."""
+        return len(self._segments)
+
+    def to_string(self) -> str:
+        """Render the current stack as a canonical JSONPath string."""
+        parts: list[str] = ["$"]
+        for kind, payload in self._segments:
+            if kind == "index":
+                # mypy-friendly: cast not needed; assignment ensures int.
+                parts.append(_render_index_segment(int(payload)))
+            else:
+                parts.append(_render_key_segment(str(payload)))
+        return "".join(parts)
+
+    def __str__(self) -> str:  # pragma: no cover — convenience
+        return self.to_string()
+
+
+class JsonPath:
+    """Static helpers for one-shot JSONPath rendering when a builder is overkill.
+
+    Equivalent to the C# ``JsonPath`` static helpers; namespaced as a class so
+    the call sites read identically in Python (``JsonPath.segment_for_key(...)``).
+    """
+
+    @staticmethod
+    def segment_for_key(key: str) -> str:
+        """Render a single object-key segment as it would appear in canonical
+        form, without the leading ``$`` — i.e. ``.foo`` or ``['my-key']``.
+        """
+        return _render_key_segment(key)
+
+    @staticmethod
+    def segment_for_index(idx: int) -> str:
+        """Render a single array-index segment: ``[N]``."""
+        return _render_index_segment(idx)
+
+
+__all__ = ["JsonPath", "JsonPathBuilder"]