feat(python): add MetaDataSource ABC + FileSource/DirectorySource/UriSource/InMemoryStringSource

Introduces the polymorphic MetaDataSource contract from the
cross-language loader-unification spec: identity, declared format, and
read() returning decoded UTF-8 text. Four concrete impls land in a new
`metaobjects.loader.sources` package — FileSource (extension-derived
format, BOM-tolerant), DirectorySource (recursive by default, sorted +
exclude-filtered), UriSource (file:// + http(s)://), and
InMemoryStringSource (no I/O; default id "<inline>").

The new loader API (MetaDataLoader class) follows in the next commit;
this commit purely lands the source abstractions + tests.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: dmealing

server/python/src/metaobjects/loader/sources/__init__.py

@@ -0,0 +1,24 @@
+"""Polymorphic MetaDataSource implementations.
+
+The cross-language Tier-1 contract: every source declares an identity (for
+error locations), a format (json | yaml), and a read() returning the decoded
+text content. File / directory / URI / in-memory sources are all just
+implementations of that contract — the loader is source-agnostic.
+
+See `docs/superpowers/specs/2026-05-25-cross-language-loader-architecture-unification.md`.
+"""
+from __future__ import annotations
+
+from .directory_source import DirectorySource
+from .file_source import FileSource
+from .meta_data_source import InMemoryStringSource, MetaDataFormat, MetaDataSource
+from .uri_source import UriSource
+
+__all__ = [
+    "MetaDataFormat",
+    "MetaDataSource",
+    "InMemoryStringSource",
+    "FileSource",
+    "DirectorySource",
+    "UriSource",
+]

server/python/src/metaobjects/loader/sources/directory_source.py

@@ -0,0 +1,51 @@
+"""Directory expander -> sorted list of FileSource.
+
+Walks the directory (recursively by default), filters to supported authoring
+extensions (``.json`` / ``.yaml`` / ``.yml``), honors a name-based exclude
+list, and yields FileSource instances in deterministic ordinal-filename
+order. Deterministic order is required because overlay merging is
+order-sensitive (last-writer-wins on attr conflicts).
+"""
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from pathlib import Path
+
+from .file_source import FileSource
+
+_SUPPORTED_SUFFIXES = (".json", ".yaml", ".yml")
+
+
+class DirectorySource:
+    """Expands a directory into a sorted, filtered list of FileSource objects."""
+
+    def __init__(
+        self,
+        directory: Path | str,
+        exclude: Iterable[str] | None = None,
+        recurse: bool = True,
+    ) -> None:
+        self._directory = Path(directory)
+        self._exclude = set(exclude or ())
+        self._recurse = recurse
+
+    @property
+    def directory(self) -> Path:
+        return self._directory
+
+    def expand(self) -> Iterator[FileSource]:
+        if self._recurse:
+            candidates: Iterable[Path] = self._directory.rglob("*")
+        else:
+            candidates = self._directory.iterdir()
+
+        files = [
+            p
+            for p in candidates
+            if p.is_file()
+            and p.suffix.lower() in _SUPPORTED_SUFFIXES
+            and p.name not in self._exclude
+        ]
+        files.sort(key=lambda p: p.name)
+        for p in files:
+            yield FileSource(p)

server/python/src/metaobjects/loader/sources/file_source.py

@@ -0,0 +1,41 @@
+"""Single-file MetaDataSource.
+
+Format defaults to extension-derived (``.yaml`` / ``.yml`` -> YAML; otherwise
+JSON). Reads with ``utf-8-sig`` so a leading UTF-8 BOM is silently stripped —
+matches the prior `load_directory` behavior.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .meta_data_source import MetaDataFormat, MetaDataSource
+
+
+def _infer_format(path: Path) -> MetaDataFormat:
+    suffix = path.suffix.lower()
+    if suffix in (".yaml", ".yml"):
+        return MetaDataFormat.YAML
+    return MetaDataFormat.JSON
+
+
+class FileSource(MetaDataSource):
+    """A single on-disk file, decoded eagerly via ``utf-8-sig``."""
+
+    def __init__(self, path: Path | str, format: MetaDataFormat | None = None) -> None:
+        self._path = Path(path)
+        self._format = format if format is not None else _infer_format(self._path)
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    @property
+    def id(self) -> str:
+        return self._path.name
+
+    @property
+    def format(self) -> MetaDataFormat:
+        return self._format
+
+    def read(self) -> str:
+        return self._path.read_text(encoding="utf-8-sig")

server/python/src/metaobjects/loader/sources/meta_data_source.py

@@ -0,0 +1,67 @@
+"""MetaDataSource abstract base + InMemoryStringSource impl.
+
+Tier-1 contract: identity (for MetaError.location), declared format, and a
+read() that returns decoded UTF-8 content.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from enum import Enum
+
+
+class MetaDataFormat(str, Enum):
+    """Authoring format vocabulary. Cross-language Tier 1: lowercase strings."""
+
+    JSON = "json"
+    YAML = "yaml"
+
+
+class MetaDataSource(ABC):
+    """A source of metadata content.
+
+    Implementations declare identity + format up front; bytes may be read
+    eagerly or lazily (the loader treats `read()` as decoded text).
+    """
+
+    @property
+    @abstractmethod
+    def id(self) -> str:
+        """Stable identity used in MetaError.location (e.g. file name, URI, ``<inline>``)."""
+
+    @property
+    @abstractmethod
+    def format(self) -> MetaDataFormat:
+        """Declared authoring format. Source-declared, never sniffed by the loader."""
+
+    @abstractmethod
+    def read(self) -> str:
+        """Return the decoded text content."""
+
+
+class InMemoryStringSource(MetaDataSource):
+    """In-memory string source; no I/O.
+
+    Default identity is ``<inline>``; callers may pass a more descriptive id
+    (e.g. ``<test:foo>``) — it surfaces in MetaError.location.
+    """
+
+    def __init__(
+        self,
+        content: str,
+        id: str = "<inline>",
+        format: MetaDataFormat = MetaDataFormat.JSON,
+    ) -> None:
+        self._content = content
+        self._id = id
+        self._format = format
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    @property
+    def format(self) -> MetaDataFormat:
+        return self._format
+
+    def read(self) -> str:
+        return self._content

server/python/src/metaobjects/loader/sources/uri_source.py

@@ -0,0 +1,48 @@
+"""URI-backed MetaDataSource.
+
+Supports ``file://``, ``http://``, and ``https://`` schemes. Format defaults to
+extension-derived from the URI path; callers may override.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from urllib.parse import urlparse
+from urllib.request import urlopen
+
+from .meta_data_source import MetaDataFormat, MetaDataSource
+
+
+def _infer_format(uri: str) -> MetaDataFormat:
+    path = urlparse(uri).path
+    suffix = Path(path).suffix.lower()
+    if suffix in (".yaml", ".yml"):
+        return MetaDataFormat.YAML
+    return MetaDataFormat.JSON
+
+
+class UriSource(MetaDataSource):
+    """A URI-backed source. Lazily fetched on ``read()``."""
+
+    def __init__(self, uri: str, format: MetaDataFormat | None = None) -> None:
+        self._uri = uri
+        self._format = format if format is not None else _infer_format(uri)
+
+    @property
+    def id(self) -> str:
+        return self._uri
+
+    @property
+    def format(self) -> MetaDataFormat:
+        return self._format
+
+    def read(self) -> str:
+        parsed = urlparse(self._uri)
+        if parsed.scheme == "file":
+            # urlparse splits the leading slashes off the path on file:// URIs.
+            return Path(parsed.path).read_text(encoding="utf-8-sig")
+        if parsed.scheme in ("http", "https"):
+            with urlopen(self._uri) as resp:  # noqa: S310 — caller-supplied URI
+                return resp.read().decode("utf-8")
+        raise ValueError(
+            f"UriSource: unsupported scheme '{parsed.scheme}' on {self._uri}"
+        )

server/python/tests/unit/test_sources.py

@@ -0,0 +1,110 @@
+"""Unit tests for MetaDataSource implementations.
+
+Mirrors the Tier-1 source contract from the cross-language loader-unification
+spec: identity / format / read().
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from metaobjects.loader.sources import (
+    DirectorySource,
+    FileSource,
+    InMemoryStringSource,
+    MetaDataFormat,
+    UriSource,
+)
+
+
+def test_file_source_infers_format_from_extension(tmp_path: Path) -> None:
+    p = tmp_path / "x.yaml"
+    p.write_text("k: v", encoding="utf-8")
+    src = FileSource(p)
+    assert src.format == MetaDataFormat.YAML
+    assert src.id == "x.yaml"
+    assert src.read() == "k: v"
+
+
+def test_file_source_explicit_format_overrides(tmp_path: Path) -> None:
+    p = tmp_path / "x.txt"
+    p.write_text("k: v", encoding="utf-8")
+    src = FileSource(p, format=MetaDataFormat.YAML)
+    assert src.format == MetaDataFormat.YAML
+
+
+def test_file_source_defaults_to_json_for_unknown_extension(tmp_path: Path) -> None:
+    p = tmp_path / "x.txt"
+    p.write_text("{}", encoding="utf-8")
+    assert FileSource(p).format == MetaDataFormat.JSON
+
+
+def test_file_source_strips_utf8_bom(tmp_path: Path) -> None:
+    p = tmp_path / "bom.json"
+    # Write BOM + body; utf-8-sig decoder must strip it.
+    p.write_bytes(b"\xef\xbb\xbf{}")
+    assert FileSource(p).read() == "{}"
+
+
+def test_in_memory_string_source_defaults() -> None:
+    src = InMemoryStringSource("{}")
+    assert src.id == "<inline>"
+    assert src.format == MetaDataFormat.JSON
+    assert src.read() == "{}"
+
+
+def test_in_memory_string_source_custom_identity_and_format() -> None:
+    src = InMemoryStringSource("k: v", id="<test>", format=MetaDataFormat.YAML)
+    assert src.id == "<test>"
+    assert src.format == MetaDataFormat.YAML
+
+
+def test_directory_source_expand_sorted_filtered(tmp_path: Path) -> None:
+    (tmp_path / "b.json").write_text("{}", encoding="utf-8")
+    (tmp_path / "a.yaml").write_text("", encoding="utf-8")
+    (tmp_path / "ignored.txt").write_text("x", encoding="utf-8")
+    expanded = list(DirectorySource(tmp_path).expand())
+    assert [s.id for s in expanded] == ["a.yaml", "b.json"]
+    assert expanded[0].format == MetaDataFormat.YAML
+    assert expanded[1].format == MetaDataFormat.JSON
+
+
+def test_directory_source_honors_exclude(tmp_path: Path) -> None:
+    (tmp_path / "meta.alpha.json").write_text("{}", encoding="utf-8")
+    (tmp_path / "meta.beta.json").write_text("{}", encoding="utf-8")
+    src = DirectorySource(tmp_path, exclude=["meta.beta.json"])
+    expanded = list(src.expand())
+    assert [s.id for s in expanded] == ["meta.alpha.json"]
+
+
+def test_directory_source_recurses_by_default(tmp_path: Path) -> None:
+    sub = tmp_path / "nested"
+    sub.mkdir()
+    (sub / "deep.json").write_text("{}", encoding="utf-8")
+    (tmp_path / "top.json").write_text("{}", encoding="utf-8")
+    ids = [s.id for s in DirectorySource(tmp_path).expand()]
+    # Sorted by file name; both files surfaced.
+    assert ids == ["deep.json", "top.json"]
+
+
+def test_directory_source_non_recursive(tmp_path: Path) -> None:
+    sub = tmp_path / "nested"
+    sub.mkdir()
+    (sub / "deep.json").write_text("{}", encoding="utf-8")
+    (tmp_path / "top.json").write_text("{}", encoding="utf-8")
+    ids = [s.id for s in DirectorySource(tmp_path, recurse=False).expand()]
+    assert ids == ["top.json"]
+
+
+def test_uri_source_file_scheme_reads_content(tmp_path: Path) -> None:
+    p = tmp_path / "x.json"
+    p.write_text("{}", encoding="utf-8")
+    src = UriSource(p.as_uri())
+    assert src.format == MetaDataFormat.JSON
+    assert src.read() == "{}"
+
+
+def test_uri_source_format_inferred_from_path(tmp_path: Path) -> None:
+    p = tmp_path / "x.yaml"
+    p.write_text("k: v", encoding="utf-8")
+    src = UriSource(p.as_uri())
+    assert src.format == MetaDataFormat.YAML