merge: the loader reads the sidecar and refuses a broken one

The reduction moved the entry union's discriminator into the manifest
sidecar while the loader had no reference to that file, so every
four-field entry failed discrimination on the real load path. A
present-but-unparseable sidecar now raises naming the file rather than
reading as absent, which would send the loader looking for an inline
discriminator and hide the cause behind the same opaque union error.

Author: Simon-McIntosh

imas_standard_names/yaml_store.py

@@ -9,6 +9,7 @@
 import yaml
 
 from .models import (
+    StandardNameCatalogManifest,
     StandardNameEntry,
     StandardNameScalarEntry,
     create_standard_name_entry,
@@ -213,9 +214,45 @@ def __init__(self, root: str | Path, permissive: bool = False):
     def yaml_files(self):
         return sorted(list(self.root.rglob("*.yml")) + list(self.root.rglob("*.yaml")))
 
+    def load_manifest(self) -> StandardNameCatalogManifest | None:
+        """Load the manifest sidecar (``catalog.yml``) beside the entries.
+
+        Checked first at ``root.parent/catalog.yml`` (the standard layout —
+        manifest at repo root, entries under ``standard_names/``), then at
+        ``root/catalog.yml`` (entries under the repo root directly). Returns
+        ``None`` only when no manifest file is present at either location; a
+        present-but-unparseable manifest is refused rather than treated as
+        absent, since silently ignoring it would leave entries without an
+        inline ``kind`` failing discrimination later with an opaque union
+        error that hides the real cause.
+        """
+        candidates = [self.root.parent / "catalog.yml", self.root / "catalog.yml"]
+        for candidate in candidates:
+            if not candidate.exists():
+                continue
+            try:
+                data = yaml.safe_load(candidate.read_text(encoding="utf-8"))
+            except yaml.YAMLError as e:
+                raise ValueError(
+                    f"Catalog manifest sidecar at {candidate} is not valid YAML: {e}"
+                ) from e
+            if not isinstance(data, dict):
+                raise ValueError(
+                    f"Catalog manifest sidecar at {candidate} must be a mapping, "
+                    f"got {type(data).__name__}"
+                )
+            try:
+                return StandardNameCatalogManifest(**data)
+            except Exception as e:
+                raise ValueError(
+                    f"Catalog manifest sidecar at {candidate} failed validation: {e}"
+                ) from e
+        return None
+
     # Load --------------------------------------------------------------------
     def load(self) -> list[StandardNameEntry]:
         models: list[StandardNameEntry] = []
+        manifest = self.load_manifest()
         for f in self.yaml_files():
             # Detect nested paths (legacy per-file layout)
             relative = f.relative_to(self.root)
@@ -269,7 +306,7 @@ def load(self) -> list[StandardNameEntry]:
 
                 # Handle Pydantic validation errors in permissive mode
                 try:
-                    m = create_standard_name_entry(entry_data)
+                    m = create_standard_name_entry(entry_data, manifest=manifest)
                     models.append(m)
                 except Exception as e:
                     if self.permissive:

tests/test_yaml_store.py

@@ -1,6 +1,7 @@
 import importlib.resources as resources
 from pathlib import Path
 
+import pytest
 import yaml
 
 from imas_standard_names.models import create_standard_name_entry
@@ -11,6 +12,18 @@
     write_catalog_yaml,
 )
 
+_MANIFEST_HEADER = """
+catalog_name: test_catalog
+cocos_convention: 11
+grammar_version: "1"
+isn_model_version: "1"
+dd_version_lineage: ["4.0.0"]
+generated_by: test-suite
+generated_at: 2026-01-01T00:00:00Z
+candidate_count: 1
+published_count: 1
+"""
+
 
 def _entry_with_source(source: dict[str, str]) -> dict:
     return {
@@ -264,3 +277,58 @@ def test_existing_catalog_rewrite_preserves_data(tmp_path: Path) -> None:
     ]
 
     assert rewritten_entries == existing
+
+
+def test_load_resolves_kind_from_valid_manifest_sidecar(tmp_path: Path) -> None:
+    entries_root = tmp_path / "standard_names"
+    entries_root.mkdir()
+    (tmp_path / "catalog.yml").write_text(
+        _MANIFEST_HEADER
+        + "names:\n"
+        + "  plasma_current:\n"
+        + "    kind: scalar\n"
+        + "    physics_domain: core_plasma_physics\n"
+    )
+    (entries_root / "plasma_current.yml").write_text(
+        "name: plasma_current\n"
+        "description: Plasma current.\n"
+        "documentation: Total plasma current in the tokamak.\n"
+        "unit: A\n"
+    )
+
+    loaded = {mm.name: mm for mm in YamlStore(entries_root).load()}
+
+    assert loaded["plasma_current"].kind == "scalar"
+
+
+def test_load_refuses_present_but_unparseable_manifest_sidecar(tmp_path: Path) -> None:
+    entries_root = tmp_path / "standard_names"
+    entries_root.mkdir()
+    manifest_path = tmp_path / "catalog.yml"
+    manifest_path.write_text("catalog_name: [unterminated\n")
+    (entries_root / "plasma_current.yml").write_text(
+        "name: plasma_current\n"
+        "kind: scalar\n"
+        "physics_domain: core_plasma_physics\n"
+        "description: Plasma current.\n"
+        "documentation: Total plasma current in the tokamak.\n"
+        "unit: A\n"
+    )
+
+    with pytest.raises(ValueError, match=str(manifest_path)):
+        YamlStore(entries_root).load()
+
+
+def test_load_without_manifest_sidecar_uses_inline_kind(tmp_path: Path) -> None:
+    (tmp_path / "plasma_current.yml").write_text(
+        "name: plasma_current\n"
+        "kind: scalar\n"
+        "physics_domain: core_plasma_physics\n"
+        "description: Plasma current.\n"
+        "documentation: Total plasma current in the tokamak.\n"
+        "unit: A\n"
+    )
+
+    loaded = {mm.name: mm for mm in YamlStore(tmp_path).load()}
+
+    assert loaded["plasma_current"].kind == "scalar"