clm-kernel 0.0.0__py3-none-any.whl

clm/cross_cutting/cel_converter.py

@@ -0,0 +1,697 @@
+#!/usr/bin/env python3
+"""CLM CEL Converter — AST-based Python→CEL conversion and schema validation.
+
+Promoted from the root-level ``convert_actual_to_cel_v2.py`` (Sprint 120).
+This module is the canonical, importable home for the conversion pipeline.
+
+Public API:
+    parse_expr_to_cel(expr_str)   — convert a Python expression string to a CEL dict
+    convert_yaml_file(path, ...)  — convert all ``actual`` fields in a YAML file
+    load_schema(path)             — load cel_schema.yaml into a dict of op definitions
+    validate_cel(cel, ...)        — validate a CEL dict against the schema
+    validate_yaml_file(path, ...) — validate all CEL ``actual`` fields in a YAML file
+
+CLI:
+    python -m clm.tools.cel_converter <file.yaml> [--dry-run] [--backup] [--validate]
+"""
+
+import ast
+import os
+import sys
+from typing import Any
+
+from clm.cross_cutting.clm_logger import get_logger
+
+_logger = get_logger("clm.tools.cel_converter")
+
+
+def _ast_to_cel(node):
+    """Convert an AST node to a CEL dict. Returns None if not convertible."""
+    if node is None:
+        return None
+
+    # --- String literal ---
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+
+    # --- Numeric literal ---
+    if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
+        return node.value
+
+    # --- List literal ---
+    if isinstance(node, ast.List):
+        return [_ast_to_cel(elt) for elt in node.elts]
+
+    # --- Boolean literal ---
+    if isinstance(node, ast.Constant) and isinstance(node.value, bool):
+        return node.value
+
+    # --- Tuple literal ---
+    if isinstance(node, ast.Tuple):
+        return tuple(_ast_to_cel(elt) for elt in node.elts)
+
+    # --- Dict literal ---
+    if isinstance(node, ast.Dict):
+        return {_ast_to_cel(k): _ast_to_cel(v) for k, v in zip(node.keys, node.values)}
+
+    # --- Name (identifier) ---
+    if isinstance(node, ast.Name):
+        name = node.id
+        if name == 'True':
+            return True
+        if name == 'False':
+            return False
+        if name == 'None':
+            return None
+        return {"op": "value_ref", "name": name}
+
+    # --- Subscript: inputs['key'], outputs['key'], retrieve('key')[N], call()[N]['key'] ---
+    if isinstance(node, ast.Subscript):
+        if isinstance(node.value, ast.Name) and node.value.id == 'inputs':
+            key = _ast_to_cel(node.slice)
+            if isinstance(key, str):
+                return {"ref": f"inputs.{key}"}
+        if isinstance(node.value, ast.Name) and node.value.id == 'outputs':
+            key = _ast_to_cel(node.slice)
+            if isinstance(key, str):
+                return {"ref": f"outputs.{key}"}
+        # General subscript: convert inner then apply index/dict_get
+        base = _ast_to_cel(node.value)
+        idx = _ast_to_cel(node.slice)
+        if isinstance(idx, int):
+            return {"op": "index", "value": base, "position": idx}
+        if isinstance(idx, str):
+            return {"op": "dict_get", "value": base, "key": idx}
+
+    # --- Attribute access: repo.method, json.loads, os.path.join ---
+    if isinstance(node, ast.Attribute):
+        if isinstance(node.value, ast.Name):
+            # os.path.join -> path_join
+            if node.value.id == 'os' and node.attr == 'path':
+                return {"_partial": "os.path"}
+            # json.loads -> json_parse
+            if node.value.id == 'json' and node.attr == 'loads':
+                return {"_partial": "json.loads"}
+            # time.sleep -> sleep
+            if node.value.id == 'time' and node.attr == 'sleep':
+                return {"_partial": "time.sleep"}
+            # os.environ -> env
+            if node.value.id == 'os' and node.attr == 'environ':
+                return {"_partial": "os.environ"}
+            # shutil.copy -> copy_file
+            if node.value.id == 'shutil' and node.attr == 'copy':
+                return {"_partial": "shutil.copy"}
+            return {"_partial": f"{node.value.id}.{node.attr}"}
+        if isinstance(node.value, ast.Attribute):
+            # os.path.join -> path_join
+            if node.value.value.id == 'os' and node.value.attr == 'path' and node.attr == 'join':
+                return {"_partial": "path_join"}
+            # os.path.basename -> path_basename  (Sprint 126.1)
+            if node.value.value.id == 'os' and node.value.attr == 'path' and node.attr == 'basename':
+                return {"_partial": "path_basename"}
+            # os.environ.pop -> unset_env
+            if node.value.value.id == 'os' and node.value.attr == 'environ' and node.attr == 'pop':
+                return {"_partial": "unset_env"}
+            # os.environ.__setitem__ -> set_env
+            if node.value.value.id == 'os' and node.value.attr == 'environ' and node.attr == '__setitem__':
+                return {"_partial": "set_env"}
+            return {"_partial": f"{_attr_chain(node.value)}.{node.attr}"}
+
+    # --- Handle chained .get() calls on dicts ---
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr == 'get':
+        val = _ast_to_cel(node.func.value)
+        if val is not None:
+            key = _ast_to_cel(node.args[0])
+            default = _ast_to_cel(node.args[1]) if len(node.args) > 1 else None
+            cel = {"op": "dict_get", "value": val, "key": key}
+            if default is not None:
+                cel["default"] = default
+            return cel
+
+    # --- Handle chained .replace() calls ---
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr == 'replace':
+        val = _ast_to_cel(node.func.value)
+        if val is not None:
+            old = _ast_to_cel(node.args[0])
+            new = _ast_to_cel(node.args[1])
+            return {"op": "replace", "value": val, "old": old, "new": new}
+
+    # --- Handle str.join: "sep".join(parts) -> string_join  (Sprint 126.1) ---
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr == 'join':
+        sep = _ast_to_cel(node.func.value)
+        if sep is not None and len(node.args) == 1:
+            parts = _ast_to_cel(node.args[0])
+            return {"op": "string_join", "separator": sep, "parts": parts}
+
+    # --- Handle `open(path).read()` ---
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr == 'read':
+        inner = node.func.value
+        if isinstance(inner, ast.Call) and isinstance(inner.func, ast.Name) and inner.func.id == 'open':
+            path = _ast_to_cel(inner.args[0])
+            return {"op": "read_file", "path": path}
+
+    # --- Handle db.execute(...) patterns (consolidated in Sprint 127.3) ---
+    cel = _convert_db_execute_pattern(node)
+    if cel is not None:
+        return cel
+
+    # --- Call ---
+    if isinstance(node, ast.Call):
+        return _ast_call_to_cel(node)
+
+    # --- BoolOp: and/or ---
+    if isinstance(node, ast.BoolOp):
+        return _ast_boolop_to_cel(node)
+
+    # --- Compare: ==, !=, >=, <=, >, <, in ---
+    if isinstance(node, ast.Compare):
+        return _ast_compare_to_cel(node)
+
+    # --- BinOp: +, -, *, /, //, % ---
+    if isinstance(node, ast.BinOp):
+        return _ast_binop_to_cel(node)
+
+    # --- UnaryOp: not, +, - ---
+    if isinstance(node, ast.UnaryOp):
+        if isinstance(node.op, ast.Not):
+            return {"op": "compare", "left": _ast_to_cel(node.operand), "operator": "eq", "right": False}
+        return None
+
+    return None
+
+
+def _make_db_query_cel(execute_node: ast.Call) -> dict | None:
+    """Build a db_query CEL dict from a db.execute(...) call node."""
+    db_obj = execute_node.func.value
+    if not (isinstance(db_obj, ast.Name) and db_obj.id == 'db'):
+        return None
+    args = [_ast_to_cel(a) for a in execute_node.args]
+    cel = {"op": "db_query", "pillar": args[0], "sql": args[1]}
+    if len(args) > 2:
+        cel["params"] = args[2]
+    return cel
+
+
+def _convert_db_execute_pattern(node: ast.AST) -> dict | None:
+    """Convert any db.execute(...) call pattern to a db_query CEL dict.
+
+    Handles three patterns that were previously 5 separate code blocks:
+      - ``db.execute(pillar, sql)``             -> ``db_query``
+      - ``db.execute(pillar, sql).strip()``     -> ``db_query``
+      - ``int(db.execute(pillar, sql).strip())`` -> ``int_cast(db_query)``
+    """
+    # Pattern: int(db.execute(...).strip())
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id == 'int':
+        arg = node.args[0] if node.args else None
+        if isinstance(arg, ast.Call) and isinstance(arg.func, ast.Attribute) and arg.func.attr == 'strip':
+            inner = arg.func.value
+            if isinstance(inner, ast.Call) and isinstance(inner.func, ast.Attribute) and inner.func.attr == 'execute':
+                cel = _make_db_query_cel(inner)
+                if cel is not None:
+                    return {"op": "int_cast", "value": cel}
+        return None
+
+    # Pattern: db.execute(...).strip()
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr == 'strip':
+        inner = node.func.value
+        if isinstance(inner, ast.Call) and isinstance(inner.func, ast.Attribute) and inner.func.attr == 'execute':
+            return _make_db_query_cel(inner)
+        return None
+
+    # Pattern: db.execute(...)
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr == 'execute':
+        return _make_db_query_cel(node)
+
+    return None
+
+
+def _attr_chain(node):
+    """Convert chained attribute access to dotted string."""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return f"{_attr_chain(node.value)}.{node.attr}"
+    return ""
+
+
+def _partial_db_execute(args: list) -> dict:
+    """Convert db.execute partial call to db_query CEL dict."""
+    cel = {"op": "db_query", "pillar": args[0], "sql": args[1]}
+    if len(args) > 2:
+        cel["params"] = args[2]
+    return cel
+
+
+# Dispatch table for partial (attribute-chain) function calls (Sprint 127.3)
+_PARTIAL_CONVERTERS: dict[str, Any] = {
+    "json.loads":    lambda args: {"op": "json_parse", "value": args[0]},
+    "time.sleep":    lambda args: {"op": "sleep", "seconds": args[0]},
+    "path_join":     lambda args: {"op": "path_join", "parts": args},
+    "path_basename": lambda args: {"op": "path_basename", "value": args[0]},
+    "set_env":       lambda args: {"op": "set_env", "var": args[0], "value": args[1]},
+    "unset_env":     lambda args: {"op": "unset_env", "var": args[0]},
+    "shutil.copy":   lambda args: {"op": "copy_file", "src": args[0], "dest": args[1]},
+    "db.execute":    _partial_db_execute,
+}
+
+# Dispatch table for simple Name function calls (Sprint 127.3)
+_NAME_CALL_CONVERTERS: dict[str, Any] = {
+    "len":         lambda args, kw: {"op": "len", "value": args[0]},
+    "int":         lambda args, kw: {"op": "int_cast", "value": args[0]},
+    "callable":    lambda args, kw: {"op": "callable_check", "value": args[0]},
+    "store":       lambda args, kw: {"op": "store", "key": args[0], "value": args[1]},
+    "retrieve":    lambda args, kw: {"op": "retrieve", "key": args[0]},
+    "write_file":  lambda args, kw: {"op": "write_file", "path": args[0], "content": args[1]},
+}
+
+
+def _ast_call_to_cel(node):
+    """Convert a function call AST node to CEL."""
+    func = _ast_to_cel(node.func)
+    if func is None:
+        return None
+
+    # Handle partials (method references like json.loads) via dispatch table
+    if isinstance(func, dict) and "_partial" in func:
+        partial = func["_partial"]
+        args = [_ast_to_cel(a) for a in node.args]
+        converter = _PARTIAL_CONVERTERS.get(partial)
+        if converter is not None:
+            return converter(args)
+        return {"op": "call", "function": partial, "args": args}
+
+    # Handle simple Name calls via dispatch table
+    if isinstance(func, dict) and func.get("op") == "value_ref":
+        func_name = func["name"]
+        args = [_ast_to_cel(a) for a in node.args]
+        kwargs = {}
+        for kw in node.keywords:
+            kwargs[kw.arg] = _ast_to_cel(kw.value)
+
+        converter = _NAME_CALL_CONVERTERS.get(func_name)
+        if converter is not None:
+            return converter(args, kwargs)
+        if func_name == 'db' and len(args) >= 2:
+            return {"op": "db_query", "pillar": args[0], "sql": args[1], "params": args[2] if len(args) > 2 else None}
+
+        return {"op": "call", "function": func_name, "args": args, "kwargs": kwargs}
+
+    # Handle Attribute calls: repo.method(...)
+    if isinstance(func, dict) and "_partial" in func:
+        func_name = func["_partial"]
+        args = [_ast_to_cel(a) for a in node.args]
+        kwargs = {}
+        for kw in node.keywords:
+            kwargs[kw.arg] = _ast_to_cel(kw.value)
+        return {"op": "call", "function": func_name, "args": args, "kwargs": kwargs}
+
+    return None
+
+
+def _ast_boolop_to_cel(node):
+    """Convert BoolOp (and/or) to CEL sequence or compare."""
+
+    if isinstance(node.op, ast.And):
+        values = [_ast_to_cel(v) for v in node.values]
+        # Filter out None values
+        steps = [v for v in values if v is not None]
+        if steps:
+            return {"op": "sequence", "steps": steps}
+        return None
+
+    if isinstance(node.op, ast.Or):
+        # Check for `a or True` pattern
+        last = node.values[-1]
+        if isinstance(last, ast.Constant) and last.value is True:
+            # Convert remaining values, handling os.environ.__setitem__ specially
+            steps = []
+            for v in node.values[:-1]:
+                cel = _ast_to_cel(v)
+                if cel is not None:
+                    steps.append(cel)
+            if steps:
+                return {"op": "sequence", "steps": steps}
+            return None
+        # Check for `__setitem__(...) or __setitem__(...)` pattern
+        setitem_steps = []
+        other_values = []
+        for v in node.values:
+            if isinstance(v, ast.Call) and isinstance(v.func, ast.Attribute) and v.func.attr == '__setitem__':
+                env = v.func.value
+                if isinstance(env, ast.Attribute) and env.attr == 'environ' and isinstance(env.value, ast.Name) and env.value.id == 'os':
+                    args = [_ast_to_cel(a) for a in v.args]
+                    setitem_steps.append({"op": "set_env", "var": args[0], "value": args[1]})
+                else:
+                    cel = _ast_to_cel(v)
+                    if cel is not None:
+                        setitem_steps.append(cel)
+            else:
+                other_values.append(v)
+        if setitem_steps:
+            return {"op": "sequence", "steps": setitem_steps}
+        # General `a or fallback` pattern -> or_fallback
+        if len(other_values) == 2:
+            left = _ast_to_cel(other_values[0])
+            right = _ast_to_cel(other_values[1])
+            if left is not None and right is not None:
+                return {"op": "or_fallback", "value": left, "fallback": right}
+        return None
+
+    return None
+
+
+def _ast_compare_to_cel(node):
+    """Convert Compare to CEL compare op.
+
+    Two pattern-specific shortcuts produce semantically cleaner CEL than the
+    generic compare wrapper:
+      - `os.environ.pop('VAR', None) is not False` → `unset_env` (drop the tautological compare)
+      - `store('key', value) is not None`         → `sequence(store, not_null(retrieve(key)))`
+    """
+    # --- Pattern: os.environ.pop('VAR', None) is not False → unset_env ---
+    if len(node.ops) == 1 and isinstance(node.ops[0], ast.IsNot) and \
+       isinstance(node.comparators[0], ast.Constant) and node.comparators[0].value is False:
+        inner = node.left
+        if isinstance(inner, ast.Call) and isinstance(inner.func, ast.Attribute) and inner.func.attr == 'pop':
+            env = inner.func.value
+            if isinstance(env, ast.Attribute) and env.attr == 'environ' and \
+               isinstance(env.value, ast.Name) and env.value.id == 'os':
+                args = [_ast_to_cel(a) for a in inner.args]
+                return {"op": "unset_env", "var": args[0]}
+
+    # --- Pattern: store('key', value) is not None → sequence(store, not_null) ---
+    if len(node.ops) == 1 and isinstance(node.ops[0], ast.IsNot) and \
+       isinstance(node.comparators[0], ast.Constant) and node.comparators[0].value is None:
+        inner = _ast_to_cel(node.left)
+        if isinstance(inner, dict) and inner.get("op") == "store":
+                return {
+                    "op": "sequence",
+                    "steps": [
+                        inner,
+                        {"op": "not_null", "value": {"op": "retrieve", "key": inner["key"]}}
+                    ]
+                }
+
+    # --- Generic compare ---
+    left = _ast_to_cel(node.left)
+    if left is None:
+        return None
+
+    ops_map = {
+        ast.Eq: "eq", ast.NotEq: "ne",
+        ast.Gt: "gt", ast.GtE: "gte",
+        ast.Lt: "lt", ast.LtE: "lte",
+        ast.In: "in",
+        ast.IsNot: "ne", ast.Is: "eq"
+    }
+
+    comparators = [_ast_to_cel(c) for c in node.comparators]
+    if len(node.ops) == 1 and len(comparators) == 1:
+        op = node.ops[0]
+        if type(op) in ops_map:
+            return {"op": "compare", "left": left, "operator": ops_map[type(op)], "right": comparators[0]}
+
+    # For chained comparisons, we can't easily represent them in CEL
+    return None
+
+
+def _ast_binop_to_cel(node):
+    """Convert BinOp to CEL."""
+    left = _ast_to_cel(node.left)
+    right = _ast_to_cel(node.right)
+    if left is None or right is None:
+        return None
+
+    if isinstance(node.op, ast.Add):
+        return {"op": "string_concat", "parts": [left, right]}
+    if isinstance(node.op, ast.Sub):
+        return {"op": "call", "function": "operator.sub", "args": [left, right]}
+    if isinstance(node.op, ast.Mult):
+        return {"op": "call", "function": "operator.mul", "args": [left, right]}
+    if isinstance(node.op, ast.Div):
+        return {"op": "call", "function": "operator.truediv", "args": [left, right]}
+    if isinstance(node.op, ast.Mod):
+        return {"op": "call", "function": "operator.mod", "args": [left, right]}
+
+    return None
+
+
+def _strip_or_true(node):
+    """If expression is `something or True`, return the something."""
+    if isinstance(node, ast.BoolOp) and isinstance(node.op, ast.Or) and len(node.values) == 2:
+        last = node.values[-1]
+        if isinstance(last, ast.Constant) and last.value is True:
+                return node.values[0]
+    return None
+
+
+def _strip_method_chain(node, method_names):
+    """Strip a chain of method calls like .strip(), .read(), etc."""
+    calls = []
+    current = node
+    while isinstance(current, ast.Call) and isinstance(current.func, ast.Attribute):
+        calls.append((current.func.attr, [_ast_to_cel(a) for a in current.args]))
+        current = current.func.value
+    calls.reverse()
+    return current, calls
+
+
+def parse_expr_to_cel(expr_str: str):
+    """Parse a Python expression string and convert to a CEL dict.
+
+    Thin wrapper around the generic AST→CEL dispatcher (`_ast_to_cel`).
+    Strips the common `X or True` idiom before dispatch. All node-type
+    dispatch (calls, comparisons, boolops, subscripts, etc.) is handled
+    by `_ast_to_cel` and its helpers — this function does NOT re-implement
+    per-pattern logic.
+    """
+    expr_str = expr_str.strip()
+
+    try:
+        tree = ast.parse(expr_str, mode='eval')
+    except SyntaxError:
+        return expr_str
+
+    node = tree.body
+
+    # --- Strip the common `X or True` wrapper ---
+    stripped = _strip_or_true(node)
+    if stripped is not None:
+        node = stripped
+
+    result = _ast_to_cel(node)
+    return result if result is not None else expr_str
+
+
+def _tuple_representer(dumper, data):
+    """Represent a Python tuple as a YAML sequence (without !!python/tuple tag)."""
+    return dumper.represent_list(data)
+
+
+def convert_yaml_file(filepath: str, dry_run: bool = False):
+    """Convert all `actual` fields in a YAML file to CEL."""
+    import yaml
+
+    with open(filepath, 'r', encoding='utf-8') as f:
+        content = f.read()
+
+    data = yaml.safe_load(content)
+
+    count = 0
+    skipped = 0
+    skipped_exprs = []
+
+    def _walk(node, path=''):
+        nonlocal count, skipped
+        if isinstance(node, dict):
+            if 'actual' in node and isinstance(node['actual'], str):
+                cel = parse_expr_to_cel(node['actual'])
+                if isinstance(cel, dict):
+                    node['actual'] = cel
+                    count += 1
+                else:
+                    skipped += 1
+                    skipped_exprs.append((path, node['actual']))
+            for k, v in node.items():
+                _walk(v, f"{path}.{k}")
+        elif isinstance(node, list):
+            for i, item in enumerate(node):
+                _walk(item, f"{path}[{i}]")
+
+    _walk(data)
+
+    print(f"Converted: {count}, Skipped: {skipped}")
+    if skipped > 0 and dry_run:
+        for p, e in skipped_exprs:
+            print(f"  SKIP {p}: {e[:100]}")
+
+    if not dry_run:
+        with open(filepath, 'w', encoding='utf-8') as f:
+            yaml.SafeDumper.add_representer(tuple, _tuple_representer)
+            yaml.dump(data, f, default_flow_style=False, sort_keys=False, allow_unicode=True, Dumper=yaml.SafeDumper)
+
+    return count, skipped
+
+
+# ---------------------------------------------------------------------------
+# Schema validation (Sprint 120 Future Work §7.3)
+# ---------------------------------------------------------------------------
+
+_DEFAULT_SCHEMA_RELS = [
+    os.path.join(os.path.dirname(__file__), "..", "..", "..", "..", "..", "types", "schemas", "cel_schema.yaml"),
+    os.path.join(os.path.dirname(__file__), "..", "..", "..", "..", "types", "schemas", "cel_schema.yaml"),
+]
+
+
+def _find_default_schema() -> str | None:
+    """Locate cel_schema.yaml relative to this module or the project root."""
+    for rel in _DEFAULT_SCHEMA_RELS:
+        p = os.path.normpath(rel)
+        if os.path.isfile(p):
+            return p
+    return None
+
+
+def load_schema(schema_path: str | None = None) -> dict[str, dict]:
+    """Load cel_schema.yaml and return ``{op_name: {required: [...], optional: [...]}}``.
+
+    Args:
+        schema_path: Path to ``cel_schema.yaml``. If None, auto-discovers via
+            ``_find_default_schema()``.
+
+    Returns:
+        Dict mapping operation name to its schema definition (``required``,
+        ``optional``, ``description``, ``defaults``).
+    """
+    import yaml
+
+    if schema_path is None:
+        schema_path = _find_default_schema()
+    if schema_path is None or not os.path.isfile(schema_path):
+        raise FileNotFoundError(f"CEL schema not found: {schema_path}")
+
+    with open(schema_path, "r", encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+
+    operations = data.get("operations", {}) if isinstance(data, dict) else {}
+    return operations
+
+
+def validate_cel(cel: Any, schema: dict[str, dict] | None = None, schema_path: str | None = None) -> list[str]:
+    """Validate a CEL dict against ``cel_schema.yaml``.
+
+    Checks:
+      - ``cel`` must be a dict with an ``op`` field.
+      - ``op`` must be a known operation in the schema.
+      - All ``required`` fields listed in the schema must be present.
+      - No unknown top-level fields (beyond ``required`` + ``optional`` + ``op``).
+
+    Args:
+        cel: The CEL dict to validate.
+        schema: Pre-loaded schema dict (from ``load_schema``). If None, loads it.
+        schema_path: Path to schema file (used if ``schema`` is None).
+
+    Returns:
+        List of validation error strings. Empty list = valid.
+    """
+    if schema is None:
+        schema = load_schema(schema_path)
+
+    errors: list[str] = []
+
+    if not isinstance(cel, dict):
+        return [f"CEL value is not a dict (got {type(cel).__name__}: {cel!r})"]
+
+    op = cel.get("op")
+    if op is None:
+        return ["CEL dict missing 'op' field"]
+
+    op_def = schema.get(op)
+    if op_def is None:
+        return [f"Unknown CEL operation: '{op}'"]
+
+    required = op_def.get("required", [])
+    optional = op_def.get("optional", [])
+    allowed_keys = {"op"} | set(required) | set(optional)
+
+    for field in required:
+        if field not in cel:
+            errors.append(f"Operation '{op}' missing required field '{field}'")
+
+    for key in cel:
+        if key not in allowed_keys:
+            errors.append(f"Operation '{op}' has unknown field '{key}'")
+
+    return errors
+
+
+def validate_yaml_file(filepath: str, schema_path: str | None = None) -> tuple[int, list[str]]:
+    """Validate all CEL ``actual`` fields in a YAML file against the schema.
+
+    Walks the YAML tree, finds every dict with an ``actual`` key that is itself
+    a dict (i.e., already CEL-converted), and validates it.
+
+    Args:
+        filepath: Path to the YAML file.
+        schema_path: Path to ``cel_schema.yaml``. If None, auto-discovers.
+
+    Returns:
+        ``(validated_count, errors)`` where errors is a list of strings.
+    """
+    import yaml
+
+    with open(filepath, "r", encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+
+    schema = load_schema(schema_path)
+    errors: list[str] = []
+    count = 0
+
+    def _walk(node, path=""):
+        nonlocal count
+        if isinstance(node, dict):
+            if "actual" in node and isinstance(node["actual"], dict):
+                count += 1
+                cel = node["actual"]
+                errs = validate_cel(cel, schema)
+                for e in errs:
+                    errors.append(f"{path}.actual: {e}")
+            for k, v in node.items():
+                _walk(v, f"{path}.{k}")
+        elif isinstance(node, list):
+            for i, item in enumerate(node):
+                _walk(item, f"{path}[{i}]")
+
+    if data is not None:
+        _walk(data)
+
+    return count, errors
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="CLM CEL Converter — convert and validate YAML actual fields")
+    parser.add_argument("file", help="YAML file to process")
+    parser.add_argument("--dry-run", action="store_true", help="Preview changes without writing")
+    parser.add_argument("--backup", action="store_true", help="Create .bak backup")
+    parser.add_argument("--validate", action="store_true", help="Validate CEL dicts against schema (no conversion)")
+    args = parser.parse_args()
+
+    if args.validate:
+        count, errors = validate_yaml_file(args.file)
+        if errors:
+            print(f"Validation FAILED: {len(errors)} errors in {count} CEL dicts:")
+            for e in errors:
+                print(f"  {e}")
+            sys.exit(1)
+        else:
+            print(f"Validation PASSED: {count} CEL dicts are valid.")
+            sys.exit(0)
+
+    if args.backup:
+        import shutil
+        shutil.copy(args.file, args.file + ".bak")
+
+    count, skipped = convert_yaml_file(args.file, dry_run=args.dry_run)
+    print(f"Done. Converted {count} expressions, skipped {skipped}.")