mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/unit_flow.py

@@ -0,0 +1,927 @@
+"""Two deterministic unit gates, read off the plan without touching a row of data.
+
+A declared unit used to be a claim nobody checked. The agent wrote the unit, the agent wrote the
+arithmetic that converted it, and nothing compared the two — so a plan could stack Celsius on
+Fahrenheit, or multiply centimetres by ten and call the result metres, and the Build would carry an
+auditable statement that was simply wrong.
+
+This module closes both, from the plan alone:
+
+**Commensurability.** Where an operation merges one column from two places — a ``union`` stacking
+same-named columns, a ``join`` bringing two tables together, an ``unpivot`` folding several columns
+into one — the declared units on each side must be the same unit. Disagreeing in dimension is one
+refusal; agreeing in dimension while disagreeing in unit, with no conversion written between them,
+is another.
+
+**Conversion verification.** Where a ``derive`` declares what unit its output is in, and its
+expression is a scaling of exactly one column whose unit is also declared, the arithmetic must be
+exactly the map the grammar derives between those two units — coefficient for coefficient. A
+conversion that multiplies Celsius by 9/5 and forgets the 32 is refused, because the check compares
+the pair rather than a factor.
+
+Both gates are silent on a column with no declared unit. That is what keeps this from being
+retroactive: a plan that declares nothing is exactly as valid as it was.
+
+The whole analysis is static. It reads node parameters, never a source file, so it is a function of
+the sealed plan and cannot change with the data.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from fractions import Fraction
+from typing import TYPE_CHECKING, Any, Final
+
+from mostlyright.data_harness.operation_registry import thaw_parameter
+from mostlyright.data_harness.units import (
+    COUNT_UNIT_CODE,
+    Unit,
+    UnitError,
+    commensurable,
+    conversion,
+    dimension_signature,
+    parse_unit,
+    resolve_declared_unit,
+    same_unit,
+)
+
+if TYPE_CHECKING:  # pragma: no cover - imported for typing only, and the other way at run time.
+    from mostlyright.data_harness.local_contracts import GraphDatasetPlan, GraphNode
+
+#: What an aggregate measure does to the unit of the column it reads. Everything that returns one
+#: of the values it was given keeps that value's unit; a count returns how many there were, which
+#: is a count of rows rather than a quantity of whatever was in them.
+_MEASURE_KEEPS_UNIT = frozenset({"sum", "min", "max", "mean", "first", "last"})
+
+#: Every operation the walk below models, and what it does to a claim. The set is closed and
+#: compared against the live registry by ``tests/test_unit_gates.py``: an operation added to the
+#: vocabulary has to be classified here before it ships, rather than falling through to
+#: "carry everything unchanged" and quietly taking a claim somewhere it does not belong.
+UNIT_PASS_THROUGH_OPERATIONS = frozenset({"cast", "sort", "deduplicate"})
+UNIT_MODELLED_OPERATIONS = (
+    frozenset(
+        {
+            "source",
+            "union",
+            "join",
+            "rename",
+            "project",
+            "derive",
+            "aggregate",
+            "resample",
+            "unpivot",
+            "prediction_label",
+            "date_add_days",
+            "filter",
+        }
+    )
+    | UNIT_PASS_THROUGH_OPERATIONS
+)
+
+
+#: What each derive-expression operator does to a declared unit, classified so the closure test can
+#: hold this set equal to the expression vocabulary. ``if`` and the arithmetic carry a unit through;
+#: everything else reads a date part or rewrites text, and its result is not a measured quantity.
+UNIT_ARITHMETIC_OPERATORS = frozenset({"add", "subtract", "multiply", "divide"})
+UNIT_UNMEASURED_OPERATORS = frozenset(
+    {"concat", "trim", "case_fold", "year", "month", "day", "hour"}
+)
+UNIT_MODELLED_EXPRESSIONS = UNIT_ARITHMETIC_OPERATORS | UNIT_UNMEASURED_OPERATORS | {"if"}
+
+
+class UnitFlowError(Exception):
+    """A typed unit-consistency refusal naming the exact plan path that carries it."""
+
+    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 _Affine:
+    """One expression reduced to ``column * scale + offset``, or to a bare constant.
+
+    ``column`` is ``None`` for an expression made only of literals. Anything the reduction cannot
+    express -- a quotient by a column, a conditional, a date part, text -- is not one of these at
+    all, and the caller gets ``None``.
+    """
+
+    column: str | None
+    scale: Fraction
+    offset: Fraction
+
+
+def _affine(column: str | None, scale: Fraction, offset: Fraction) -> _Affine:
+    """Build a reduction, reading a term that scales to zero as the constant it is.
+
+    ``y - y`` and ``y * 0`` name a column and contribute nothing to the value, so carrying the name
+    would make ``x + (y - y)`` look like an expression over two columns and stop the reduction --
+    which is one token's worth of hiding for any conversion at all.
+    """
+
+    return _Affine(column=column if scale else None, scale=scale, offset=offset)
+
+
+def _constant(value: Fraction) -> _Affine:
+    return _affine(None, Fraction(0), value)
+
+
+def _reduce(expression: Any) -> _Affine | None:
+    """Reduce one derive expression to an affine map over at most one column.
+
+    Only the integer literals the expression grammar admits appear here, so every coefficient is an
+    exact rational and the comparison against a grammar-derived conversion is exact too. That is
+    not an accident of this function: the plan contract has no decimal literal, so a conversion by
+    9/5 is written as a multiply and a divide, and both are exact.
+    """
+
+    if not isinstance(expression, Mapping):
+        return None
+    keys = set(expression)
+    if keys == {"column"}:
+        column = expression["column"]
+        if not isinstance(column, str):
+            return None
+        return _affine(column, Fraction(1), Fraction(0))
+    if keys == {"literal"}:
+        literal = expression["literal"]
+        if type(literal) is not int:
+            return None
+        return _constant(Fraction(literal))
+    operation = expression.get("op")
+    arguments = expression.get("args")
+    if not isinstance(arguments, list):
+        # Every conditional is resolved to one branch before this runs, so nothing reaching here
+        # has ``condition``/``then``/``else`` in place of ``args``.
+        return None
+    if operation in {"add", "subtract"} and len(arguments) == 2:
+        left = _reduce(arguments[0])
+        right = _reduce(arguments[1])
+        if left is None or right is None:
+            return None
+        sign = 1 if operation == "add" else -1
+        if left.column is not None and right.column is not None:
+            if left.column != right.column:
+                return None
+            column = left.column
+        else:
+            column = left.column or right.column
+        scale = left.scale + sign * right.scale
+        return _affine(column, scale, left.offset + sign * right.offset)
+    if operation == "multiply" and len(arguments) == 2:
+        left = _reduce(arguments[0])
+        right = _reduce(arguments[1])
+        if left is None or right is None:
+            return None
+        if left.column is not None and right.column is not None:
+            return None
+        varying, constant = (left, right) if left.column is not None else (right, left)
+        if (
+            constant.column is not None
+        ):  # pragma: no cover - one side is constant by the test above.
+            return None
+        factor = constant.offset
+        return _affine(varying.column, varying.scale * factor, varying.offset * factor)
+    if operation == "divide" and len(arguments) == 2:
+        numerator = _reduce(arguments[0])
+        denominator = _reduce(arguments[1])
+        if numerator is None or denominator is None or denominator.column is not None:
+            return None
+        if denominator.offset == 0:
+            return None
+        return _affine(
+            numerator.column,
+            numerator.scale / denominator.offset,
+            numerator.offset / denominator.offset,
+        )
+    return None
+
+
+@dataclass(frozen=True)
+class _Measured:
+    """What a subtree's value is measured in, and whether the code is exactly that.
+
+    ``exact`` is false where an operand has been scaled: multiplying a length by two leaves a
+    length, so the dimension is still known, but the number is no longer in the unit the column
+    declared and no code names what it is in. Both halves are useful -- the dimension catches a
+    length added to a time however either side was scaled, and the code catches Celsius added to
+    Fahrenheit.
+    """
+
+    unit: Unit
+    exact: bool
+
+
+class _Unplaced:
+    """A subtree the walk could not read: not a number, and not a unit it can name.
+
+    Keeping this apart from ``None`` is the whole of one round's finding. A bare number
+    contributes no unit and lets the other operand speak for the result; a subtree nobody could
+    place contributes an unknown one, and letting the other operand speak for the result there is
+    how ``declared + undeclared`` came to be admitted as exactly the declared unit.
+    """
+
+    __slots__ = ()
+
+
+UNPLACED: Final = _Unplaced()
+
+
+def _measured(
+    expression: Any, incoming: Mapping[str, Unit], path: str
+) -> _Measured | _Unplaced | None:
+    """Walk one expression and refuse an addition whose two sides are not measuring the same thing.
+
+    Adding metres to seconds, or Celsius to Fahrenheit, is wrong in the plan rather than in the
+    data, and it is wrong before anything is said about the result. Without this the reduction
+    above simply declines to model such an expression, the declared output unit is taken at its
+    word, and an invented claim walks downstream past the merge gate -- which is the failure this
+    module exists to stop, reached by arithmetic instead of by a stack.
+
+    A literal is not a unit. It is a bare number whose meaning comes from what it is added to, so
+    ``(x * 9 + 160) / 5`` is a conversion rather than a mismatch. What this walk cannot place it
+    leaves unplaced rather than guessing at.
+    """
+
+    if not isinstance(expression, Mapping):
+        return UNPLACED
+    keys = set(expression)
+    if keys == {"column"}:
+        column = expression["column"]
+        if not isinstance(column, str):
+            return UNPLACED
+        unit = incoming.get(column)
+        return _Measured(unit=unit, exact=True) if unit is not None else UNPLACED
+    if keys == {"literal"}:
+        # A bare number. It contributes no unit of its own and takes the one it is used with.
+        return None
+    operation = expression.get("op")
+    if operation == "if":
+        # Both branches are values of the same column, so they answer the same question, and a
+        # mismatch inside either is a mismatch. Walking only ``args`` would have left every
+        # conditional unexamined -- which is a hole the width of one wrapper.
+        _predicate_units(expression.get("condition"), incoming, path)
+        return _combine(
+            _measured(expression.get("then"), incoming, path),
+            _measured(expression.get("else"), incoming, path),
+            path=path,
+            verb="offers",
+            fix="convert one to the other before choosing between them",
+        )
+    arguments = expression.get("args")
+    if not isinstance(arguments, list):
+        return UNPLACED
+    # Every argument is walked for its own refusals before the operation is dispatched on, so a
+    # mismatch does not become invisible by sitting inside an operator of a different arity. It
+    # was invisible inside a one-argument ``concat`` until this loop existed.
+    operands = [_measured(argument, incoming, path) for argument in arguments]
+    if len(arguments) != 2:
+        # A concatenation, a text rewrite, a date part. Its arguments were walked for their own
+        # refusals; what it produces is not a quantity this walk can name.
+        return UNPLACED
+    left, right = operands
+    if operation in {"add", "subtract"}:
+        return _combine(
+            left,
+            right,
+            path=path,
+            verb="adds",
+            fix="convert one to the other before adding them",
+            additive=True,
+        )
+    if operation in {"multiply", "divide"}:
+        if isinstance(left, _Unplaced) or isinstance(right, _Unplaced):
+            return UNPLACED
+        if left is not None and right is not None:
+            # A product of two units is a new unit, and nothing here multiplies units together.
+            return UNPLACED
+        scaled = left if right is None else right
+        if scaled is None or (operation == "divide" and left is None):
+            return UNPLACED
+        scalar = _literal(arguments[1] if right is None else arguments[0])
+        if scalar is None:
+            # The other operand is a column with no declared unit, not a number. Metres per second
+            # is metres divided by a column, and it is neither metres nor a mistake -- claiming it
+            # kept the numerator's dimension would refuse the plainest rate there is.
+            return UNPLACED
+        # Scaling by a number leaves the dimension and takes the code: what a scaled length is in
+        # depends on the scale, and no code here names it. Scaling by one is the exception, and it
+        # is worth the line -- a no-op multiply is otherwise a one-token way to hide an operand.
+        return _Measured(unit=scaled.unit, exact=scaled.exact and scalar == 1)
+    return UNPLACED
+
+
+#: The comparisons a predicate can make between two values. Everything else a predicate does is
+#: about presence or membership, where one side is not a measured quantity at all.
+_COMPARISONS = frozenset({"eq", "ne", "lt", "le", "gt", "ge"})
+
+
+def _predicate_units(predicate: Any, incoming: Mapping[str, Unit], path: str) -> None:
+    """Refuse a comparison between two columns declared in different units.
+
+    Asking whether a length in metres exceeds one in feet is the same mistake as stacking them,
+    and it is one the plan can see. A predicate is not an expression -- it yields a truth rather
+    than a quantity -- so nothing is returned; the walk is here for the refusal alone.
+    """
+
+    if not isinstance(predicate, Mapping):
+        return
+    operation = predicate.get("op")
+    if operation in {"and", "or"}:
+        for argument in predicate.get("args") or []:
+            _predicate_units(argument, incoming, path)
+        return
+    if operation == "not":
+        _predicate_units(predicate.get("arg"), incoming, path)
+        return
+    if operation not in _COMPARISONS:
+        return
+    _combine(
+        _measured(predicate.get("left"), incoming, path),
+        _measured(predicate.get("right"), incoming, path),
+        path=path,
+        verb="compares",
+        fix="convert one to the other before comparing them",
+    )
+
+
+def _literal(expression: Any) -> int | None:
+    """The whole number an operand names, where it names one and nothing else."""
+
+    if not isinstance(expression, Mapping) or set(expression) != {"literal"}:
+        return None
+    value = expression["literal"]
+    return value if type(value) is int else None
+
+
+def _combine(
+    left: _Measured | _Unplaced | None,
+    right: _Measured | _Unplaced | None,
+    *,
+    path: str,
+    verb: str,
+    fix: str,
+    additive: bool = False,
+) -> _Measured | _Unplaced | None:
+    """Hold two operands of one arithmetic to measuring the same thing, or refuse the pair."""
+
+    if isinstance(left, _Unplaced) or isinstance(right, _Unplaced):
+        # One side could not be read, so nothing is settled about the pair. Returning the side that
+        # could would say the result is in that unit, which is the claim nobody established.
+        return UNPLACED
+    if left is None or right is None:
+        settled = left if right is None else right
+        if additive and isinstance(settled, _Measured) and settled.unit.affine:
+            # Twenty degrees Celsius plus five is not twenty-five degrees Celsius: the number
+            # moved along an offset scale, and no code names where it landed.
+            return UNPLACED
+        return settled
+    if not commensurable(left.unit, right.unit):
+        raise UnitFlowError(
+            "UNIT_DIMENSION_MISMATCH",
+            path,
+            f"this expression {verb} a value declared {_describe(left.unit)} and one declared "
+            f"{_describe(right.unit)}; the two do not measure the same kind of thing",
+        )
+    if left.exact and right.exact and not same_unit(left.unit, right.unit):
+        raise UnitFlowError(
+            "UNIT_CONVERSION_MISSING",
+            path,
+            f"this expression {verb} a value declared {left.unit.code!r} and one declared "
+            f"{right.unit.code!r}; {fix}",
+        )
+    if additive and (left.unit.affine or right.unit.affine):
+        # Twenty degrees Celsius plus twenty is not forty degrees Celsius. An offset scale does not
+        # add, so the pair settles nothing -- but only after the two have been held to being the
+        # same unit, which is a mismatch worth naming whether or not the sum means anything.
+        return UNPLACED
+    return _Measured(unit=left.unit, exact=left.exact and right.exact)
+
+
+def _parameters(node: GraphNode) -> dict[str, Any]:
+    return dict(node.parameters)
+
+
+def _declared(code: Any) -> Unit | None:
+    if not isinstance(code, str):
+        return None
+    try:
+        return resolve_declared_unit(code)
+    except UnitError:  # pragma: no cover - the registry resolved this code before it got here.
+        return None
+
+
+def _describe(unit: Unit) -> str:
+    return f"{unit.code!r} ({dimension_signature(unit)})"
+
+
+def _merge(
+    left: Mapping[str, Unit],
+    right: Mapping[str, Unit],
+    *,
+    path: str,
+    left_label: str,
+    right_label: str,
+) -> dict[str, Unit]:
+    """Combine two column-to-unit environments, refusing a column the two disagree about.
+
+    A column declared on one side only is carried across unchanged. That is the deliberate part:
+    the gate says nothing about a claim nobody made.
+    """
+
+    merged = dict(left)
+    for column, unit in right.items():
+        held = left.get(column)
+        if held is None:
+            merged[column] = unit
+            continue
+        if not commensurable(held, unit):
+            raise UnitFlowError(
+                "UNIT_DIMENSION_MISMATCH",
+                path,
+                f"{left_label} declares {column!r} as {_describe(held)} and {right_label} declares "
+                f"it as {_describe(unit)}; the two do not measure the same kind of thing",
+            )
+        if not same_unit(held, unit):
+            raise UnitFlowError(
+                "UNIT_CONVERSION_MISSING",
+                path,
+                f"{left_label} declares {column!r} as {held.code!r} and {right_label} declares it "
+                f"as {unit.code!r}; convert one to the other before merging them",
+            )
+    return merged
+
+
+def _source_units(node: GraphNode) -> dict[str, Unit]:
+    declared = thaw_parameter(_parameters(node).get("column_units"))
+    if not isinstance(declared, Mapping):
+        return {}
+    units: dict[str, Unit] = {}
+    for column, code in declared.items():
+        unit = _declared(code)
+        if unit is not None:
+            units[column] = unit
+    return units
+
+
+def _derive_units(node: GraphNode, incoming: Mapping[str, Unit], *, index: int) -> dict[str, Unit]:
+    """Carry the input units through, add every declared output unit, and verify the arithmetic."""
+
+    units = dict(incoming)
+    expressions = thaw_parameter(_parameters(node).get("expressions"))
+    if not isinstance(expressions, Mapping):  # pragma: no cover - the registry shaped this already.
+        return units
+    for output, specification in expressions.items():
+        if not isinstance(specification, Mapping):  # pragma: no cover - same.
+            continue
+        path = f"plan.nodes[{index}].parameters.expressions.{output}.expression"
+        measured = _measured(specification.get("expression"), incoming, path)
+        declared_code = specification.get("output_unit")
+        if declared_code is None:
+            # No claim about this column, so it carries none from here on. A later merge cannot be
+            # fooled by it, because a column with no declared unit is invisible to that gate.
+            units.pop(output, None)
+            continue
+        target = _declared(declared_code)
+        if target is None:  # pragma: no cover - the registry resolved this code before it got here.
+            continue
+        node_path = f"plan.nodes[{index}].parameters.expressions.{output}"
+        _admit_declared_output(
+            specification.get("expression"),
+            incoming,
+            measured,
+            target,
+            node_path,
+            declared_code=declared_code,
+        )
+        units[output] = target
+    return units
+
+
+#: How many arithmetics one expression may branch into before the conversion in it stops being
+#: checkable. A conversion guarded against an absent value branches into two, and a sum of eight
+#: guarded readings into 256; nothing anybody writes reaches past that, and an expression that does
+#: is refused rather than passed over, because passing it over would make nesting the way to switch
+#: the check off.
+MAX_BRANCH_VARIANTS: Final = 1024
+
+#: Where a value lives inside an expression. A conditional's ``condition`` is deliberately not
+#: among them: a predicate decides which value is taken, never what that value is measured in, so a
+#: column read only there says nothing about the result's unit and must not be required to declare
+#: one. Everything else the grammar admits is a value.
+_VALUE_POSITIONS = ("then", "else")
+
+
+def _value_columns(expression: Any) -> set[str]:
+    """Every column whose value the expression's result is computed from, at any depth."""
+
+    if not isinstance(expression, Mapping):
+        return set()
+    if set(expression) == {"column"}:
+        return {expression["column"]} if isinstance(expression["column"], str) else set()
+    found: set[str] = set()
+    for key in _VALUE_POSITIONS:
+        found |= _value_columns(expression.get(key))
+    for argument in expression.get("args") or []:
+        found |= _value_columns(argument)
+    return found
+
+
+def _branch_variants(expression: Any) -> list[Any] | None:
+    """Every arithmetic one expression can take, with each conditional resolved to one branch.
+
+    A conditional hides a conversion wherever it sits, not only at the root: ``(if x else 0) / 10``
+    is how anyone guards a conversion against a missing reading, and reducing it as one expression
+    answers "not a scaling of one column" and checks nothing. Expanding it into the two arithmetics
+    it can actually perform puts each of them back in front of the check.
+
+    ``None`` means the expansion ran past its bound.
+    """
+
+    if not isinstance(expression, Mapping):
+        return [expression]
+    if expression.get("op") == "if":
+        variants: list[Any] = []
+        for branch in ("then", "else"):
+            expanded = _branch_variants(expression.get(branch))
+            if expanded is None:
+                return None
+            variants.extend(expanded)
+        return variants if len(variants) <= MAX_BRANCH_VARIANTS else None
+    arguments = expression.get("args")
+    if not isinstance(arguments, list):
+        return [expression]
+    combined: list[list[Any]] = [[]]
+    for argument in arguments:
+        expanded = _branch_variants(argument)
+        if expanded is None:
+            return None
+        combined = [[*carried, one] for carried in combined for one in expanded]
+        if len(combined) > MAX_BRANCH_VARIANTS:
+            return None
+    return [{**expression, "args": chosen} for chosen in combined]
+
+
+def _admit_declared_output(
+    expression: Any,
+    incoming: Mapping[str, Unit],
+    measured: _Measured | _Unplaced | None,
+    target: Unit,
+    path: str,
+    *,
+    declared_code: str,
+) -> None:
+    """Admit a declared output unit only where something establishes it, and refuse it otherwise.
+
+    Six rounds of review found six ways to make this check look away, and every one of them was
+    the same move: write the conversion so the reduction cannot read it, and the declaration went
+    unexamined. Asking "can I see anything wrong with this claim" will always have another answer
+    of that shape. So the question is the other way round -- what establishes this claim -- and
+    there are exactly three things that can.
+
+    The expression converts a declared column, and the arithmetic is exactly the conversion the
+    two units imply. That is the case this gate was written for.
+
+    Or the expression's own operands settle what it is in, unscaled and unconverted, and that is
+    the unit claimed: kilometres plus kilometres is kilometres.
+
+    Or nothing it reads carries a declared unit, so the claim is a first statement about the
+    numbers rather than a conclusion from other statements, and stands as a `source` declaration
+    stands.
+
+    Anything else is refused. That refuses some correct plans -- a density from a mass and a
+    volume, an area from a side -- and ``docs/UNITS.md`` says so: those columns carry no declared
+    unit until the arithmetic of units over the whole expression grammar is written, which is a
+    larger thing than this. Refusing a true claim costs a declaration. Admitting a false one costs
+    the point of the gate.
+    """
+
+    if isinstance(measured, _Measured) and measured.exact:
+        # The operands settle it: every one was read unscaled and unconverted, so the result is in
+        # the unit they are in and in no other.
+        if same_unit(measured.unit, target):
+            return
+        if not commensurable(measured.unit, target):
+            raise UnitFlowError(
+                "UNIT_DIMENSION_MISMATCH",
+                f"{path}.output_unit",
+                f"this expression is in {_describe(measured.unit)} and claims to be in "
+                f"{_describe(target)}; the two do not measure the same kind of thing",
+            )
+        raise UnitFlowError(
+            "UNIT_CONVERSION_FACTOR",
+            f"{path}.output_unit",
+            f"this expression reads its operands unconverted and so is in "
+            f"{measured.unit.code!r}, and claims to be in {declared_code!r}; convert them, or "
+            "declare the unit the expression is actually in",
+        )
+    if not any(incoming.get(column) is not None for column in _value_columns(expression)):
+        return
+    _require_verifiable_conversion(
+        expression, incoming, target, path, declared_code=declared_code, measured=measured
+    )
+
+
+def _require_verifiable_conversion(
+    expression: Any,
+    incoming: Mapping[str, Unit],
+    target: Unit,
+    path: str,
+    *,
+    declared_code: str,
+    measured: _Measured | _Unplaced | None,
+) -> None:
+    """Every arithmetic the expression can perform is the conversion, or converts nothing at all."""
+
+    variants = _branch_variants(expression)
+    if variants is None:
+        raise UnitFlowError(
+            "UNIT_CONVERSION_UNVERIFIABLE",
+            f"{path}.expression",
+            f"this expression branches into more than {MAX_BRANCH_VARIANTS} arithmetics, which is "
+            "past what the declared conversion can be checked against; declare no output unit, or "
+            "write the conversion in one node and the branching in another",
+        )
+    converts = False
+    for variant in variants:
+        reduced = _reduce(variant)
+        if reduced is not None and reduced.column is None:
+            # A branch that reduces to a constant converts nothing: a default of zero beside a
+            # conversion, or the absent value a guard returns.
+            continue
+        if reduced is None or incoming.get(reduced.column) is None:
+            if not any(incoming.get(column) is not None for column in _value_columns(variant)):
+                # Reads nothing anybody declared, so it contradicts nothing.
+                continue
+            raise UnitFlowError(
+                "UNIT_CONVERSION_UNVERIFIABLE",
+                f"{path}.expression",
+                _unverifiable_detail(measured, declared_code),
+            )
+        _compare_conversion(reduced, incoming[reduced.column], target, path, declared_code)
+        converts = True
+    if not converts:
+        raise UnitFlowError(
+            "UNIT_CONVERSION_UNVERIFIABLE",
+            f"{path}.expression",
+            _unverifiable_detail(measured, declared_code),
+        )
+
+
+def _unverifiable_detail(measured: _Measured | _Unplaced | None, declared_code: str) -> str:
+    if isinstance(measured, _Measured):
+        return (
+            f"this expression reads {measured.unit.code!r} operands scaled, so it is not in that "
+            f"unit either, and nothing establishes that it is in {declared_code!r}; declare no "
+            "output unit, or write the conversion as whole-number multiplies, divides and adds "
+            "over one declared column"
+        )
+    return (
+        f"nothing establishes that this expression is in {declared_code!r}: it reads a column "
+        "whose unit is declared and is not arithmetic that unit can be carried through; "
+        "declare no output unit, or write the conversion as whole-number multiplies, divides "
+        "and adds over one declared column"
+    )
+
+
+def _compare_conversion(
+    reduced: _Affine, source: Unit, target: Unit, path: str, declared_code: str
+) -> None:
+    """Hold one reduced arithmetic to the exact map the grammar derives between the two units.
+
+    Where the claim is the column's own unit there is no conversion to hold it to: scaling a
+    distance leaves it a distance, and the reduction having read the arithmetic is what says so.
+    An expression the reduction could *not* read is a different matter and never reaches here.
+    """
+
+    if same_unit(source, target):
+        if source.affine and (reduced.scale, reduced.offset) != (Fraction(1), Fraction(0)):
+            raise UnitFlowError(
+                "UNIT_CONVERSION_FACTOR",
+                f"{path}.expression",
+                f"{reduced.column!r} is declared {source.code!r}, which is an offset scale: "
+                "doubling it or adding to it does not leave a value in that unit, so the result "
+                "cannot be declared to be in it",
+            )
+        return
+    if not commensurable(source, target):
+        raise UnitFlowError(
+            "UNIT_DIMENSION_MISMATCH",
+            f"{path}.output_unit",
+            f"the expression reads {reduced.column!r}, declared {_describe(source)}, and claims "
+            f"the result is {_describe(target)}; the two do not measure the same kind of thing",
+        )
+    expected_scale, expected_offset = conversion(source, target)
+    if (reduced.scale, reduced.offset) != (expected_scale, expected_offset):
+        raise UnitFlowError(
+            "UNIT_CONVERSION_FACTOR",
+            f"{path}.expression",
+            f"converting {reduced.column!r} from {source.code!r} to {declared_code!r} is "
+            f"multiply by {expected_scale} then add {expected_offset}; this expression "
+            f"multiplies by {reduced.scale} and adds {reduced.offset}",
+        )
+
+
+def _aggregate_units(
+    node: GraphNode, incoming: Mapping[str, Unit], *, group_by_key: str, measures_key: str
+) -> dict[str, Unit]:
+    parameters = _parameters(node)
+    units: dict[str, Unit] = {}
+    for column in thaw_parameter(parameters.get(group_by_key)) or []:
+        if isinstance(column, str) and column in incoming:
+            units[column] = incoming[column]
+    for measure in thaw_parameter(parameters.get(measures_key)) or []:
+        if not isinstance(measure, Mapping):  # pragma: no cover - the registry shaped this already.
+            continue
+        output = measure.get("as")
+        operation = measure.get("op")
+        if not isinstance(output, str):  # pragma: no cover - same.
+            continue
+        if operation == "count":
+            units[output] = parse_unit(COUNT_UNIT_CODE)
+            continue
+        source = incoming.get(measure.get("column"))
+        if operation not in _MEASURE_KEEPS_UNIT or source is None:
+            continue
+        if operation == "sum" and source.affine:
+            # A total of Celsius readings is not a temperature. Every other measure here returns
+            # one of the values it was given, which an offset scale survives; adding them up is
+            # the one that does not.
+            continue
+        units[output] = source
+    return units
+
+
+def _unpivot_units(node: GraphNode, incoming: Mapping[str, Unit], *, index: int) -> dict[str, Unit]:
+    """Fold the named value columns into one, refusing a fold the declared units disagree about."""
+
+    parameters = _parameters(node)
+    value_columns = [
+        column
+        for column in (thaw_parameter(parameters.get("value_columns")) or [])
+        if isinstance(column, str)
+    ]
+    name_column = parameters.get("name_column")
+    value_column = parameters.get("value_column")
+    units = {column: unit for column, unit in incoming.items() if column not in set(value_columns)}
+    units.pop(name_column, None)
+
+    # Every declared value column is compared, whatever order the plan lists them in. Deciding on
+    # the first undeclared one instead would have made the refusal a function of the order rather
+    # than of the units, and moving one undeclared name to the front would have got a disagreement
+    # past the gate.
+    declared: dict[str, Unit] = {}
+    first: str | None = None
+    path = f"plan.nodes[{index}].parameters.value_columns"
+    for column in value_columns:
+        unit = incoming.get(column)
+        if unit is None:
+            continue
+        declared = _merge(
+            declared,
+            {str(value_column): unit},
+            path=path,
+            # The column that was compared, not the column the fold writes to: naming the output
+            # on one side of the sentence would leave the reader looking for an input that is not
+            # there, and with sixteen value columns unable to tell which one disagreed.
+            left_label=f"value column {first!r}",
+            right_label=f"value column {column!r}",
+        )
+        first = first or column
+    if declared and all(column in incoming for column in value_columns):
+        # Only where every folded column declared something. One undeclared among them means the
+        # result is part quantity and part unknown, and saying it was all one unit would be the
+        # invention this gate exists to stop.
+        units.update(declared)
+    return units
+
+
+def unit_environments(plan: GraphDatasetPlan) -> dict[str, dict[str, Unit]]:
+    """Walk the graph once and return the declared unit of every column each node emits.
+
+    Nodes are already ordered so that every input is defined before it is used, which is what makes
+    one forward pass enough. The environments are partial by design: a column appears only when
+    something declared its unit, so the result says what is claimed and never what is guessed.
+    """
+
+    environments: dict[str, dict[str, Unit]] = {}
+    for index, node in enumerate(plan.nodes):
+        incoming = [environments.get(input_id, {}) for input_id in node.inputs]
+        path = f"plan.nodes[{index}].parameters"
+        parameters = _parameters(node)
+        operation = node.operation
+        if operation == "source":
+            environments[node.node_id] = _source_units(node)
+        elif operation == "union":
+            merged: dict[str, Unit] = {}
+            for position, environment in enumerate(incoming):
+                merged = _merge(
+                    merged,
+                    environment,
+                    path=path,
+                    left_label="an earlier input",
+                    right_label=f"input {node.inputs[position]!r}",
+                )
+            environments[node.node_id] = merged
+        elif operation == "join":
+            # An anti join emits left columns only and discards every right column, key or not. So
+            # the comparison there is the keys it matches on -- metres against feet is the same
+            # mistake whether or not the row is emitted -- and nothing else: refusing over a column
+            # the node provably throws away would refuse a plan that is correct.
+            anti = parameters.get("kind") == "anti"
+            keys = {
+                column
+                for column in (thaw_parameter(parameters.get("on")) or [])
+                if isinstance(column, str)
+            }
+            right = (
+                {column: unit for column, unit in incoming[1].items() if column in keys}
+                if anti
+                else incoming[1]
+            )
+            merged_sides = _merge(
+                incoming[0],
+                right,
+                path=path,
+                left_label=f"the left side {node.inputs[0]!r}",
+                right_label=f"the right side {node.inputs[1]!r}",
+            )
+            environments[node.node_id] = dict(incoming[0]) if anti else merged_sides
+        elif operation == "rename":
+            mappings = thaw_parameter(parameters.get("mappings")) or {}
+            carried = dict(incoming[0])
+            renamed = {
+                new: carried.pop(old)
+                for old, new in mappings.items()
+                if isinstance(new, str) and old in carried
+            }
+            for old in mappings:
+                carried.pop(old, None)
+            carried.update(renamed)
+            environments[node.node_id] = carried
+        elif operation == "project":
+            selected = {
+                column
+                for column in (thaw_parameter(parameters.get("columns")) or [])
+                if isinstance(column, str)
+            }
+            environments[node.node_id] = {
+                column: unit for column, unit in incoming[0].items() if column in selected
+            }
+        elif operation == "derive":
+            environments[node.node_id] = _derive_units(node, incoming[0], index=index)
+        elif operation == "aggregate":
+            environments[node.node_id] = _aggregate_units(
+                node, incoming[0], group_by_key="group_by", measures_key="measures"
+            )
+        elif operation == "resample":
+            environments[node.node_id] = _aggregate_units(
+                node, incoming[0], group_by_key="group_by", measures_key="aggregates"
+            )
+        elif operation == "unpivot":
+            environments[node.node_id] = _unpivot_units(node, incoming[0], index=index)
+        elif operation == "date_add_days":
+            # A calendar label is not a quantity. Existing quantity claims pass through, while
+            # the newly emitted date intentionally carries no unit declaration.
+            environments[node.node_id] = dict(incoming[0])
+        elif operation == "filter":
+            _predicate_units(
+                thaw_parameter(parameters.get("predicate")),
+                incoming[0],
+                f"{path}.predicate",
+            )
+            environments[node.node_id] = dict(incoming[0])
+        elif operation in UNIT_PASS_THROUGH_OPERATIONS or operation == "prediction_label":
+            # These change which rows or which types are present, never what the numbers are in, so
+            # the claim rides through. A retired operation appends a column, which carries no claim
+            # because nothing declared one for it.
+            environments[node.node_id] = dict(incoming[0]) if incoming else {}
+        else:  # pragma: no cover - the closure test below makes this unreachable.
+            raise UnitFlowError(
+                "UNIT_OPERATION_UNMODELLED",
+                f"plan.nodes[{index}].operation",
+                f"{operation!r} is in the operation vocabulary and this analysis does not say "
+                "what it does to a declared unit",
+            )
+    return environments
+
+
+def refuse_inconsistent_units(plan: GraphDatasetPlan) -> None:
+    """Run both gates over one plan, or raise the first refusal either of them reaches."""
+
+    unit_environments(plan)
+
+
+__all__ = [
+    "UNIT_ARITHMETIC_OPERATORS",
+    "UNIT_MODELLED_EXPRESSIONS",
+    "UNIT_MODELLED_OPERATIONS",
+    "UNIT_PASS_THROUGH_OPERATIONS",
+    "UNIT_UNMEASURED_OPERATORS",
+    "UnitFlowError",
+    "refuse_inconsistent_units",
+    "unit_environments",
+]