refactor(sl): split overlay columns from column_overrides and enforce TS/Python wire contract

Overlay sources now have two distinct collections: `columns:` for computed
columns (requiring `expr` + `type`) and `column_overrides:` for metadata
patches to inherited manifest columns. Composing or loading an overlay that
mixes the two — or references an unknown column — fails with a typed error.

Introduce `ResolvedSemanticLayerSource` / `resolvedSourceSchema` /
`toResolvedWire` as the strict shape sent to the Python engine, and add a
schema contract test that diffs Zod against the Pydantic JSON schema dumped
by `python -m semantic_layer dump-schema`. `SourceDefinition` is now
`extra="forbid"` on the Python side.

`loadAllSources` surfaces per-file load errors instead of swallowing them,
so validation/query paths can report manifest shard parse failures.

python/ktx-sl/semantic_layer/__main__.py

@@ -1,3 +1,22 @@
-from semantic_layer.cli import main
+from __future__ import annotations
 
-main()
+import json
+import sys
+
+from semantic_layer.cli import main as cli_main
+from semantic_layer.models import SourceDefinition
+
+
+def dump_schema() -> None:
+    json.dump(
+        SourceDefinition.model_json_schema(), sys.stdout, indent=2, sort_keys=True
+    )
+    sys.stdout.write("\n")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1 and sys.argv[1] in {"dump-schema", "schema"}:
+        sys.argv.pop(1)
+        dump_schema()
+    else:
+        cli_main()

python/ktx-sl/semantic_layer/loader.py

@@ -87,18 +87,23 @@ class SourceLoader:
                 sources[name] = SourceDefinition(**data)
             else:
                 # Overlay — validate and compose with matching manifest entry
-                errors = validate_overlay(data)
-                if errors:
-                    raise ValueError(
-                        f"Invalid overlay '{name}' in {path}: {'; '.join(errors)}"
-                    )
                 base = sources.get(name)
                 if base:
+                    errors = validate_overlay(data, {c.name for c in base.columns})
+                    if errors:
+                        raise ValueError(
+                            f"Invalid overlay '{name}' in {path}: {'; '.join(errors)}"
+                        )
                     (
                         sources[name],
                         description_sources[name],
                     ) = self._compose(base, data, description_sources.get(name))
                 else:
+                    errors = validate_overlay(data)
+                    if errors:
+                        raise ValueError(
+                            f"Invalid overlay '{name}' in {path}: {'; '.join(errors)}"
+                        )
                     logger.warning(
                         "Orphan overlay '%s' in %s: no matching manifest entry, skipping",
                         name,
@@ -149,12 +154,55 @@ class SourceLoader:
                 description_sources or None,
             )
 
-        # Filter columns
+        excluded = set(overlay.get("exclude_columns", []))
+        overrides = overlay.get("column_overrides", [])
+        override_names = {override.get("name") for override in overrides}
+        conflicts = sorted(name for name in override_names if name in excluded)
+        if conflicts:
+            raise ValueError(
+                "column_overrides conflict with exclude_columns: "
+                + ", ".join(conflicts)
+            )
+
+        base_by_name = {column.name: column for column in base.columns}
+
+        for override in overrides:
+            name = override.get("name")
+            base_column = base_by_name.get(name)
+            if base_column is None:
+                raise ValueError(
+                    f"column '{name}' in column_overrides does not exist on manifest source '{base.name}'"
+                )
+
         excluded = set(overlay.get("exclude_columns", []))
         source.columns = [c for c in source.columns if c.name not in excluded]
 
-        # Append computed columns (overlay columns with expr)
+        columns_by_name = {column.name: column for column in source.columns}
+
+        for override in overrides:
+            name = override["name"]
+            base_column = base_by_name[name]
+            merged = base_column.model_dump(mode="python", exclude_none=True)
+            base_descriptions = merged.get("descriptions") or {}
+            override_data = dict(override)
+            override_descriptions = override_data.get("descriptions") or {}
+            merged.update(override_data)
+            if base_descriptions or override_descriptions:
+                merged["descriptions"] = {
+                    **base_descriptions,
+                    **override_descriptions,
+                }
+            columns_by_name[name] = SourceColumn(**merged)
+        source.columns = list(columns_by_name.values())
+
+        # Append computed columns. Manifest column names cannot be reused here;
+        # use column_overrides for metadata patches.
         for col in overlay.get("columns", []):
+            name = col.get("name")
+            if name in base_by_name:
+                raise ValueError(
+                    f"column '{name}' in columns patches a manifest column on '{base.name}' — move it to 'column_overrides:'"
+                )
             source.columns.append(SourceColumn(**col))
 
         # Set measures
@@ -181,6 +229,11 @@ class SourceLoader:
         ]
         source.joins = manifest_joins + new_joins
 
+        if not source.table and not source.sql:
+            raise ValueError("resolved source must have 'table' or 'sql'")
+        if source.table and source.sql:
+            raise ValueError("'table' and 'sql' are mutually exclusive")
+
         return source, (description_sources or None)
 
     def _validate_cross_references(self, sources: dict[str, SourceDefinition]) -> None:

python/ktx-sl/semantic_layer/manifest.py

@@ -143,7 +143,9 @@ class Manifest(BaseModel):
 # ── Projection ──────────────────────────────────────────────────────
 
 
-def validate_overlay(data: dict) -> list[str]:
+def validate_overlay(
+    data: dict, manifest_column_names: set[str] | None = None
+) -> list[str]:
     """Validate that overlay data doesn't contain structural fields.
 
     Returns a list of error messages (empty if valid).
@@ -162,11 +164,26 @@ def validate_overlay(data: dict) -> list[str]:
             errors.append(
                 f"Overlay column '{col.get('name', '?')}' must use 'descriptions'"
             )
-        if "type" in col and "expr" not in col:
+        if "expr" not in col:
             errors.append(
-                f"Overlay column '{col.get('name', '?')}' specifies 'type' without 'expr' "
-                f"(structural types are inherited from manifest — only computed columns may specify a type)"
+                f"Overlay column '{col.get('name', '?')}' in 'columns' must define "
+                f"'expr' and 'type' (use 'column_overrides' to patch manifest columns)"
             )
+        if "type" not in col:
+            errors.append(
+                f"Overlay column '{col.get('name', '?')}' in 'columns' must define "
+                f"'type' and 'expr' (use 'column_overrides' to patch manifest columns)"
+            )
+    for col in data.get("column_overrides", []):
+        name = col.get("name", "?")
+        if "description" in col:
+            errors.append(f"Column override '{name}' must use 'descriptions'")
+        if "type" in col:
+            errors.append(f"Column override '{name}' must not contain 'type'")
+        if "expr" in col:
+            errors.append(f"Column override '{name}' must not contain 'expr'")
+        if manifest_column_names is not None and name not in manifest_column_names:
+            errors.append(f"Column override '{name}' does not match a manifest column")
     return errors
 
 

python/ktx-sl/semantic_layer/models.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from enum import Enum
 from typing import Any, Literal
 
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 
 # ── Source Definition Models ──────────────────────────────────────────
@@ -105,6 +105,8 @@ class DefaultTimeDimensionDbt(BaseModel):
 
 
 class SourceDefinition(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
     name: str
     description: str | None = None
     descriptions: dict[str, str] | None = None
@@ -123,6 +125,8 @@ class SourceDefinition(BaseModel):
     def validate_source(self) -> SourceDefinition:
         if self.description is None:
             self.description = _resolve_description_map(self.descriptions)
+        if not self.table and not self.sql:
+            raise ValueError("resolved source must have 'table' or 'sql'")
         if self.table and self.sql:
             raise ValueError("'table' and 'sql' are mutually exclusive")
         if not self.grain: