Merge worktree-fr5a-python-2026-05-26 — FR5a (loader error envelope + source-on-node) for Python

Per ADR-0009 + FR5a spec
(docs/superpowers/specs/2026-05-25-fr5a-json-shape-loader-errors.md).
Python is the fourth and final port to land FR5a's per-port runtime +
API work. The conformance fixture migration to the
{ errors: [...envelopes], warnings: [...] } shape is now unblocked and
becomes the next cross-port step.

Branch commits:

  c163bae feat(python): FR5a foundation — ErrorSource hierarchy, JsonPath, SemanticDiff
  fd03b22 feat(python): FR5a — thread source through parser + validation + MetaData.source
  78ff0b8 fix(python): pre-merge review — complete FR5a envelope coverage
  2a48841 chore(python): pre-merge simplifier pass — FR5a polish

What FR5a delivers in Python:

- New metaobjects.source package: @DataClass(frozen=True) discriminated
  union (ErrorSource abstract base + JsonSource / YamlSource /
  MergedSource / ResolvedSource / DatabaseSource / CodeSource) +
  Contributor / NodeContext / YamlPosition / DbLocation / LoaderError /
  LoaderWarning. Each variant carries a `format` ClassVar discriminant
  matching TS/C#/Java strings. JsonSource enforces the FR5a length-1
  invariant in __post_init__.
- metaobjects.source.json_path — canonical JSONPath builder matching
  TS + C# + Java byte-for-byte (identifier-safe → dot; otherwise
  single-quoted bracket with `'` escape; `[N]` indices; root `$`).
- metaobjects.source.semantic_diff — both JSON-value and (MetaData,
  MetaData) entry points; lazy MetaData import resolves the
  source ↔ meta_data module cycle.
- MetaData._source attribute (default CodeSource.DEFAULT) with the
  existing _require_mutable() freeze guard reused for set_source.
- MetaError carries an optional envelope: ErrorSource | None alongside
  legacy source / path (conformance adapter only inspects code).
- parser.py threads a JsonPathBuilder through parse_document → _build
  → _parse_attr_child. Every constructed node + every parser-built
  MetaAttribute child (inline @-attrs AND typed attr.* children) gets
  set_source(JsonSource(...)). Every error site passes envelope.
- validation_passes.py — all 29 MetaError sites pass envelope (28
  initially, plus ERR_PROVIDER_ATTR_CONFLICT fixed in the review pass).

Pre-merge gate: code-reviewer flagged the parser-attr source-tagging
gap, a `<inline>` source-id carve-out inconsistent with mid-tree
envelope construction, and one missing-envelope site. All three fixed
in 78ff0b8. Simplifier unquoted two now-redundant string annotations
(with __future__ annotations at the top of both files).

Verification: 496 Python tests green (was 466 baseline, +30 new FR5a
tests for JsonPath edges, SemanticDiff smoke, source-on-node, parser
attr source-tagging). Conformance fixture corpus stays in the OLD
{ "code": "ERR_*" } shape — Python's conformance_adapter continues to
extract code from envelopes for the cross-port assertion.

What stays unchanged:
- Conformance fixtures still in the OLD shape (cross-port artifact);
  fixture rewrite is now the next coordinated step across all 4 ports.
- No new ERR_* codes; existing codes get richer envelopes.

With this merge, FR5a per-port runtime + API work is COMPLETE across
TS / C# / Java / Python. ADR-0009 envelope shape is consistent on the
wire end-to-end.

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

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,41 @@ 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 (`$`). Matches C#
+        # Parser.cs:140 — only fall back to CodeSource when there is no source
+        # id at all; "<inline>" is a valid source identifier and must yield a
+        # JsonSource so envelope formats remain consistent across error sites.
+        envelope: ErrorSource = (
+            JsonSource(files=(src.id,), json_path="$")
+            if src.id
+            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)