hx-9ed0389d migrate authoring consumers to ExpectationSuite

Governed by docs/helix/02-design/adr/ADR-005-unified-expectation-model.md.

Verification: uv run pytest -q tests/unit/test_apply_response.py tests/unit/test_mutations.py tests/unit/test_preview.py tests/unit/test_cli_validation_commands.py tests/unit/test_cli_apply_response.py; uv run ruff check src/tablespec/authoring/mutations.py src/tablespec/authoring/apply_response.py src/tablespec/cli.py tests/unit/test_apply_response.py tests/unit/test_mutations.py tests/unit/test_preview.py tests/unit/test_cli_validation_commands.py tests/unit/test_cli_apply_response.py; uv run pyright src/tablespec/authoring/mutations.py src/tablespec/authoring/apply_response.py src/tablespec/cli.py

Author: easel

.helix/issues.jsonl

@@ -14,5 +14,6 @@
 {"id":"hx-2c3c331f","title":"ADR-005 Phase C: migrate consumers to ExpectationSuite","type":"epic","status":"open","priority":2,"labels":["helix","phase:build","kind:refactor","area:validation"],"deps":[],"parent":"","spec-id":"docs/helix/02-design/adr/ADR-005-unified-expectation-model.md","description":"","design":"","acceptance":"All runtime consumers read from ExpectationSuite; quality_checks retained for backward-compatible loading only","assignee":"","notes":"","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:39:59Z","updated":"2026-04-02T03:39:59Z"}
 {"id":"hx-bdb8fff2","title":"Migrate UMFLoader to populate ExpectationSuite on read","type":"task","status":"in_progress","priority":2,"labels":["helix","phase:build","kind:refactor","area:loader"],"deps":[],"parent":"hx-2c3c331f","spec-id":"docs/helix/02-design/adr/ADR-005-unified-expectation-model.md","description":"","design":"","acceptance":"UMFLoader.load() populates umf.expectations from validation_rules + quality_checks via expectation_migration; split-format saver writes expectations.yaml","assignee":"helix","notes":"","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:40:07Z","updated":"2026-04-02T03:44:10Z"}
 {"id":"hx-8da6f798","title":"Migrate QualityCheckExecutor to read from ExpectationSuite","type":"task","status":"closed","priority":2,"labels":["helix","phase:build","kind:refactor","area:validation"],"deps":["hx-bdb8fff2"],"parent":"hx-2c3c331f","spec-id":"docs/helix/02-design/adr/ADR-005-unified-expectation-model.md","description":"","design":"","acceptance":"QualityCheckExecutor reads from umf.expectations; falls back to quality_checks if expectations is empty","assignee":"helix","notes":"","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:40:13Z","updated":"2026-04-02T03:48:32Z"}
-{"id":"hx-9ed0389d","title":"Migrate authoring commands to use ExpectationSuite","type":"task","status":"open","priority":2,"labels":["helix","phase:build","kind:refactor","area:authoring"],"deps":["hx-bdb8fff2"],"parent":"hx-2c3c331f","spec-id":"docs/helix/02-design/adr/ADR-005-unified-expectation-model.md","description":"","design":"","acceptance":"mutations.py, preview.py, apply_response.py, and cli.py search/mutate umf.expectations instead of quality_checks","assignee":"","notes":"","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:40:19Z","updated":"2026-04-02T03:40:19Z"}
-{"id":"hx-f3261259","title":"Add deprecation warnings to quality_checks and validation_rules fields","type":"task","status":"open","priority":2,"labels":["helix","phase:build","kind:refactor","area:models"],"deps":["hx-8da6f798","hx-9ed0389d"],"parent":"hx-2c3c331f","spec-id":"docs/helix/02-design/adr/ADR-005-unified-expectation-model.md","description":"","design":"","acceptance":"Pydantic model emits DeprecationWarning when quality_checks or validation_rules are populated directly; ADR-005 status updated to Phase C","assignee":"","notes":"","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:40:24Z","updated":"2026-04-02T03:40:24Z"}
+{"id":"hx-9ed0389d","title":"Migrate authoring commands to use ExpectationSuite","type":"task","status":"in_progress","priority":2,"labels":["helix","phase:build","kind:refactor","area:authoring"],"deps":["hx-bdb8fff2"],"parent":"hx-2c3c331f","spec-id":"docs/helix/02-design/adr/ADR-005-unified-expectation-model.md","description":"","design":"","acceptance":"mutations.py, preview.py, apply_response.py, and cli.py search/mutate umf.expectations instead of quality_checks","assignee":"helix","notes":"","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:40:19Z","updated":"2026-04-02T04:11:16Z"}
+{"id":"hx-f3261259","title":"Add deprecation warnings to quality_checks and validation_rules fields","type":"task","status":"in_progress","priority":2,"labels":["helix","phase:build","kind:refactor","area:models"],"deps":["hx-8da6f798","hx-9ed0389d"],"parent":"hx-2c3c331f","spec-id":"docs/helix/02-design/adr/ADR-005-unified-expectation-model.md","description":"","design":"","acceptance":"Pydantic model emits DeprecationWarning when quality_checks or validation_rules are populated directly; ADR-005 status updated to Phase C","assignee":"helix","notes":"","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T03:40:24Z","updated":"2026-04-02T04:14:47Z"}
+{"id":"hx-747cdaa0","title":"Restore canonical make check signal","type":"chore","status":"open","priority":2,"labels":["helix","phase:iterate","area:tooling"],"deps":[],"parent":"","spec-id":"","description":"Running 'make check' on 2026-04-02 during hx-9ed0389d failed before this issue's slice could be evaluated cleanly. Failures include hundreds of existing ruff violations across tracked tests plus untracked .claude/worktrees content being linted. This should be split from feature work so implementation issues can rely on a trustworthy pre-push gate.","design":"","acceptance":"1. 'make check' excludes ephemeral local worktree content such as .claude/worktrees or otherwise ignores non-project artifacts. 2. Remaining lint/type/test failures in tracked project files are reduced until 'make check' passes from a clean checkout. 3. The issue records the exact commands and any config changes needed to keep the canonical gate trustworthy.","assignee":"","notes":"","execution-eligible":true,"superseded-by":"","replaces":"","created":"2026-04-02T04:16:22Z","updated":"2026-04-02T04:16:22Z"}

src/tablespec/authoring/apply_response.py

@@ -6,6 +6,7 @@
 from typing import Any
 
 from tablespec.models.umf import (
+    Expectation,
     INGESTED_QUALITY_CHECK_TYPES,
     RAW_VALIDATION_TYPES,
     UMF,
@@ -22,6 +23,7 @@ class ApplyResult:
     deduplicated: list[dict[str, Any]] = field(default_factory=list)
     invalid: list[tuple[dict[str, Any], str]] = field(default_factory=list)
     warnings: list[str] = field(default_factory=list)
+    updated_umf: UMF | None = None
 
 
 def apply_validation_response(
@@ -40,10 +42,15 @@ def apply_validation_response(
     """
     known_types = RAW_VALIDATION_TYPES | INGESTED_QUALITY_CHECK_TYPES
     result = ApplyResult()
+    new_expectations: list[Expectation] = []
 
     # Get existing expectations for dedup
     existing_signatures: set[str] = set()
-    suite = umf.expectations or migrate_to_expectation_suite(umf.model_dump(exclude_none=True))
+    suite = (
+        umf.expectations.model_copy(deep=True)
+        if umf.expectations is not None
+        else migrate_to_expectation_suite(umf.model_dump(exclude_none=True))
+    )
     for exp in suite.expectations:
         sig = _expectation_signature(exp)
         existing_signatures.add(sig)
@@ -82,8 +89,20 @@ def apply_validation_response(
             continue
 
         result.added.append(exp_dict)
+        new_expectations.append(Expectation.from_gx_dict(exp_dict))
         existing_signatures.add(sig)
 
+    if new_expectations:
+        result.updated_umf = umf.model_copy(
+            update={
+                "expectations": suite.model_copy(
+                    update={"expectations": [*suite.expectations, *new_expectations]}
+                ),
+                "validation_rules": None,
+                "quality_checks": None,
+            }
+        )
+
     return result
 
 

src/tablespec/authoring/mutations.py

@@ -72,6 +72,8 @@ def _matches(exp: dict[str, Any] | Any) -> bool:
 
     if removed:
         updates["expectations"] = suite.model_copy(update={"expectations": filtered_expectations})
+        updates["validation_rules"] = None
+        updates["quality_checks"] = None
 
     return umf.model_copy(update=updates) if updates else umf, removed
 

src/tablespec/cli.py

@@ -825,7 +825,7 @@ def domains_set(
             raise typer.Exit(1)
 
         loader = UMFLoader()
-        umf = loader.load(table_path)
+        umf = loader.load(Path(table_path))
         updated = modify_column(umf, column, domain_type=domain_type)
         dest = Path(table_path)
         fmt = UMFFormat.JSON if dest.suffix == ".json" else UMFFormat.SPLIT
@@ -857,7 +857,7 @@ def column_add(
 
     try:
         loader = UMFLoader()
-        umf = loader.load(table_path)
+        umf = loader.load(Path(table_path))
 
         kwargs: dict = {}
         if description is not None:
@@ -893,7 +893,7 @@ def column_remove(
 
     try:
         loader = UMFLoader()
-        umf = loader.load(table_path)
+        umf = loader.load(Path(table_path))
         updated = remove_column(umf, name)
         dest = Path(table_path)
         fmt = UMFFormat.JSON if dest.suffix == ".json" else UMFFormat.SPLIT
@@ -924,7 +924,7 @@ def column_modify(
 
     try:
         loader = UMFLoader()
-        umf = loader.load(table_path)
+        umf = loader.load(Path(table_path))
 
         changes: dict = {}
         if data_type is not None:
@@ -966,7 +966,7 @@ def column_rename(
 
     try:
         loader = UMFLoader()
-        umf = loader.load(table_path)
+        umf = loader.load(Path(table_path))
         updated = rename_column(umf, old_name, new_name, keep_alias=keep_alias)
         dest = Path(table_path)
         fmt = UMFFormat.JSON if dest.suffix == ".json" else UMFFormat.SPLIT
@@ -1044,7 +1044,7 @@ def validation_remove(
 
     try:
         loader = UMFLoader()
-        umf = loader.load(table_path)
+        umf = loader.load(Path(table_path))
         updated, count = remove_expectation(umf, expectation_type, column)
 
         if count == 0:
@@ -1106,7 +1106,7 @@ def preview(
     from tablespec.gx_baseline import BaselineExpectationGenerator
 
     loader = UMFLoader()
-    umf = loader.load(table_path)
+    umf = loader.load(Path(table_path))
     umf_data = umf.model_dump()
 
     # Also generate baseline expectations
@@ -1200,6 +1200,10 @@ def apply_response(
 
         result = apply_validation_response(umf, response)
 
+        if result.updated_umf is not None and not dry_run:
+            fmt = UMFFormat.JSON if source.suffix == ".json" else UMFFormat.SPLIT
+            loader.save(result.updated_umf, source, format=fmt)
+
         if result.added:
             console.print(f"[green]Added:[/green] {len(result.added)} expectations")
             for exp in result.added:

tests/unit/test_apply_response.py

@@ -15,6 +15,7 @@ def _make_umf(
     columns: list[dict] | None = None,
     validation_rules: dict | None = None,
     quality_checks: dict | None = None,
+    expectations: dict | None = None,
 ) -> UMF:
     """Build a minimal UMF for testing."""
     if columns is None:
@@ -28,6 +29,8 @@ def _make_umf(
         data["validation_rules"] = validation_rules
     if quality_checks is not None:
         data["quality_checks"] = quality_checks
+    if expectations is not None:
+        data["expectations"] = expectations
     return UMF(**data)
 
 
@@ -46,6 +49,8 @@ def test_adds_new_expectations(self):
         assert len(result.added) == 1
         assert result.added[0]["meta"]["generated_from"] == "llm"
         assert result.added[0]["meta"]["validation_stage"] == "raw"
+        assert result.updated_umf is not None
+        assert len(result.updated_umf.expectations.expectations) == 1
 
     def test_deduplicates_existing(self):
         umf = _make_umf(
@@ -191,3 +196,53 @@ def test_result_dataclass_defaults(self):
         assert result.deduplicated == []
         assert result.invalid == []
         assert result.warnings == []
+        assert result.updated_umf is None
+
+    def test_updates_expectation_suite_and_clears_legacy_fields(self):
+        umf = _make_umf(
+            validation_rules={
+                "expectations": [
+                    {
+                        "type": "expect_column_values_to_not_be_null",
+                        "kwargs": {"column": "id"},
+                    }
+                ]
+            }
+        )
+        response = [
+            {
+                "type": "expect_column_values_to_match_regex",
+                "kwargs": {"column": "id", "regex": "^\\d+$"},
+            }
+        ]
+
+        result = apply_validation_response(umf, response)
+
+        assert result.updated_umf is not None
+        assert len(result.updated_umf.expectations.expectations) == 2
+        assert result.updated_umf.validation_rules is None
+        assert result.updated_umf.quality_checks is None
+
+    def test_dedup_does_not_create_updated_umf(self):
+        umf = _make_umf(
+            expectations={
+                "expectations": [
+                    {
+                        "type": "expect_column_values_to_not_be_null",
+                        "kwargs": {"column": "id"},
+                        "meta": {"validation_stage": "raw"},
+                    }
+                ]
+            }
+        )
+        response = [
+            {
+                "type": "expect_column_values_to_not_be_null",
+                "kwargs": {"column": "id"},
+            }
+        ]
+
+        result = apply_validation_response(umf, response)
+
+        assert len(result.deduplicated) == 1
+        assert result.updated_umf is None

tests/unit/test_cli_apply_response.py

@@ -0,0 +1,83 @@
+"""Tests for CLI apply-response command."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+from typer.testing import CliRunner
+
+from tablespec.cli import app
+
+pytestmark = [pytest.mark.no_spark, pytest.mark.fast]
+
+runner = CliRunner(env={"NO_COLOR": "1", "TERM": "dumb"})
+
+
+def _write_umf(tmp_path: Path) -> Path:
+    path = tmp_path / "table.json"
+    path.write_text(
+        json.dumps(
+            {
+                "version": "1.0",
+                "table_name": "TestTable",
+                "columns": [{"name": "id", "data_type": "INTEGER"}],
+                "validation_rules": {
+                    "expectations": [
+                        {
+                            "type": "expect_column_values_to_not_be_null",
+                            "kwargs": {"column": "id"},
+                        }
+                    ]
+                },
+            }
+        )
+    )
+    return path
+
+
+def _write_response(tmp_path: Path) -> Path:
+    path = tmp_path / "response.json"
+    path.write_text(
+        json.dumps(
+            [
+                {
+                    "type": "expect_column_values_to_match_regex",
+                    "kwargs": {"column": "id", "regex": "^\\d+$"},
+                }
+            ]
+        )
+    )
+    return path
+
+
+def test_apply_response_persists_expectation_suite(tmp_path: Path) -> None:
+    umf_file = _write_umf(tmp_path)
+    response_file = _write_response(tmp_path)
+
+    result = runner.invoke(app, ["apply-response", str(umf_file), str(response_file)])
+
+    assert result.exit_code == 0
+    assert "Added:" in result.output
+
+    updated = json.loads(umf_file.read_text())
+    assert "expectations" in updated
+    assert "validation_rules" not in updated
+    expectations = updated["expectations"]["expectations"]
+    assert len(expectations) == 2
+    assert expectations[1]["meta"]["generated_from"] == "llm"
+
+
+def test_apply_response_dry_run_does_not_persist(tmp_path: Path) -> None:
+    umf_file = _write_umf(tmp_path)
+    response_file = _write_response(tmp_path)
+
+    result = runner.invoke(app, ["apply-response", str(umf_file), str(response_file), "--dry-run"])
+
+    assert result.exit_code == 0
+    assert "Dry run" in result.output
+
+    updated = json.loads(umf_file.read_text())
+    assert "validation_rules" in updated
+    assert "expectations" not in updated

tests/unit/test_mutations.py

@@ -152,3 +152,26 @@ def test_updates_only_expectations_field(self):
         # legacy fields are untouched (None on the builder-produced UMF)
         assert result.quality_checks is None
         assert result.validation_rules is None
+
+    def test_removes_from_migrated_legacy_expectations(self):
+        umf = UMF(
+            version="1.0",
+            table_name="t",
+            columns=[{"name": "id", "data_type": "INTEGER"}],
+            validation_rules={
+                "expectations": [
+                    {
+                        "type": "expect_column_values_to_not_be_null",
+                        "kwargs": {"column": "id"},
+                    }
+                ]
+            },
+        )
+
+        result, count = remove_expectation(umf, "expect_column_values_to_not_be_null", "id")
+
+        assert count == 1
+        assert result.expectations is not None
+        assert result.expectations.expectations == []
+        assert result.validation_rules is None
+        assert result.quality_checks is None

tests/unit/test_preview.py

@@ -1,6 +1,6 @@
 import pytest
 
-from tablespec.authoring.preview import generate_preview, PreviewResult
+from tablespec.authoring.preview import generate_preview
 
 pytestmark = [pytest.mark.no_spark, pytest.mark.fast]
 
@@ -113,3 +113,33 @@ def test_severity_from_meta(self):
         }
         result = generate_preview(data)
         assert result.raw[0].severity == "critical"
+
+    def test_prefers_expectation_suite_over_legacy_quality_checks(self):
+        data = {
+            "expectations": {
+                "expectations": [
+                    {
+                        "type": "expect_column_values_to_not_be_null",
+                        "kwargs": {"column": "id"},
+                        "meta": {"validation_stage": "raw", "severity": "critical"},
+                    }
+                ]
+            },
+            "quality_checks": {
+                "checks": [
+                    {
+                        "expectation": {
+                            "type": "expect_column_values_to_be_between",
+                            "kwargs": {"column": "age", "min_value": 0},
+                        },
+                        "severity": "warning",
+                        "blocking": False,
+                    }
+                ]
+            },
+        }
+
+        result = generate_preview(data)
+
+        assert len(result.raw) == 1
+        assert len(result.ingested) == 0