feat(yaml): the loader reads the sidecar and refuses a broken one

The reduction moved kind, the entry union's discriminator, into the
manifest sidecar, and the loader had no reference to that file at all,
so every four-field entry failed discrimination on the real load path.
The store now reads the manifest beside the entries and merges each
name's derived fields before the union discriminates.

A present-but-unparseable manifest raises naming the file rather than
being treated as absent: returning nothing there sends the loader
looking for an inline discriminator and hides the real cause behind
the same opaque union error.

Recovered from a worker that died with the work uncommitted.

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"