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

Wires the FR5a foundation (commit c163bae) into the loader pipeline so every
parser-constructed metadata node carries its origin and every error raised
during parse / per-node validation produces an ADR-0009-shaped envelope.

  * `meta/meta_data.py` — new `source` property + `set_source` setter
    (freeze-guarded). Defaults to `CodeSource.DEFAULT` for programmatic /
    test construction, mirroring the C# `MetaData.Source` contract.
  * `errors.py` — `MetaError` gains an `envelope: ErrorSource | None` field
    alongside the legacy `source` / `path` strings (conformance still inspects
    `code` only; the envelope is additive).
  * `parser.py` — threads a `JsonPathBuilder` through the recursion. Pushes
    the wrapper key at root, the `children` key + `[i]` index + child wrapper
    on each descent, and the `@key` for reserved-attr errors. Every node
    created in `_build` calls `set_source(JsonSource(files=(src,), json_path=…))`;
    every error raised mid-parse passes the same envelope via the new
    `_current_envelope` helper. Falls back to `CodeSource.DEFAULT` when the
    source id is missing — matches the C# `ParseState.CurrentSource` fallback
    so the FR5a length-1 invariant on `JsonSource.files` can't be violated.
  * `loader/validation_passes.py` — 29 `MetaError(...)` sites updated to pass
    `envelope=<node>.source` where a node is in scope. `_validate_entity_field_ref`
    and `_validate_via_path` gained a required `origin_node` parameter so
    `@from` / `@of` / `@via` failures attach to the origin node, not just a
    text label.
  * `loader/meta_data_loader.py` — top-level OSError / JSON-decode / YAML
    parse-error sites build a `JsonSource(files=(src.id,), json_path="$")`
    envelope (with `CodeSource` fallback when the source has no real id).
  * `source/error_source.py` — `CodeSource.DEFAULT` declared as a class-level
    `ClassVar["CodeSource"]` so mypy sees the singleton statically.
  * `source/semantic_diff.py` — lazy MetaData import to break the
    meta_data ↔ source module cycle; `bool(...)` cast on the return path for
    strict-mypy compatibility.

The canonical JSON serializer already only emits recognized structural keys,
so `source` is naturally omitted from `canonical_serialize` output — verified
by the new `test_canonical_serializer_omits_source_from_output` test.

Tests: +7 new in `tests/source/test_source_on_node.py` (programmatic default;
freeze guard; parser populates JsonSource on every node with correct
bracket-vs-dot JSONPath segmentation; canonical serializer omits `source`;
parse-error envelope carries the right files+jsonPath; MetaData subclass
inheritance). Conformance baseline unchanged (94/94). Full Python suite:
466 baseline + 28 new FR5a = 494/494 green.

Author: dmealing

server/python/src/metaobjects/errors.py

@@ -2,6 +2,10 @@
 from __future__ import annotations
 
 from enum import Enum
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:  # avoid runtime import cycles
+    from .source import ErrorSource
 
 
 class ErrorCode(str, Enum):
@@ -47,19 +51,28 @@ class ErrorCode(str, Enum):
 
 
 class MetaError:
-    """A loader error. `code` is the conformance-compared value; `message` is human text."""
+    """A loader error. ``code`` is the conformance-compared value; ``message`` is human text.
+
+    FR5a / ADR-0009: ``envelope`` is the structured provenance envelope every
+    cross-language port emits — populated by the parser (JSON tree-walk) and by
+    validation passes that have access to a node's ``source``. Legacy ``source``
+    (the file path) / ``path`` remain for backward-compat (the conformance
+    adapter only inspects ``code``); new sites should pass ``envelope``.
+    """
 
     def __init__(
         self,
         message: str,
         code: ErrorCode = ErrorCode.ERR_UNKNOWN,
         source: str | None = None,
         path: str | None = None,
+        envelope: "Optional[ErrorSource]" = None,
     ) -> None:
         self.message = message
         self.code = code
         self.source = source
         self.path = path
+        self.envelope = envelope
 
     def __repr__(self) -> str:
         return f"MetaError({self.code.name}: {self.message!r})"

server/python/src/metaobjects/loader/meta_data_loader.py

@@ -27,6 +27,7 @@
 from ..provider import Provider, compose_registry
 from ..registry import TypeRegistry
 from ..shared.base_types import SUBTYPE_ROOT, TYPE_METADATA
+from ..source import CodeSource, ErrorSource, JsonSource
 from ..super_resolve import resolve_supers
 from .merge import merge_roots
 from .sources import (
@@ -139,23 +140,38 @@ def _parse_source(
         malformed; the caller appends an error and skips this source from
         the merge set.
         """
+        # FR5a / ADR-0009 — top-level envelope for the source. Until the parser
+        # walk descends, the offending location is the root (`$`).
+        envelope: ErrorSource = (
+            JsonSource(files=(src.id,), json_path="$")
+            if src.id and src.id != "<inline>"
+            else CodeSource.DEFAULT
+        )
+
         try:
             text = src.read()
         except OSError as exc:
-            errors.append(MetaError(str(exc), ErrorCode.ERR_UNKNOWN, src.id))
+            errors.append(MetaError(
+                str(exc), ErrorCode.ERR_UNKNOWN, src.id, envelope=envelope,
+            ))
             return None
 
         match src.format:
             case MetaDataFormat.YAML:
                 try:
                     return parse_yaml(text, self._registry, source=src.id)
                 except ParseError as exc:
-                    errors.append(MetaError(str(exc), exc.code, src.id))
+                    errors.append(MetaError(
+                        str(exc), exc.code, src.id, envelope=envelope,
+                    ))
                     return None
             case MetaDataFormat.JSON:
                 try:
                     doc = json.loads(text)
                 except json.JSONDecodeError as exc:
-                    errors.append(MetaError(str(exc), ErrorCode.ERR_MALFORMED_JSON, src.id))
+                    errors.append(MetaError(
+                        str(exc), ErrorCode.ERR_MALFORMED_JSON, src.id,
+                        envelope=envelope,
+                    ))
                     return None
                 return parse_document(doc, self._registry, source=src.id)

server/python/src/metaobjects/loader/validation_passes.py

@@ -195,6 +195,7 @@ def _validate_attr_schema(
                     MetaError(
                         f"{_node_label(node)} is missing required attribute '@{schema.name}'",
                         ErrorCode.ERR_MISSING_REQUIRED_ATTR,
+                        envelope=node.source,
                     )
                 )
 
@@ -218,6 +219,7 @@ def _validate_attr_schema(
                             f"{_node_label(node)} attribute '@{attr_node.name}' has value "
                             f"{raw_value!r} which does not match expected type '{schema.value_type}'",
                             ErrorCode.ERR_BAD_ATTR_VALUE,
+                            envelope=node.source,
                         )
                     )
                     continue  # type wrong — skip allowed_values check
@@ -231,6 +233,7 @@ def _validate_attr_schema(
                             f"{_node_label(node)} attribute '@{attr_node.name}' has value "
                             f"'{raw_value}' which is not one of the allowed values: {allowed_str}",
                             ErrorCode.ERR_BAD_ATTR_VALUE,
+                            envelope=node.source,
                         )
                     )
 
@@ -277,6 +280,7 @@ def _validate_enum_values(
                 MetaError(
                     f"{label} attribute '@{FIELD_ATTR_VALUES}' must not be empty",
                     ErrorCode.ERR_BAD_ATTR_VALUE,
+                    envelope=node.source,
                 )
             )
             continue  # further checks don't apply to empty list
@@ -289,6 +293,7 @@ def _validate_enum_values(
                         f"{label} attribute '@{FIELD_ATTR_VALUES}' member {member!r} "
                         f"is not a valid identifier (must match {ENUM_MEMBER_PATTERN})",
                         ErrorCode.ERR_BAD_ATTR_VALUE,
+                        envelope=node.source,
                     )
                 )
                 break  # one error per field is sufficient
@@ -299,6 +304,7 @@ def _validate_enum_values(
                 MetaError(
                     f"{label} attribute '@{FIELD_ATTR_VALUES}' contains duplicate members",
                     ErrorCode.ERR_BAD_ATTR_VALUE,
+                    envelope=node.source,
                 )
             )
 
@@ -337,6 +343,7 @@ def _validate_datagrid_sort_fields(
                         f"@defaultSortField='{sort_field}' which is not a field on this object "
                         f"(known fields: {sorted(field_names)})",
                         ErrorCode.ERR_BAD_DEFAULT_SORT_FIELD,
+                        envelope=child.source,
                     )
                 )
 
@@ -415,6 +422,7 @@ def _validate_datagrid_filter_values(
                             f"references field '{field_name}' which is not a filterable field "
                             f"on this object",
                             ErrorCode.ERR_BAD_ATTR_FILTER,
+                            envelope=child.source,
                         )
                     )
                     continue
@@ -434,6 +442,7 @@ def _validate_datagrid_filter_values(
                                 f"uses operator '{op}' on field '{field_name}' which is not "
                                 f"allowed for field subtype '{sub}'",
                                 ErrorCode.ERR_BAD_ATTR_FILTER,
+                                envelope=child.source,
                             )
                         )
 
@@ -480,19 +489,22 @@ def _validate_entity_field_ref(
     context: str,
     object_index: dict[str, MetaObject],
     errors: list[MetaError],
+    origin_node: MetaData,
 ) -> bool:
     """Validate a dotted 'Entity.fieldName' reference.
 
     Appends ERR_INVALID_ORIGIN to *errors* if invalid; returns True if valid.
     *attr_name* is used only for the error message text; *context* identifies the
-    origin node for diagnostic purposes.
+    origin node for diagnostic purposes; *origin_node* carries the provenance
+    envelope attached to any emitted error.
     """
     parts = ref.split(".", 1)
     if len(parts) != 2:
         errors.append(
             MetaError(
                 f"{context} @{attr_name}='{ref}' must be in 'EntityName.fieldName' format",
                 ErrorCode.ERR_INVALID_ORIGIN,
+                envelope=origin_node.source,
             )
         )
         return False
@@ -503,6 +515,7 @@ def _validate_entity_field_ref(
             MetaError(
                 f"{context} @{attr_name}='{ref}' references unknown entity '{entity_name}'",
                 ErrorCode.ERR_INVALID_ORIGIN,
+                envelope=origin_node.source,
             )
         )
         return False
@@ -513,6 +526,7 @@ def _validate_entity_field_ref(
                 f"{context} @{attr_name}='{ref}' references field '{field_name}' which does "
                 f"not exist on entity '{entity_name}' (known fields: {sorted(field_names)})",
                 ErrorCode.ERR_INVALID_ORIGIN,
+                envelope=origin_node.source,
             )
         )
         return False
@@ -524,17 +538,20 @@ def _validate_via_path(
     context: str,
     object_index: dict[str, MetaObject],
     errors: list[MetaError],
+    origin_node: MetaData,
 ) -> bool:
     """Validate a dotted relationship path 'Entity.rel1[.rel2...]'.
 
     Returns True if valid; appends ERR_INVALID_ORIGIN and returns False if not.
+    *origin_node* carries the provenance envelope attached to any emitted error.
     """
     segments = via.split(".")
     if len(segments) < 2:
         errors.append(
             MetaError(
                 f"{context} @via='{via}' must be in 'EntityName.relName[.relName...]' format",
                 ErrorCode.ERR_INVALID_ORIGIN,
+                envelope=origin_node.source,
             )
         )
         return False
@@ -547,6 +564,7 @@ def _validate_via_path(
             MetaError(
                 f"{context} @via='{via}' references unknown entity '{current_name}'",
                 ErrorCode.ERR_INVALID_ORIGIN,
+                envelope=origin_node.source,
             )
         )
         return False
@@ -561,6 +579,7 @@ def _validate_via_path(
                     f"{context} @via='{via}' — entity '{current_entity.name}' has no "
                     f"relationship '{rel_name}' (known relationships: {sorted(rels)})",
                     ErrorCode.ERR_INVALID_ORIGIN,
+                    envelope=origin_node.source,
                 )
             )
             return False
@@ -573,6 +592,7 @@ def _validate_via_path(
                     f"{context} @via='{via}' — relationship '{rel_name}' on entity "
                     f"'{current_entity.name}' has no @objectRef",
                     ErrorCode.ERR_INVALID_ORIGIN,
+                    envelope=origin_node.source,
                 )
             )
             return False
@@ -584,6 +604,7 @@ def _validate_via_path(
                     f"{context} @via='{via}' — relationship '{rel_name}' on entity "
                     f"'{current_entity.name}' references unknown entity '{obj_ref}'",
                     ErrorCode.ERR_INVALID_ORIGIN,
+                    envelope=origin_node.source,
                 )
             )
             return False
@@ -619,15 +640,16 @@ def _validate_origin_paths(
                         MetaError(
                             f"{ctx} is missing required attribute '@{ORIGIN_ATTR_FROM}'",
                             ErrorCode.ERR_INVALID_ORIGIN,
+                            envelope=origin.source,
                         )
                     )
                 else:
                     _validate_entity_field_ref(
-                        from_ref, ORIGIN_ATTR_FROM, ctx, object_index, errors
+                        from_ref, ORIGIN_ATTR_FROM, ctx, object_index, errors, origin,
                     )
                 via = origin.attr(ORIGIN_ATTR_VIA)
                 if isinstance(via, str) and via:
-                    _validate_via_path(via, ctx, object_index, errors)
+                    _validate_via_path(via, ctx, object_index, errors, origin)
 
             elif origin.sub_type == ORIGIN_SUBTYPE_AGGREGATE:
                 of_ref = origin.attr(ORIGIN_ATTR_OF)
@@ -636,22 +658,24 @@ def _validate_origin_paths(
                         MetaError(
                             f"{ctx} is missing required attribute '@{ORIGIN_ATTR_OF}'",
                             ErrorCode.ERR_INVALID_ORIGIN,
+                            envelope=origin.source,
                         )
                     )
                 else:
                     _validate_entity_field_ref(
-                        of_ref, ORIGIN_ATTR_OF, ctx, object_index, errors
+                        of_ref, ORIGIN_ATTR_OF, ctx, object_index, errors, origin,
                     )
                 via = origin.attr(ORIGIN_ATTR_VIA)
                 if not isinstance(via, str) or not via:
                     errors.append(
                         MetaError(
                             f"{ctx} is missing required attribute '@{ORIGIN_ATTR_VIA}'",
                             ErrorCode.ERR_INVALID_ORIGIN,
+                            envelope=origin.source,
                         )
                     )
                 else:
-                    _validate_via_path(via, ctx, object_index, errors)
+                    _validate_via_path(via, ctx, object_index, errors, origin)
 
 
 # ---------------------------------------------------------------------------
@@ -691,6 +715,7 @@ def _validate_one_primary_source(
                     f"{_node_label(node)} declares {len(sources)} source(s) but "
                     f"none has role '{SOURCE_ROLE_PRIMARY}'",
                     ErrorCode.ERR_SOURCE_NO_PRIMARY,
+                    envelope=node.source,
                 )
             )
         elif primary_count > 1:
@@ -699,6 +724,7 @@ def _validate_one_primary_source(
                     f"{_node_label(node)} declares {primary_count} sources with "
                     f"role '{SOURCE_ROLE_PRIMARY}'; exactly one is required",
                     ErrorCode.ERR_SOURCE_MULTIPLE_PRIMARY,
+                    envelope=node.source,
                 )
             )
 
@@ -736,6 +762,7 @@ def _validate_subtype_rules(
                     MetaError(
                         f"{_node_label(node)} is a value object but declares a primary identity",
                         ErrorCode.ERR_SUBTYPE_RULE_VIOLATION,
+                        envelope=node.source,
                     )
                 )
 
@@ -812,6 +839,7 @@ def _validate_field_object_storage(root: MetaData, errors: list[MetaError]) -> N
                     f"field.object '{node.name}' has @storage but no @objectRef — "
                     f"@storage shape only applies to referenced objects"
                 ),
+                envelope=node.source,
             ))
             continue
         if storage == "flattened" and getattr(node, "is_array", False):
@@ -821,6 +849,7 @@ def _validate_field_object_storage(root: MetaData, errors: list[MetaError]) -> N
                     f"field.object '{node.name}' @storage=\"flattened\" cannot be combined "
                     f"with isArray=true (use @storage=\"jsonb\" for owned-array storage)"
                 ),
+                envelope=node.source,
             ))
 
 
@@ -853,6 +882,7 @@ def _validate_templates(root: MetaData, errors: list[MetaError]) -> None:
             errors.append(MetaError(
                 code=ErrorCode.ERR_MISSING_REQUIRED_ATTR,
                 message=f"template.prompt '{tpl.name}' is missing required @payloadRef",
+                envelope=tpl.source,
             ))
             continue
 
@@ -868,6 +898,7 @@ def _validate_templates(root: MetaData, errors: list[MetaError]) -> None:
                     f"template '{tpl.name}' @payloadRef '{payload_ref}' "
                     f"does not resolve to an object.value at root"
                 ),
+                envelope=tpl.source,
             ))
             continue
 
@@ -885,6 +916,7 @@ def _validate_templates(root: MetaData, errors: list[MetaError]) -> None:
                                 f"template.prompt '{tpl.name}' @requiredSlots includes '{slot}' "
                                 f"which is not a field on payload '{payload_ref}'"
                             ),
+                            envelope=tpl.source,
                         ))