mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/operation_registry.py

@@ -0,0 +1,1007 @@
+"""Closed capability authority for the versioned table-plan graph.
+
+The registry contains declarations only.  Plan values cannot choose an import, plugin, callable,
+or engine expression.  Later phases attach the named executor hooks in reviewed code while this
+module remains the single source for operation coordinates, arity, and parameter shape.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any
+
+from mostlyright.data_harness.units import UnitError, resolve_declared_unit
+
+GRAPH_OPERATION_VERSION = "1.0.0"
+GRAPH_OPERATION_CONTRACT_VERSION = "local-operations.v2"
+MAX_PARAMETER_MEMBERS = 4_096
+MAX_PARAMETER_DEPTH = 16
+# A fixed availability offset is a cleaning declaration, not an unbounded duration language. Ten
+# calendar years covers publication-delay corrections without turning this one-row operation into
+# a general temporal calculation surface. The bound is symmetric because a source can record when
+# a value became available before a declared rate date as well as after it.
+MAX_DATE_ADD_DAYS = 3_650
+
+# The two availabilities an entry in this table can have.  ``EXECUTABLE`` is an operation a plan
+# may name.  ``RETIRED`` is one that no longer meets the admission contract and that no newly
+# authored plan may name, kept in the table because a Build sealed before it was retired, and a
+# Recipe approved before it was retired, both re-parse their stored plan through this table --
+# dropping the entry would make their own sealed bytes unreadable, which is a different and worse
+# thing than retiring an operation.  The refusal for new bytes lives at the authoring surfaces in
+# ``local_contracts.refuse_retired_operations``, not in ``resolve_operation``, precisely because
+# ``resolve_operation`` is on both paths and cannot tell them apart.
+EXECUTABLE = "executable"
+RETIRED = "retired"
+_AVAILABILITIES = frozenset({EXECUTABLE, RETIRED})
+
+# The join kinds a graph node may name, and the only place join-kind growth happens.  The older
+# plan version's ``JoinSpec`` is frozen at ``left`` alone, so this set and
+# ``local_contracts.JOIN_KINDS`` are deliberately different sizes, and ``docs/TRANSFORMS.md``
+# records the ruling that keeps them that way.  Both sets are pinned by equality in one test,
+# ``tests/test_local_contracts.py``, so adding a kind here reds the assertion that sits beside the
+# frozen one -- which is the point: the decision about the older version is taken in the same
+# place, rather than the two vocabularies drifting apart quietly.
+GRAPH_JOIN_KINDS = frozenset({"left", "inner", "anti"})
+
+
+class OperationRegistryError(ValueError):
+    """A stable feasibility refusal produced by the graph capability authority."""
+
+    def __init__(self, code: str, path: str, detail: str) -> None:
+        self.code = code
+        self.path = path
+        self.detail = detail
+        super().__init__(f"{path}: {detail} [{code}]")
+
+
+@dataclass(frozen=True)
+class AdmissionRow:
+    """One operation's row in the admission table in ``docs/TRANSFORMS.md``.
+
+    The table judges every operation against the scope test on that page, so each row is a
+    written finding rather than anything derivable: what the verdict was, one example that shows
+    the shape, and the reason in a few words. It is carried on the entry so that the page and the
+    entry cannot disagree -- ``scripts/generate_registry_tables.py`` emits the page's rows from
+    here -- and it is inert: nothing in resolution or parameter validation reads it.
+    """
+
+    verdict: str
+    example: str
+    rationale: str
+
+    def __post_init__(self) -> None:
+        # The value has to *be* its one line, not merely split into one. ``splitlines`` honours
+        # every separator that would break a table row, including the vertical tab and the
+        # paragraph separator, but it drops a trailing one -- so a cell ending in a newline
+        # splits into a single line and would push the row after it out of the table anyway.
+        for name in ("verdict", "example", "rationale"):
+            value = getattr(self, name)
+            lines = value.splitlines() if isinstance(value, str) else []
+            if (
+                not isinstance(value, str)
+                or not value.strip()
+                or "|" in value
+                or len(lines) != 1
+                or lines[0] != value
+            ):
+                raise OperationRegistryError(
+                    "OPERATION_ADMISSION",
+                    f"operation_registry.admission.{name}",
+                    "must be one nonempty line holding no table separator",
+                )
+
+
+@dataclass(frozen=True)
+class GraphOperation:
+    name: str
+    version: str
+    input_arity: tuple[int, int]
+    required_parameters: frozenset[str]
+    optional_parameters: frozenset[str]
+    contract_parser_hook: str
+    executor_hook: str
+    admission: AdmissionRow
+    availability: str = EXECUTABLE
+
+    def __post_init__(self) -> None:
+        # RETIRED_OPERATIONS derives by equality against RETIRED, so a misspelling here would not
+        # fail anywhere -- it would quietly leave a retired operation admitted for new plans.
+        if self.availability not in _AVAILABILITIES:
+            raise OperationRegistryError(
+                "OPERATION_AVAILABILITY",
+                f"operation_registry.{self.name}.availability",
+                f"availability must be one of {sorted(_AVAILABILITIES)}",
+            )
+        # The written verdict and the field the software acts on are two statements of one
+        # decision, and a page saying "Admitted" beside a table refusing the operation is worse
+        # than either alone. Binding them here is what keeps the emitted row honest.
+        expected = "Retired" if self.availability == RETIRED else "Admitted"
+        if not self.admission.verdict.startswith(expected):
+            raise OperationRegistryError(
+                "OPERATION_ADMISSION",
+                f"operation_registry.{self.name}.admission.verdict",
+                f"an operation whose availability is {self.availability!r} reads {expected!r}",
+            )
+
+    def validate_parameters(self, value: Any, *, path: str) -> tuple[tuple[str, Any], ...]:
+        if not isinstance(value, Mapping) or any(not isinstance(key, str) for key in value):
+            raise OperationRegistryError("OPERATION_PARAMETERS", path, "must be an object")
+        keys = frozenset(value)
+        missing = sorted(self.required_parameters - keys)
+        unknown = sorted(keys - self.required_parameters - self.optional_parameters)
+        if missing or unknown:
+            raise OperationRegistryError(
+                "OPERATION_PARAMETERS",
+                path,
+                f"fields invalid; missing={missing}, unknown={unknown}",
+            )
+        _validate_semantics(self.name, value, path)
+        budget = [0]
+        return tuple(
+            (key, _freeze_json(value[key], f"{path}.{key}", depth=0, budget=budget))
+            for key in sorted(value)
+        )
+
+
+def _operation(
+    name: str,
+    arity: tuple[int, int],
+    required: set[str],
+    optional: set[str] | None = None,
+    *,
+    availability: str = EXECUTABLE,
+    verdict: str,
+    example: str,
+    rationale: str,
+) -> GraphOperation:
+    return GraphOperation(
+        name=name,
+        version=GRAPH_OPERATION_VERSION,
+        input_arity=arity,
+        required_parameters=frozenset(required),
+        optional_parameters=frozenset(optional or set()),
+        contract_parser_hook=f"parse_{name}_parameters",
+        executor_hook=f"execute_{name}",
+        admission=AdmissionRow(verdict=verdict, example=example, rationale=rationale),
+        availability=availability,
+    )
+
+
+def _choice(
+    value: Any, allowed: set[str], path: str, *, code: str = "OPERATION_PARAMETERS"
+) -> None:
+    if not isinstance(value, str) or value not in allowed:
+        raise OperationRegistryError(code, path, f"must be one of {sorted(allowed)}")
+
+
+def _text(value: Any, path: str) -> str:
+    if (
+        not isinstance(value, str)
+        or not value
+        or len(value) > 128
+        or any(ord(char) < 32 for char in value)
+    ):
+        raise OperationRegistryError("OPERATION_PARAMETERS", path, "must be bounded text")
+    return value
+
+
+def _text_list(value: Any, path: str, *, empty: bool = False) -> list[str]:
+    if (
+        not isinstance(value, list)
+        or (not empty and not value)
+        or len(value) > 256
+        or any(not isinstance(item, str) for item in value)
+    ):
+        raise OperationRegistryError("OPERATION_PARAMETERS", path, "must be a bounded text list")
+    for index, item in enumerate(value):
+        _text(item, f"{path}[{index}]")
+    if len(value) != len(set(value)):
+        raise OperationRegistryError("OPERATION_PARAMETERS", path, "values must be unique")
+    return value
+
+
+def _positive_int(value: Any, path: str, *, maximum: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or not 1 <= value <= maximum:
+        raise OperationRegistryError(
+            "OPERATION_PARAMETERS", path, f"must be an integer from 1 to {maximum}"
+        )
+    return value
+
+
+def _date_add_days_offset(value: Any, path: str) -> int:
+    """Accept the one signed, fixed calendar offset this operation may declare."""
+
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise OperationRegistryError(
+            "DATE_ADD_DAYS_TYPE", path, "days must be a signed int64 calendar-day offset"
+        )
+    if not -MAX_DATE_ADD_DAYS <= value <= MAX_DATE_ADD_DAYS:
+        raise OperationRegistryError(
+            "DATE_ADD_DAYS_RANGE",
+            path,
+            f"days must be from {-MAX_DATE_ADD_DAYS} to {MAX_DATE_ADD_DAYS}",
+        )
+    return value
+
+
+def _exact(value: Mapping[str, Any], expected: set[str], path: str) -> None:
+    if set(value) != expected:
+        raise OperationRegistryError(
+            "OPERATION_PARAMETERS", path, f"fields must be exactly {sorted(expected)}"
+        )
+
+
+def _operand(value: Any, path: str, *, membership: bool = False) -> None:
+    if not isinstance(value, Mapping):
+        raise OperationRegistryError("OPERATION_PARAMETERS", path, "operand must be an object")
+    if set(value) == {"column"}:
+        _text(value["column"], f"{path}.column")
+        return
+    if set(value) != {"literal"}:
+        raise OperationRegistryError(
+            "OPERATION_PARAMETERS", path, "operand must name one column or literal"
+        )
+    literal = value["literal"]
+    if membership:
+        if not isinstance(literal, list) or not 1 <= len(literal) <= 256:
+            raise OperationRegistryError(
+                "OPERATION_PARAMETERS", f"{path}.literal", "membership literal must be bounded list"
+            )
+        if any(type(item) not in {bool, int, str} and item is not None for item in literal):
+            raise OperationRegistryError(
+                "OPERATION_PARAMETERS", f"{path}.literal", "membership values are not scalar"
+            )
+    elif type(literal) not in {bool, int, str} and literal is not None:
+        raise OperationRegistryError(
+            "OPERATION_PARAMETERS", f"{path}.literal", "literal must be a scalar"
+        )
+
+
+def _predicate(value: Any, path: str, *, depth: int = 0) -> None:
+    if depth > 16 or not isinstance(value, Mapping):
+        raise OperationRegistryError("OPERATION_PARAMETERS", path, "predicate is invalid")
+    op = value.get("op")
+    if op in {"and", "or"}:
+        _exact(value, {"op", "args"}, path)
+        args = value["args"]
+        if not isinstance(args, list) or not 2 <= len(args) <= 64:
+            raise OperationRegistryError(
+                "OPERATION_PARAMETERS", f"{path}.args", "boolean op needs 2..64 predicates"
+            )
+        for index, item in enumerate(args):
+            _predicate(item, f"{path}.args[{index}]", depth=depth + 1)
+        return
+    if op == "not":
+        _exact(value, {"op", "arg"}, path)
+        _predicate(value["arg"], f"{path}.arg", depth=depth + 1)
+        return
+    if op in {"is_null", "not_null"}:
+        _exact(value, {"op", "left"}, path)
+        _operand(value["left"], f"{path}.left")
+        return
+    if op in {"eq", "ne", "lt", "le", "gt", "ge", "in"}:
+        _exact(value, {"op", "left", "right"}, path)
+        _operand(value["left"], f"{path}.left")
+        _operand(value["right"], f"{path}.right", membership=op == "in")
+        return
+    raise OperationRegistryError(
+        "OPERATION_PARAMETERS", f"{path}.op", "predicate operation is unsupported"
+    )
+
+
+def _derive_expression(value: Any, path: str, *, depth: int = 0) -> None:
+    if depth > 16 or not isinstance(value, Mapping):
+        raise OperationRegistryError("OPERATION_PARAMETERS", path, "derive expression is invalid")
+    if set(value) in ({"column"}, {"literal"}):
+        _operand(value, path)
+        return
+    op = value.get("op")
+    if op == "if":
+        _exact(value, {"op", "condition", "then", "else"}, path)
+        _predicate(value["condition"], f"{path}.condition", depth=depth + 1)
+        _derive_expression(value["then"], f"{path}.then", depth=depth + 1)
+        _derive_expression(value["else"], f"{path}.else", depth=depth + 1)
+        return
+    _exact(value, {"op", "args"}, path)
+    args = value["args"]
+    arity = DERIVE_EXPRESSION_ARITY
+    if op == "concat":
+        valid = isinstance(args, list) and 1 <= len(args) <= 64
+    else:
+        valid = op in arity and isinstance(args, list) and len(args) == arity[op]
+    if not valid:
+        raise OperationRegistryError(
+            "OPERATION_PARAMETERS", f"{path}.args", "derive operation or arity is unsupported"
+        )
+    for index, item in enumerate(args):
+        _derive_expression(item, f"{path}.args[{index}]", depth=depth + 1)
+
+
+# The two denominator policies a dividing ``derive`` node declares, in the style of the node's
+# ``overflow_policy`` and ``null_policy``: one admitted spelling each, named in the plan so the
+# behaviour is read from the recipe rather than inferred from the kernel.
+#: Every operator a derive expression can name, and how many arguments each takes. It is stated
+#: once, here, because two things read it: the shape check below, and the unit analysis in
+#: :mod:`unit_flow`, which has to say what each operator does to a declared unit. An operator added
+#: to one and not the other is what let a conditional go unexamined by both unit gates.
+DERIVE_EXPRESSION_ARITY: Mapping[str, int] = MappingProxyType(
+    {
+        "add": 2,
+        "subtract": 2,
+        "multiply": 2,
+        # The numerator comes first and the denominator second; the order is contract-significant
+        # because division is the one arithmetic operator here that is not commutative.
+        "divide": 2,
+        "year": 1,
+        "month": 1,
+        "day": 1,
+        "hour": 1,
+        # The two lexical normalizers. Both are bounded rewrites of one string operand: neither
+        # parses, matches a pattern, or accepts one from a plan.
+        "trim": 1,
+        "case_fold": 1,
+    }
+)
+#: The two the arity table cannot hold: a conditional's parts are named rather than counted, and a
+#: concatenation takes one to sixty-four.
+DERIVE_EXPRESSION_VARIADIC: frozenset[str] = frozenset({"if", "concat"})
+
+DIVIDE_POLICIES: tuple[str, ...] = ("zero_denominator_policy", "null_denominator_policy")
+_DIVIDE_POLICY_CHOICES = {
+    "zero_denominator_policy": {"reject"},
+    "null_denominator_policy": {"propagate"},
+}
+
+
+def _divides(value: Any) -> bool:
+    """Report whether one derive expression tree contains a division anywhere inside it."""
+
+    if isinstance(value, Mapping):
+        return value.get("op") == "divide" or any(_divides(item) for item in value.values())
+    if isinstance(value, list):
+        return any(_divides(item) for item in value)
+    return False
+
+
+def _divide_policies(value: Mapping[str, Any], expressions: Mapping[str, Any], path: str) -> None:
+    """Bind the denominator policies to the presence of a division, in both directions.
+
+    A node that divides must declare both policies, and a node that does not divide must declare
+    neither. Making the pair exactly conditional keeps the parameter set closed: a plan cannot
+    carry a policy that governs nothing, and a division cannot run under a policy nobody wrote.
+    """
+
+    dividing = any(
+        _divides(specification.get("expression"))
+        for specification in expressions.values()
+        if isinstance(specification, Mapping)
+    )
+    declared = [name for name in DIVIDE_POLICIES if name in value]
+    if not dividing:
+        if declared:
+            raise OperationRegistryError(
+                "OPERATION_PARAMETERS",
+                f"{path}.{declared[0]}",
+                "only a derive node containing a divide expression declares denominator policies",
+            )
+        return
+    missing = [name for name in DIVIDE_POLICIES if name not in value]
+    if missing:
+        raise OperationRegistryError(
+            "OPERATION_PARAMETERS",
+            f"{path}.{missing[0]}",
+            "a divide expression requires a declared denominator policy",
+        )
+    for name in DIVIDE_POLICIES:
+        _choice(value[name], _DIVIDE_POLICY_CHOICES[name], f"{path}.{name}")
+
+
+def _unit_code(value: Any, path: str) -> None:
+    """Admit one unit code the grammar resolves, or refuse it by the construct that failed."""
+
+    if not isinstance(value, str):
+        raise OperationRegistryError("OPERATION_PARAMETERS", path, "a unit code must be text")
+    try:
+        resolve_declared_unit(value)
+    except UnitError as exc:
+        raise OperationRegistryError(
+            "UNIT_CODE", path, f"{value!r} is not a unit code: {exc.detail}"
+        ) from None
+
+
+def _column_units(value: Any, path: str) -> None:
+    """Admit a bounded column-to-unit declaration, or nothing at all.
+
+    Declaring nothing is the ordinary case and stays legal forever: a column with no declared unit
+    is untouched by the gates that read this, so adding the parameter cannot refuse a plan that
+    was already correct.
+    """
+
+    if value is None:
+        return
+    if not isinstance(value, Mapping) or not value:
+        raise OperationRegistryError(
+            "OPERATION_PARAMETERS", path, "must be a non-empty object or absent"
+        )
+    if len(value) > 256:
+        raise OperationRegistryError(
+            "OPERATION_PARAMETERS", path, "must declare at most 256 columns"
+        )
+    for column, code in value.items():
+        if not isinstance(column, str):
+            raise OperationRegistryError("OPERATION_PARAMETERS", path, "column names must be text")
+        _text(column, path)
+        _unit_code(code, f"{path}.{column}")
+
+
+def _sort_keys(value: Any, path: str) -> None:
+    if not isinstance(value, list) or not 1 <= len(value) <= 256:
+        raise OperationRegistryError("OPERATION_PARAMETERS", path, "sort keys must be bounded list")
+    for index, item in enumerate(value):
+        item_path = f"{path}[{index}]"
+        if isinstance(item, str):
+            _text(item, item_path)
+            continue
+        if not isinstance(item, Mapping):
+            raise OperationRegistryError("OPERATION_PARAMETERS", item_path, "sort key is invalid")
+        _exact(item, {"column", "direction", "nulls"}, item_path)
+        _text(item["column"], f"{item_path}.column")
+        _choice(item["direction"], {"asc", "desc"}, f"{item_path}.direction")
+        _choice(item["nulls"], {"first", "last"}, f"{item_path}.nulls")
+
+
+def _measures(value: Any, path: str) -> None:
+    if not isinstance(value, list) or not 1 <= len(value) <= 256:
+        raise OperationRegistryError("OPERATION_PARAMETERS", path, "measures must be bounded list")
+    names: list[str] = []
+    for index, item in enumerate(value):
+        item_path = f"{path}[{index}]"
+        if not isinstance(item, Mapping):
+            raise OperationRegistryError("OPERATION_PARAMETERS", item_path, "measure is invalid")
+        _exact(item, {"column", "op", "as"}, item_path)
+        _text(item["column"], f"{item_path}.column")
+        _choice(
+            item["op"], {"count", "sum", "min", "max", "mean", "first", "last"}, f"{item_path}.op"
+        )
+        names.append(_text(item["as"], f"{item_path}.as"))
+    if len(names) != len(set(names)):
+        raise OperationRegistryError("OPERATION_PARAMETERS", path, "measure outputs must be unique")
+
+
+def _validate_semantics(name: str, value: Mapping[str, Any], path: str) -> None:
+    """Admit only policy variants the deterministic v2 kernel actually implements."""
+
+    if name == "union":
+        _choice(
+            value["column_matching"], {"exact"}, f"{path}.column_matching", code="UNION_UNSUPPORTED"
+        )
+        safe_casts = value["safe_casts"]
+        if not isinstance(safe_casts, Mapping) or any(
+            not isinstance(column, str) for column in safe_casts
+        ):
+            raise OperationRegistryError(
+                "OPERATION_PARAMETERS", f"{path}.safe_casts", "must be an object"
+            )
+        for column, target in safe_casts.items():
+            _text(column, f"{path}.safe_casts")
+            _choice(target, {"decimal"}, f"{path}.safe_casts.{column}")
+        _choice(
+            value["grain_policy"], {"preserve"}, f"{path}.grain_policy", code="UNION_UNSUPPORTED"
+        )
+    elif name == "source":
+        _text(value["source"], f"{path}.source")
+        _column_units(value.get("column_units"), f"{path}.column_units")
+    elif name == "filter":
+        _choice(value["null_policy"], {"drop"}, f"{path}.null_policy")
+        _predicate(value["predicate"], f"{path}.predicate")
+    elif name == "project":
+        _text_list(value["columns"], f"{path}.columns")
+    elif name == "rename":
+        mappings = value["mappings"]
+        if not isinstance(mappings, Mapping) or not mappings:
+            raise OperationRegistryError(
+                "OPERATION_PARAMETERS", f"{path}.mappings", "must be a non-empty object"
+            )
+        targets = []
+        for source, target in mappings.items():
+            _text(source, f"{path}.mappings")
+            targets.append(_text(target, f"{path}.mappings.{source}"))
+        if len(targets) != len(set(targets)):
+            raise OperationRegistryError(
+                "OPERATION_PARAMETERS", f"{path}.mappings", "targets must be unique"
+            )
+    elif name == "cast":
+        _choice(value["overflow_policy"], {"reject"}, f"{path}.overflow_policy")
+        columns = value["columns"]
+        if not isinstance(columns, Mapping) or not columns:
+            raise OperationRegistryError(
+                "OPERATION_PARAMETERS", f"{path}.columns", "must be a non-empty object"
+            )
+        for column, kind in columns.items():
+            if not isinstance(column, str):
+                raise OperationRegistryError(
+                    "OPERATION_PARAMETERS", f"{path}.columns", "column names must be text"
+                )
+            _choice(
+                kind,
+                {
+                    "boolean",
+                    "int64",
+                    "float64",
+                    "string",
+                    "date",
+                    "timestamp_utc",
+                    "decimal",
+                },
+                f"{path}.columns.{column}",
+            )
+    elif name == "deduplicate":
+        _text_list(value["keys"], f"{path}.keys")
+        _sort_keys(value["authority"], f"{path}.authority")
+        _choice(value["null_key_policy"], {"reject"}, f"{path}.null_key_policy")
+        _choice(value["tie_policy"], {"stable_first"}, f"{path}.tie_policy")
+    elif name == "sort":
+        _sort_keys(value["keys"], f"{path}.keys")
+    elif name == "derive":
+        _choice(value["overflow_policy"], {"reject"}, f"{path}.overflow_policy")
+        _choice(value["null_policy"], {"propagate"}, f"{path}.null_policy")
+        expressions = value["expressions"]
+        if not isinstance(expressions, Mapping) or not expressions:
+            raise OperationRegistryError(
+                "OPERATION_PARAMETERS", f"{path}.expressions", "must be a non-empty object"
+            )
+        for output, specification in expressions.items():
+            _text(output, f"{path}.expressions")
+            if not isinstance(specification, Mapping):
+                raise OperationRegistryError(
+                    "OPERATION_PARAMETERS", f"{path}.expressions.{output}", "must be an object"
+                )
+            fields = set(specification)
+            if (
+                not {"output_type", "expression"}
+                <= fields
+                <= {
+                    "output_type",
+                    "expression",
+                    "output_unit",
+                }
+            ):
+                raise OperationRegistryError(
+                    "OPERATION_PARAMETERS",
+                    f"{path}.expressions.{output}",
+                    "fields must be output_type and expression, and may add output_unit",
+                )
+            if "output_unit" in specification:
+                # A unit is a claim about a quantity, so the column has to hold one. Text and dates
+                # do not, and a unit on one of them would leave the merge gate downstream
+                # arbitrating units on strings.
+                if specification["output_type"] not in {"int64", "float64", "decimal"}:
+                    raise OperationRegistryError(
+                        "OPERATION_PARAMETERS",
+                        f"{path}.expressions.{output}.output_unit",
+                        "only an int64, float64 or decimal column carries a unit",
+                    )
+                _unit_code(specification["output_unit"], f"{path}.expressions.{output}.output_unit")
+            _choice(
+                specification["output_type"],
+                {
+                    "boolean",
+                    "int64",
+                    "float64",
+                    "string",
+                    "date",
+                    "timestamp_utc",
+                    "decimal",
+                },
+                f"{path}.expressions.{output}.output_type",
+            )
+            _derive_expression(
+                specification["expression"], f"{path}.expressions.{output}.expression"
+            )
+        _divide_policies(value, expressions, path)
+    elif name == "unpivot":
+        # Wide to long. The columns that carry values are named in the plan and are never read
+        # out of the data, so the output schema is a function of the recipe alone: the columns
+        # the plan does not name stay as they are, and exactly two new columns are appended.
+        # ``value_type`` is declared for the same reason ``derive`` declares ``output_type``.
+        # Inferring it from the wide columns would have made the long column's type depend on the
+        # data: a refresh in which every declared column happened to be empty would type it
+        # differently from the last one, off the same recipe.
+        value_columns = _text_list(value["value_columns"], f"{path}.value_columns")
+        name_column = _text(value["name_column"], f"{path}.name_column")
+        value_column = _text(value["value_column"], f"{path}.value_column")
+        _choice(
+            value["value_type"],
+            {
+                "boolean",
+                "int64",
+                "float64",
+                "string",
+                "date",
+                "timestamp_utc",
+                "decimal",
+            },
+            f"{path}.value_type",
+        )
+        _choice(value["null_policy"], {"retain"}, f"{path}.null_policy")
+        if name_column == value_column:
+            raise OperationRegistryError(
+                "OPERATION_PARAMETERS",
+                f"{path}.value_column",
+                "must differ from name_column",
+            )
+        reused = sorted({name_column, value_column} & set(value_columns))
+        if reused:
+            raise OperationRegistryError(
+                "OPERATION_PARAMETERS",
+                f"{path}.value_columns",
+                f"output columns must be new names: {reused}",
+            )
+    elif name == "aggregate":
+        _text_list(value["group_by"], f"{path}.group_by", empty=True)
+        _measures(value["measures"], f"{path}.measures")
+        _choice(value["empty_group_policy"], {"omit"}, f"{path}.empty_group_policy")
+    elif name == "resample":
+        fixed = {
+            "origin": {"unix_epoch"},
+            "timezone": {"UTC"},
+            "ambiguity_policy": {"reject"},
+            "nonexistent_policy": {"reject"},
+            "closure": {"left"},
+            "label": {"left"},
+            "missing_period_policy": {"omit"},
+        }
+        for field, allowed in fixed.items():
+            _choice(value[field], allowed, f"{path}.{field}", code="RESAMPLE_UNSUPPORTED")
+        _text_list(value["group_by"], f"{path}.group_by", empty=True)
+        _text(value["event_time"], f"{path}.event_time")
+        _measures(value["aggregates"], f"{path}.aggregates")
+        if (
+            isinstance(value["duration_seconds"], bool)
+            or not isinstance(value["duration_seconds"], int)
+            or value["duration_seconds"] <= 0
+        ):
+            raise OperationRegistryError(
+                "OPERATION_PARAMETERS", f"{path}.duration_seconds", "must be a positive integer"
+            )
+    elif name == "prediction_label":
+        _text_list(value["partition_by"], f"{path}.partition_by", empty=True)
+        for field in ("time_column", "source_column", "output_column"):
+            _text(value[field], f"{path}.{field}")
+        if value["time_column"] == value["source_column"] or {
+            value["time_column"],
+            value["source_column"],
+        } & set(value["partition_by"]):
+            raise OperationRegistryError(
+                "OPERATION_PARAMETERS",
+                f"{path}.partition_by",
+                "partition, time, and source-value columns must be distinct",
+            )
+        if value["output_column"] in {
+            value["time_column"],
+            value["source_column"],
+            *value["partition_by"],
+        }:
+            raise OperationRegistryError(
+                "OPERATION_PARAMETERS",
+                f"{path}.output_column",
+                "must be a new column distinct from the keys and source value",
+            )
+        _positive_int(value["horizon_days"], f"{path}.horizon_days", maximum=3_650)
+        _choice(value["null_key_policy"], {"reject"}, f"{path}.null_key_policy")
+        _choice(value["duplicate_key_policy"], {"reject"}, f"{path}.duplicate_key_policy")
+        _choice(value["missing_target_policy"], {"drop"}, f"{path}.missing_target_policy")
+        _choice(value["null_target_policy"], {"drop"}, f"{path}.null_target_policy")
+        _choice(value["boundary_policy"], {"drop"}, f"{path}.boundary_policy")
+    elif name == "date_add_days":
+        date_column = _text(value["date_column"], f"{path}.date_column")
+        output_column = _text(value["output_column"], f"{path}.output_column")
+        if date_column == output_column:
+            raise OperationRegistryError(
+                "DATE_ADD_DAYS_COLUMN",
+                f"{path}.output_column",
+                "must be a new column distinct from date_column",
+            )
+        _date_add_days_offset(value["days"], f"{path}.days")
+        _choice(value["null_policy"], {"propagate"}, f"{path}.null_policy")
+        _choice(value["overflow_policy"], {"reject"}, f"{path}.overflow_policy")
+    elif name == "join":
+        _choice(value["kind"], set(GRAPH_JOIN_KINDS), f"{path}.kind")
+        _choice(value["cardinality"], {"one_to_one", "many_to_one"}, f"{path}.cardinality")
+        _choice(value["null_key_policy"], {"reject"}, f"{path}.null_key_policy")
+        _choice(
+            value["unmatched_policy"], {"preserve", "reject", "drop"}, f"{path}.unmatched_policy"
+        )
+        # An anti join is the unmatched left rows and nothing else, so ``preserve`` is the only
+        # unmatched policy that describes it: dropping the unmatched rows would leave no output,
+        # and rejecting them would refuse every anti join that found anything.
+        if (value["kind"], value["unmatched_policy"]) not in {
+            ("left", "preserve"),
+            ("left", "reject"),
+            ("inner", "drop"),
+            ("inner", "reject"),
+            ("anti", "preserve"),
+        }:
+            raise OperationRegistryError(
+                "OPERATION_PARAMETERS",
+                f"{path}.unmatched_policy",
+                "unmatched policy is incompatible with join kind",
+            )
+        _text_list(value["on"], f"{path}.on")
+
+
+_OPERATIONS = {
+    # ``column_units`` is optional so a plan sealed before units were declarable keeps validating
+    # unchanged, in the same style as the conditional denominator policies below. A source that
+    # declares nothing is untouched by both unit gates; a source that declares a column's unit is
+    # what gives the gates something to check.
+    "source": _operation(
+        "source",
+        (0, 0),
+        {"source"},
+        {"column_units"},
+        verdict="Admitted",
+        example="load one snapshotted delimited file",
+        rationale="leaf, no choice",
+    ),
+    "union": _operation(
+        "union",
+        (2, 64),
+        {"column_matching", "safe_casts", "grain_policy"},
+        verdict="Admitted",
+        example="stack twelve monthly files",
+        rationale="same facts, one table",
+    ),
+    "filter": _operation(
+        "filter",
+        (1, 1),
+        {"predicate", "null_policy"},
+        verdict="Admitted",
+        example="drop rows before 2010",
+        rationale="selects, invents nothing",
+    ),
+    "project": _operation(
+        "project",
+        (1, 1),
+        {"columns"},
+        verdict="Admitted",
+        example="drop forty unused columns",
+        rationale="selection",
+    ),
+    "rename": _operation(
+        "rename",
+        (1, 1),
+        {"mappings"},
+        verdict="Admitted",
+        example="one supplier's column name becomes the declared one",
+        rationale="label only",
+    ),
+    "cast": _operation(
+        "cast",
+        (1, 1),
+        {"columns", "overflow_policy"},
+        verdict="Admitted",
+        example="text digits become a whole number",
+        rationale="type fix",
+    ),
+    # The two denominator policies are optional in the parameter table and mandatory in the
+    # semantics: ``_divide_policies`` requires both exactly when an expression divides and refuses
+    # both when none does. Keeping them out of the required set is what lets a ``derive`` node
+    # sealed before division existed keep validating unchanged.
+    "derive": _operation(
+        "derive",
+        (1, 1),
+        {"expressions", "overflow_policy", "null_policy"},
+        set(DIVIDE_POLICIES),
+        verdict="Admitted, with a limit",
+        example="the year of a timestamp",
+        rationale="see the limit below",
+    ),
+    "deduplicate": _operation(
+        "deduplicate",
+        (1, 1),
+        {"keys", "authority", "null_key_policy", "tie_policy"},
+        verdict="Admitted",
+        example="two feeds report one reading, keep the declared authority",
+        rationale="resolves a conflict that was declared, not noticed",
+    ),
+    "sort": _operation(
+        "sort",
+        (1, 1),
+        {"keys"},
+        verdict="Admitted",
+        example="order by facility, then date",
+        rationale="presentation",
+    ),
+    "aggregate": _operation(
+        "aggregate",
+        (1, 1),
+        {"group_by", "measures", "empty_group_policy"},
+        verdict="Admitted",
+        example="daily total per facility",
+        rationale="declares grain",
+    ),
+    "resample": _operation(
+        "resample",
+        (1, 1),
+        {
+            "group_by",
+            "event_time",
+            "duration_seconds",
+            "origin",
+            "timezone",
+            "ambiguity_policy",
+            "nonexistent_policy",
+            "closure",
+            "label",
+            "aggregates",
+            "missing_period_policy",
+        },
+        verdict="Admitted",
+        example="hourly readings become daily means",
+        rationale="grain, in time",
+    ),
+    # Retired. It fails the admission contract in ``docs/TRANSFORMS.md``: ``horizon_days`` is a
+    # claim about what somebody intends to predict, which is the modeling side of the line. It
+    # stays in the registry with ``availability="retired"`` so a Build already sealed with it, and
+    # a Recipe already approved with it, keep resolving -- both re-parse their stored plan through
+    # this table to verify. Newly authored bytes are refused; see
+    # ``local_contracts.refuse_retired_operations``.
+    "prediction_label": _operation(
+        "prediction_label",
+        (1, 1),
+        {
+            "partition_by",
+            "time_column",
+            "source_column",
+            "output_column",
+            "horizon_days",
+            "null_key_policy",
+            "duplicate_key_policy",
+            "missing_target_policy",
+            "null_target_policy",
+            "boundary_policy",
+        },
+        availability=RETIRED,
+        verdict="Retired",
+        example="an outcome thirty days ahead",
+        rationale="the horizon is the analyst's modeling choice",
+    ),
+    "join": _operation(
+        "join",
+        (2, 2),
+        {"kind", "cardinality", "on", "null_key_policy", "unmatched_policy"},
+        verdict="Admitted",
+        example="readings joined to facility metadata",
+        rationale="combines, invents nothing",
+    ),
+    # New vocabulary is appended rather than inserted: the order below is contract-significant,
+    # so an addition extends the tuple and never rewrites the part of it that already shipped.
+    "unpivot": _operation(
+        "unpivot",
+        (1, 1),
+        {"value_columns", "name_column", "value_column", "value_type", "null_policy"},
+        verdict="Admitted",
+        example="one column per year becomes a year column and a value column",
+        rationale="reshape only",
+    ),
+    # This is a row-local date correction, not a lag, lead, target, or window: each output date
+    # comes from exactly the date on its own input row plus one fixed offset declared in the plan.
+    # It is appended because graph-vocabulary order is contract-significant.
+    "date_add_days": _operation(
+        "date_add_days",
+        (1, 1),
+        {"date_column", "output_column", "days", "null_policy", "overflow_policy"},
+        verdict="Admitted",
+        example="a rate date becomes its next calendar availability date",
+        rationale="fixed row-local calendar correction",
+    ),
+}
+
+# Tuple order is contract-significant and deliberately follows the graph vocabulary.
+OPERATION_REGISTRY: Mapping[str, GraphOperation] = MappingProxyType(_OPERATIONS)
+
+# The retired names, read off the table rather than restated beside it.
+RETIRED_OPERATIONS: frozenset[str] = frozenset(
+    name for name, operation in _OPERATIONS.items() if operation.availability == RETIRED
+)
+
+
+def resolve_operation(name: Any, version: Any) -> GraphOperation:
+    if not isinstance(name, str) or not isinstance(version, str):
+        raise OperationRegistryError(
+            "OPERATION_COORDINATE", "plan.nodes.operation", "name and version must be strings"
+        )
+    if name in {"window_target", "lag", "lead", "rolling"}:
+        raise OperationRegistryError(
+            "WINDOW_TARGET_UNSUPPORTED",
+            "plan.nodes.operation",
+            "generic window, lag, lead, and rolling operations are outside local-operations.v2",
+        )
+    operation = OPERATION_REGISTRY.get(name)
+    if operation is None:
+        raise OperationRegistryError(
+            "OPERATION_UNSUPPORTED", "plan.nodes.operation", f"operation {name!r} is not registered"
+        )
+    if version != operation.version:
+        raise OperationRegistryError(
+            "OPERATION_VERSION_UNSUPPORTED",
+            "plan.nodes.operation_version",
+            f"operation {name!r} requires version {operation.version!r}",
+        )
+    return operation
+
+
+def _freeze_json(value: Any, path: str, *, depth: int, budget: list[int]) -> Any:
+    if depth > MAX_PARAMETER_DEPTH:
+        raise OperationRegistryError("OPERATION_PARAMETERS", path, "nesting is too deep")
+    budget[0] += 1
+    if budget[0] > MAX_PARAMETER_MEMBERS:
+        raise OperationRegistryError("OPERATION_PARAMETERS", path, "contains too many members")
+    if value is None or type(value) in {bool, int, str}:
+        return value
+    if type(value) is float:
+        raise OperationRegistryError(
+            "OPERATION_PARAMETERS", path, "floating JSON numbers are not contract values"
+        )
+    if isinstance(value, list):
+        return (
+            "$array",
+            tuple(
+                _freeze_json(item, f"{path}[{index}]", depth=depth + 1, budget=budget)
+                for index, item in enumerate(value)
+            ),
+        )
+    if isinstance(value, Mapping) and all(isinstance(key, str) for key in value):
+        return (
+            "$object",
+            tuple(
+                (
+                    key,
+                    _freeze_json(value[key], f"{path}.{key}", depth=depth + 1, budget=budget),
+                )
+                for key in sorted(value)
+            ),
+        )
+    raise OperationRegistryError(
+        "OPERATION_PARAMETERS", path, "must contain only closed JSON-compatible values"
+    )
+
+
+def thaw_parameter(value: Any) -> Any:
+    """Return the canonical JSON representation of one frozen parameter value."""
+
+    if isinstance(value, tuple):
+        if len(value) == 2 and value[0] == "$array" and isinstance(value[1], tuple):
+            return [thaw_parameter(item) for item in value[1]]
+        if len(value) == 2 and value[0] == "$object" and isinstance(value[1], tuple):
+            return {key: thaw_parameter(item) for key, item in value[1]}
+        if all(
+            isinstance(item, tuple) and len(item) == 2 and isinstance(item[0], str)
+            for item in value
+        ):
+            return {key: thaw_parameter(item) for key, item in value}
+        return [thaw_parameter(item) for item in value]
+    return value
+
+
+__all__ = [
+    "DERIVE_EXPRESSION_ARITY",
+    "DERIVE_EXPRESSION_VARIADIC",
+    "DIVIDE_POLICIES",
+    "EXECUTABLE",
+    "GRAPH_JOIN_KINDS",
+    "GRAPH_OPERATION_CONTRACT_VERSION",
+    "GRAPH_OPERATION_VERSION",
+    "MAX_DATE_ADD_DAYS",
+    "OPERATION_REGISTRY",
+    "RETIRED",
+    "RETIRED_OPERATIONS",
+    "AdmissionRow",
+    "GraphOperation",
+    "OperationRegistryError",
+    "resolve_operation",
+    "thaw_parameter",
+]