mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/plan_graph.py

@@ -0,0 +1,2026 @@
+"""Deterministic executor for ``local-graph-table-plan.v1`` Table graphs.
+
+The graph owns topology, budgets and observable node audits. Engines may supply typed containers,
+but operation meaning lives here so row order, null behavior and reduction arithmetic cannot drift.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from collections import defaultdict
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass
+from datetime import UTC, date, datetime, timedelta
+from decimal import ROUND_HALF_EVEN, Decimal, InvalidOperation, localcontext
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any
+
+from mostlyright.data_harness.local_contracts import GraphNode, GraphTablePlan
+from mostlyright.data_harness.operation_registry import MAX_DATE_ADD_DAYS, thaw_parameter
+
+if TYPE_CHECKING:
+    from mostlyright.data_harness.backends.protocol import Backend
+
+# The hard ceilings are sized to the hosted acquisition contract, so a source the hosted
+# clean room can lawfully hand back is a source the local engine can execute.  Each value
+# below names the hosted constant it mirrors; a policy may narrow any of them, and a value
+# above a ceiling still refuses -- the ceilings stay hard.
+#
+# One source may hold every row of one hosted normalized artifact: the epa-scale Reader
+# budget admits 10_000_000 rows per decode (``readers/contracts.py``), and the coordinator
+# parser ceiling agrees (``acquisition/parsing.py``).
+HARD_MAX_SOURCE_ROWS = 10_000_000
+# One intermediate table may hold the union of several year-scale sources: four sources at
+# the normalized-maximum row count, which covers a three-year union with one source of
+# margin before anything is filtered or aggregated.
+HARD_MAX_INTERMEDIATE_ROWS = 40_000_000
+# A released dataset never carries more rows than one hosted normalized artifact may.
+HARD_MAX_OUTPUT_ROWS = 10_000_000
+HARD_MAX_FIELD_BYTES = 1 * 1024 * 1024
+# Canonical logical bytes, not an RSS claim: room for several normalized-maximum sources
+# (4 GiB each, ``readers/contracts.py`` max_output_bytes) held beside the canonical tables
+# derived from them.  16 GiB = raw year-scale sources + one decode transient + the kernel's
+# own tables, with the same one-source margin the intermediate row ceiling carries.
+HARD_MAX_RETAINED_BYTES = 17_179_869_184
+LOGICAL_TYPES = frozenset(
+    {"null", "boolean", "int64", "float64", "string", "date", "timestamp_utc", "decimal"}
+)
+DECIMAL_INTEGRAL_DIGITS = 38
+DECIMAL_FRACTIONAL_DIGITS = 38
+DECIMAL_WORKING_PRECISION = 160
+DECIMAL_QUANTUM = Decimal(1).scaleb(-DECIMAL_FRACTIONAL_DIGITS)
+# The whole trim alphabet of the local lexical contract, which is deliberately smaller than
+# Python's Unicode default: ``str.strip()`` with no argument also removes NBSP, the ideographic
+# space and every other Unicode space, and which code points those are depends on the Unicode
+# version the interpreter was built against.  These six ASCII characters do not move.  The v1
+# cleaning step in ``pipeline.py`` trims by this same constant, so both plan versions strip
+# exactly the same bytes.
+ASCII_TRIM_CHARS = "\t\n\v\f\r "
+# ASCII case folding, written out rather than delegated to ``str.casefold()``.  Full Unicode
+# folding is locale-independent but not version-independent: its mappings grow with each Unicode
+# release, and some of them change a string's length.  A sealed Build must replay byte for byte on
+# a later interpreter, so the fold admitted here is the twenty-six letters and nothing else; every
+# other code point, including a dotted capital I and a sharp s, is returned unchanged.
+_ASCII_CASE_FOLD = str.maketrans("ABCDEFGHIJKLMNOPQRSTUVWXYZ", "abcdefghijklmnopqrstuvwxyz")
+
+
+@dataclass(frozen=True)
+class GraphResourcePolicy:
+    max_source_rows: int = HARD_MAX_SOURCE_ROWS
+    max_intermediate_rows: int = HARD_MAX_INTERMEDIATE_ROWS
+    max_output_rows: int = HARD_MAX_OUTPUT_ROWS
+    max_source_bytes: int = HARD_MAX_RETAINED_BYTES
+    max_intermediate_bytes: int = HARD_MAX_RETAINED_BYTES
+    max_output_bytes: int = HARD_MAX_RETAINED_BYTES
+    max_retained_bytes: int = HARD_MAX_RETAINED_BYTES
+
+    def __post_init__(self) -> None:
+        limits = (
+            ("max_source_rows", self.max_source_rows, HARD_MAX_SOURCE_ROWS),
+            ("max_intermediate_rows", self.max_intermediate_rows, HARD_MAX_INTERMEDIATE_ROWS),
+            ("max_output_rows", self.max_output_rows, HARD_MAX_OUTPUT_ROWS),
+        )
+        for name, value, ceiling in limits:
+            if isinstance(value, bool) or not isinstance(value, int) or not 1 <= value <= ceiling:
+                raise GraphExecutionError("RESOURCE_POLICY_INVALID", name, "outside hard ceiling")
+        byte_limits = (
+            ("max_source_bytes", self.max_source_bytes),
+            ("max_intermediate_bytes", self.max_intermediate_bytes),
+            ("max_output_bytes", self.max_output_bytes),
+            ("max_retained_bytes", self.max_retained_bytes),
+        )
+        for name, value in byte_limits:
+            if (
+                isinstance(value, bool)
+                or not isinstance(value, int)
+                or not 1 <= value <= HARD_MAX_RETAINED_BYTES
+            ):
+                raise GraphExecutionError("RESOURCE_POLICY_INVALID", name, "outside hard ceiling")
+
+
+class GraphExecutionError(RuntimeError):
+    def __init__(self, code: str, node_id: str, detail: str) -> None:
+        self.code = code
+        self.node_id = node_id
+        self.detail = detail
+        super().__init__(f"{node_id}: {detail} [{code}]")
+
+
+@dataclass(frozen=True)
+class ColumnLineage:
+    """Sources and deterministic graph operations that produced one column."""
+
+    sources: tuple[tuple[str, str], ...]
+    operations: tuple[str, ...] = ()
+
+    def __iter__(self):
+        """Keep the v2 pipeline's source-pair iteration compatible."""
+
+        return iter(self.sources)
+
+    def __len__(self) -> int:
+        return len(self.sources)
+
+    def __getitem__(self, item: int | slice):
+        return self.sources[item]
+
+
+@dataclass(frozen=True)
+class GraphTable:
+    columns: tuple[str, ...]
+    rows: tuple[tuple[Any, ...], ...]
+    lineage: Mapping[str, ColumnLineage | tuple[tuple[str, str], ...]] = MappingProxyType({})
+    schema: Mapping[str, str] | None = None
+
+    def __post_init__(self) -> None:
+        schema = self.schema or MappingProxyType(
+            {
+                column: _infer_column_type((row[index] for row in self.rows), "table", column)
+                for index, column in enumerate(self.columns)
+            }
+        )
+        if tuple(schema) != self.columns or any(
+            logical_type not in LOGICAL_TYPES for logical_type in schema.values()
+        ):
+            raise GraphExecutionError(
+                "LOGICAL_SCHEMA_INVALID", "table", "schema must exactly type every ordered column"
+            )
+        if any(len(row) != len(self.columns) for row in self.rows):
+            raise GraphExecutionError(
+                "SOURCE_ROW_INVALID", "table", "row width differs from schema"
+            )
+        lineage = MappingProxyType(
+            {
+                column: item if isinstance(item, ColumnLineage) else ColumnLineage(tuple(item))
+                for column, item in self.lineage.items()
+            }
+        )
+        object.__setattr__(self, "schema", MappingProxyType(dict(schema)))
+        object.__setattr__(self, "lineage", lineage)
+
+    def mappings(self) -> tuple[Mapping[str, Any], ...]:
+        return tuple(
+            MappingProxyType(dict(zip(self.columns, row, strict=True))) for row in self.rows
+        )
+
+
+@dataclass(frozen=True)
+class NodeAudit:
+    node_id: str
+    operation: str
+    operation_version: str
+    inputs: tuple[str, ...]
+    parameter_digest: str
+    input_digests: tuple[str, ...]
+    output_digest: str
+    input_rows: int
+    output_rows: int
+    rejected_rows: int
+    duplicate_rows: int
+    order_contract: str
+    engine: str
+    input_schemas: tuple[tuple[tuple[str, str], ...], ...] = ()
+    output_schema: tuple[tuple[str, str], ...] = ()
+    input_bytes: int = 0
+    output_bytes: int = 0
+    retained_bytes: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "node_id": self.node_id,
+            "operation": self.operation,
+            "operation_version": self.operation_version,
+            "inputs": list(self.inputs),
+            "parameter_digest": self.parameter_digest,
+            "input_digests": list(self.input_digests),
+            "output_digest": self.output_digest,
+            "input_rows": self.input_rows,
+            "output_rows": self.output_rows,
+            "rejected_rows": self.rejected_rows,
+            "duplicate_rows": self.duplicate_rows,
+            "order_contract": self.order_contract,
+            "engine": self.engine,
+            "input_schemas": [dict(schema) for schema in self.input_schemas],
+            "output_schema": dict(self.output_schema),
+            "input_bytes": self.input_bytes,
+            "output_bytes": self.output_bytes,
+            "retained_bytes": self.retained_bytes,
+        }
+
+
+@dataclass(frozen=True)
+class GraphExecution:
+    terminal: GraphTable
+    audits: tuple[NodeAudit, ...]
+    tables: Mapping[str, GraphTable]
+    peak_retained_bytes: int = 0
+
+
+def _normalize(value: Any) -> Any:
+    if value is None or type(value) in {bool, int, str}:
+        return value
+    if isinstance(value, (date, datetime)):
+        return value.isoformat().replace("+00:00", "Z")
+    if isinstance(value, Decimal):
+        return format(value, "f")
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise GraphExecutionError("NON_FINITE_VALUE", "digest", "non-finite floats refuse")
+        return {"$float": value.hex()}
+    if isinstance(value, tuple):
+        return [_normalize(item) for item in value]
+    if isinstance(value, list):
+        return [_normalize(item) for item in value]
+    if isinstance(value, Mapping):
+        return {str(key): _normalize(item) for key, item in sorted(value.items())}
+    raise GraphExecutionError("VALUE_UNSUPPORTED", "digest", f"unsupported value {type(value)!r}")
+
+
+def _digest(value: Any) -> str:
+    raw = json.dumps(
+        _normalize(value),
+        ensure_ascii=False,
+        allow_nan=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode()
+    return hashlib.sha256(raw).hexdigest()
+
+
+def _value_bytes(value: Any, node_id: str) -> int:
+    normalized = _normalize(value)
+    size = len(
+        json.dumps(normalized, ensure_ascii=False, allow_nan=False, separators=(",", ":")).encode()
+    )
+    if size > HARD_MAX_FIELD_BYTES:
+        raise GraphExecutionError("FIELD_BUDGET_EXCEEDED", node_id, "field exceeds byte ceiling")
+    return size
+
+
+def _table_bytes(table: GraphTable, node_id: str) -> int:
+    return sum(_value_bytes(value, node_id) for row in table.rows for value in row)
+
+
+@dataclass
+class _OutputBudget:
+    """Reserve canonical output bytes before retaining each kernel result row."""
+
+    node_id: str
+    max_rows: int
+    max_bytes: int
+    rows: int = 0
+    bytes: int = 0
+
+    def retain(self, output: list[tuple[Any, ...]], row: tuple[Any, ...]) -> None:
+        if self.rows >= self.max_rows:
+            raise GraphExecutionError(
+                "ROW_BUDGET_EXCEEDED", self.node_id, f"output exceeds {self.max_rows}"
+            )
+        row_bytes = sum(_value_bytes(value, self.node_id) for value in row)
+        if row_bytes > self.max_bytes - self.bytes:
+            raise GraphExecutionError(
+                "BYTE_BUDGET_EXCEEDED", self.node_id, f"output exceeds {self.max_bytes}"
+            )
+        output.append(row)
+        self.rows += 1
+        self.bytes += row_bytes
+
+
+def table_digest(table: GraphTable) -> str:
+    return _digest({"columns": table.columns, "schema": dict(table.schema), "rows": table.rows})
+
+
+def _logical_type(value: Any, node_id: str) -> str:
+    if value is None:
+        return "null"
+    if type(value) is bool:
+        return "boolean"
+    if type(value) is int:
+        if not -(2**63) <= value < 2**63:
+            raise GraphExecutionError("SOURCE_VALUE_INVALID", node_id, "integer exceeds int64")
+        return "int64"
+    if type(value) is float:
+        if not math.isfinite(value):
+            raise GraphExecutionError("NON_FINITE_VALUE", node_id, "source float is non-finite")
+        return "float64"
+    if isinstance(value, Decimal):
+        if not value.is_finite():
+            raise GraphExecutionError("NON_FINITE_VALUE", node_id, "source decimal is non-finite")
+        return "decimal"
+    if isinstance(value, datetime):
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise GraphExecutionError(
+                "SOURCE_VALUE_INVALID", node_id, "timestamp must carry an offset"
+            )
+        return "timestamp_utc"
+    if isinstance(value, date):
+        return "date"
+    if isinstance(value, str):
+        return "string"
+    raise GraphExecutionError(
+        "SOURCE_VALUE_INVALID", node_id, f"unsupported source scalar {type(value)!r}"
+    )
+
+
+def _infer_column_type(values: Iterable[Any], node_id: str, column: str) -> str:
+    observed = {_logical_type(value, node_id) for value in values} - {"null"}
+    if not observed:
+        return "null"
+    if len(observed) == 1:
+        return next(iter(observed))
+    raise GraphExecutionError(
+        "SOURCE_SCHEMA_MIXED",
+        node_id,
+        f"column {column!r} contains incompatible logical types {sorted(observed)}",
+    )
+
+
+def _schema_items(table: GraphTable) -> tuple[tuple[str, str], ...]:
+    return tuple(table.schema.items())
+
+
+def _operation_coordinate(node: GraphNode) -> str:
+    return f"{node.node_id}:{node.operation}@{node.operation_version}"
+
+
+def _advance_lineage(
+    node: GraphNode,
+    lineage: Mapping[str, ColumnLineage],
+) -> Mapping[str, ColumnLineage]:
+    coordinate = _operation_coordinate(node)
+    return MappingProxyType(
+        {
+            column: ColumnLineage(item.sources, (*item.operations, coordinate))
+            for column, item in lineage.items()
+        }
+    )
+
+
+def _parameters(node: GraphNode) -> dict[str, Any]:
+    value = thaw_parameter(node.parameters)
+    assert isinstance(value, dict)
+    return value
+
+
+def _table_from_records(
+    node_id: str,
+    source_id: str,
+    records: Iterable[Mapping[str, Any]],
+    limit: int,
+    byte_limit: int,
+    declared_columns: tuple[str, ...] | None = None,
+) -> GraphTable:
+    columns: tuple[str, ...] | None = declared_columns
+    rows: list[tuple[Any, ...]] = []
+    retained_bytes = 0
+    for index, record in enumerate(records):
+        if index >= limit:
+            raise GraphExecutionError(
+                "ROW_BUDGET_EXCEEDED", node_id, f"source exceeds max_source_rows={limit}"
+            )
+        if not isinstance(record, Mapping) or any(not isinstance(key, str) for key in record):
+            raise GraphExecutionError("SOURCE_ROW_INVALID", node_id, "source row must be an object")
+        keys = tuple(record)
+        if columns is None:
+            columns = keys
+        elif keys != columns:
+            raise GraphExecutionError(
+                "SOURCE_SCHEMA_DRIFT", node_id, "source rows do not share exact column order"
+            )
+        rows.append(tuple(record[column] for column in columns))
+        for value in rows[-1]:
+            retained_bytes += _value_bytes(value, node_id)
+            if retained_bytes > byte_limit:
+                raise GraphExecutionError(
+                    "BYTE_BUDGET_EXCEEDED", node_id, "source table exceeds byte ceiling"
+                )
+    final_columns = columns or ()
+    frozen_rows = tuple(rows)
+    schema = MappingProxyType(
+        {
+            column: (
+                _infer_column_type((row[column_index] for row in frozen_rows), node_id, column)
+                if frozen_rows
+                else "string"
+            )
+            for column_index, column in enumerate(final_columns)
+        }
+    )
+    return GraphTable(
+        final_columns,
+        frozen_rows,
+        MappingProxyType(
+            {column: ColumnLineage(((source_id, column),)) for column in final_columns}
+        ),
+        schema,
+    )
+
+
+def _lineage_union(*values: Iterable[tuple[str, str]]) -> tuple[tuple[str, str], ...]:
+    return tuple(dict.fromkeys(item for value in values for item in value))
+
+
+def _merge_lineage(node: GraphNode, *items: ColumnLineage) -> ColumnLineage:
+    return ColumnLineage(
+        _lineage_union(*(item.sources for item in items)),
+        tuple(
+            dict.fromkeys(
+                operation
+                for item in items
+                for operation in (*item.operations, _operation_coordinate(node))
+            )
+        ),
+    )
+
+
+def _expression_columns(value: Any) -> tuple[str, ...]:
+    if isinstance(value, Mapping):
+        found = (str(value["column"]),) if set(value) == {"column"} else ()
+        return _lineage_names(found, value.values())
+    if isinstance(value, list):
+        return _lineage_names((), value)
+    return ()
+
+
+def _lineage_names(initial: tuple[str, ...], values: Iterable[Any]) -> tuple[str, ...]:
+    return tuple(
+        dict.fromkeys(
+            (*initial, *(name for value in values for name in _expression_columns(value)))
+        )
+    )
+
+
+def _index(table: GraphTable, node_id: str) -> dict[str, int]:
+    if len(table.columns) != len(set(table.columns)):
+        raise GraphExecutionError("SCHEMA_DUPLICATE", node_id, "column names must be unique")
+    return {column: index for index, column in enumerate(table.columns)}
+
+
+def _columns(value: Any, node_id: str) -> tuple[str, ...]:
+    if not isinstance(value, list) or not value or any(not isinstance(item, str) for item in value):
+        raise GraphExecutionError("OPERATION_PARAMETERS", node_id, "columns must be text list")
+    if len(value) != len(set(value)):
+        raise GraphExecutionError("OPERATION_PARAMETERS", node_id, "columns must be unique")
+    return tuple(value)
+
+
+def _require_columns(table: GraphTable, columns: Iterable[str], node_id: str) -> None:
+    missing = sorted(set(columns) - set(table.columns))
+    if missing:
+        raise GraphExecutionError("COLUMN_UNKNOWN", node_id, f"columns absent: {missing}")
+
+
+def _canonical_decimal(value: Decimal, node_id: str) -> Decimal:
+    if not value.is_finite():
+        raise GraphExecutionError("NON_FINITE_VALUE", node_id, "decimal is non-finite")
+    exponent = value.as_tuple().exponent
+    fractional_digits = max(0, -exponent)
+    integral_digits = max(0, value.adjusted() + 1) if value else 0
+    if integral_digits > DECIMAL_INTEGRAL_DIGITS or fractional_digits > DECIMAL_FRACTIONAL_DIGITS:
+        raise GraphExecutionError(
+            "DECIMAL_RANGE",
+            node_id,
+            "decimal exceeds canonical decimal256(76,38) integral/scale bounds",
+        )
+    return value
+
+
+def _cast(value: Any, kind: str, node_id: str) -> Any:
+    if value is None:
+        return None
+    try:
+        if kind == "string":
+            return str(value)
+        if kind == "int64":
+            if isinstance(value, bool):
+                raise ValueError
+            if isinstance(value, (float, Decimal)) and value != int(value):
+                raise ValueError
+            result = int(value)
+            if not -(2**63) <= result < 2**63:
+                raise OverflowError
+            return result
+        if kind == "float64":
+            result = float(value)
+            if not math.isfinite(result):
+                raise ValueError
+            return result
+        if kind == "boolean":
+            if type(value) is bool:
+                return value
+            if isinstance(value, str) and value.lower() in {"true", "false"}:
+                return value.lower() == "true"
+            raise ValueError
+        if kind == "date":
+            if isinstance(value, datetime):
+                raise ValueError
+            return value if isinstance(value, date) else date.fromisoformat(str(value))
+        if kind == "timestamp_utc":
+            parsed = (
+                value
+                if isinstance(value, datetime)
+                else datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+            )
+            if parsed.tzinfo is None or parsed.utcoffset() is None:
+                raise ValueError
+            return parsed.astimezone(UTC)
+        if kind == "decimal":
+            return _canonical_decimal(Decimal(str(value)), node_id)
+    except (InvalidOperation, OverflowError, TypeError, ValueError) as exc:
+        raise GraphExecutionError("CAST_INVALID", node_id, f"cannot cast value to {kind}") from exc
+    raise GraphExecutionError("CAST_UNSUPPORTED", node_id, f"unknown cast {kind!r}")
+
+
+def _operand(expr: Any, row: Mapping[str, Any], node_id: str) -> Any:
+    if isinstance(expr, Mapping) and set(expr) == {"column"} and isinstance(expr["column"], str):
+        if expr["column"] not in row:
+            raise GraphExecutionError("COLUMN_UNKNOWN", node_id, str(expr["column"]))
+        return row[expr["column"]]
+    if isinstance(expr, Mapping) and set(expr) == {"literal"}:
+        return expr["literal"]
+    return expr
+
+
+def _predicate(expr: Any, row: Mapping[str, Any], node_id: str) -> bool | None:
+    if not isinstance(expr, Mapping) or not isinstance(expr.get("op"), str):
+        raise GraphExecutionError("PREDICATE_INVALID", node_id, "predicate must name an op")
+    op = expr["op"]
+    if op in {"and", "or"}:
+        args = expr.get("args")
+        if not isinstance(args, list) or len(args) < 2:
+            raise GraphExecutionError("PREDICATE_INVALID", node_id, f"{op} needs arguments")
+        values = [_predicate(item, row, node_id) for item in args]
+        if op == "and":
+            return False if False in values else None if None in values else True
+        return True if True in values else None if None in values else False
+    if op == "not":
+        result = _predicate(expr.get("arg"), row, node_id)
+        return None if result is None else not result
+    left = _operand(expr.get("left", {"column": expr.get("column")}), row, node_id)
+    if op in {"is_null", "not_null"}:
+        return (left is None) if op == "is_null" else (left is not None)
+    right = _operand(expr.get("right", expr.get("value")), row, node_id)
+    if left is None or right is None:
+        return None
+    if op == "in":
+        try:
+            return any(type(left) is type(candidate) and left == candidate for candidate in right)
+        except TypeError as exc:
+            raise GraphExecutionError(
+                "PREDICATE_TYPE", node_id, "membership operand is incompatible"
+            ) from exc
+    if type(left) is not type(right):
+        raise GraphExecutionError(
+            "PREDICATE_TYPE", node_id, "predicate operands have different logical types"
+        )
+    operations = {
+        "eq": lambda: left == right,
+        "ne": lambda: left != right,
+        "lt": lambda: left < right,
+        "le": lambda: left <= right,
+        "gt": lambda: left > right,
+        "ge": lambda: left >= right,
+    }
+    try:
+        return bool(operations[op]())
+    except KeyError as exc:
+        raise GraphExecutionError("PREDICATE_UNSUPPORTED", node_id, op) from exc
+    except (TypeError, ValueError) as exc:
+        raise GraphExecutionError(
+            "PREDICATE_TYPE", node_id, "predicate operands are incompatible"
+        ) from exc
+
+
+def _expression_type(expr: Any, schema: Mapping[str, str], node_id: str) -> str:
+    if not isinstance(expr, Mapping):
+        return _logical_type(expr, node_id)
+    if set(expr) == {"column"}:
+        column = expr["column"]
+        if not isinstance(column, str) or column not in schema:
+            raise GraphExecutionError("COLUMN_UNKNOWN", node_id, str(column))
+        return schema[column]
+    if set(expr) == {"literal"}:
+        return _logical_type(expr["literal"], node_id)
+    op = expr.get("op")
+    if op == "if":
+        branch_types = {
+            _expression_type(expr[branch], schema, node_id) for branch in ("then", "else")
+        } - {"null"}
+        if len(branch_types) > 1:
+            raise GraphExecutionError(
+                "DERIVE_TYPE", node_id, "conditional branches have different logical types"
+            )
+        return next(iter(branch_types), "null")
+    argument_types = [_expression_type(item, schema, node_id) for item in expr.get("args", [])]
+    present_types = [item for item in argument_types if item != "null"]
+    if op in {"add", "subtract", "multiply"}:
+        if len(set(present_types)) > 1 or any(
+            item not in {"int64", "float64", "decimal"} for item in present_types
+        ):
+            raise GraphExecutionError(
+                "DERIVE_TYPE", node_id, "arithmetic requires one exact numeric logical type"
+            )
+        return present_types[0] if present_types else "null"
+    if op == "divide":
+        # Division takes the same one-exact-numeric-type operands as the other arithmetic and
+        # then leaves that type behind, because a quotient is not the domain its operands came
+        # from.  ``int64 / int64`` is the case this makes explicit: it does not truncate towards
+        # zero, does not floor, and does not become a float; it produces the decimal quotient,
+        # exactly as ``aggregate``'s ``mean`` does over an integer column.  A ratio therefore
+        # always declares ``output_type: decimal``.
+        if len(set(present_types)) > 1 or any(
+            item not in {"int64", "float64", "decimal"} for item in present_types
+        ):
+            raise GraphExecutionError(
+                "DERIVE_TYPE", node_id, "division requires one exact numeric logical type"
+            )
+        return "decimal" if present_types else "null"
+    if op == "concat":
+        if any(item != "string" for item in present_types):
+            raise GraphExecutionError("DERIVE_TYPE", node_id, "concat requires string operands")
+        return "string" if present_types else "null"
+    if op in {"trim", "case_fold"}:
+        if any(item != "string" for item in present_types):
+            raise GraphExecutionError("DERIVE_TYPE", node_id, f"{op} requires a string operand")
+        return "string" if present_types else "null"
+    if op in {"year", "month", "day", "hour"}:
+        permitted = {"timestamp_utc"} if op == "hour" else {"date", "timestamp_utc"}
+        if any(item not in permitted for item in present_types):
+            raise GraphExecutionError("DERIVE_TYPE", node_id, f"{op} requires a temporal operand")
+        return "int64" if present_types else "null"
+    raise GraphExecutionError("DERIVE_UNSUPPORTED", node_id, str(op))
+
+
+def _divide(args: list[Any], node_id: str) -> Any:
+    """One quotient, under the two denominator policies a dividing node declares."""
+
+    present_types = {_logical_type(item, node_id) for item in args} - {"null"}
+    if len(present_types) > 1 or any(
+        item not in {"int64", "float64", "decimal"} for item in present_types
+    ):
+        raise GraphExecutionError(
+            "DERIVE_TYPE", node_id, "division requires one exact numeric logical type"
+        )
+    # The declared zero-denominator policy is ``reject``, and it answers before the null policy so
+    # that it answers for every row with a zero denominator.  There is no quotient to record, and
+    # an absent value here would be one this operation manufactured rather than one it found.
+    if args[1] is not None and _decimal(args[1], node_id, code="DERIVE_TYPE") == 0:
+        raise GraphExecutionError(
+            "DERIVE_DIVIDE_BY_ZERO", node_id, "denominator is zero under the declared policy"
+        )
+    # A denominator that is absent is a different fact from one that is zero, and the declared
+    # null policy carries it through as absent. An absent numerator does the same.
+    if any(item is None for item in args):
+        return None
+    numerator = _decimal(args[0], node_id, code="DERIVE_TYPE")
+    denominator = _decimal(args[1], node_id, code="DERIVE_TYPE")
+    # Both operands came through ``_canonical_decimal``, so each is under 1e38 and no smaller than
+    # 1e-38; the quotient is therefore under 1e76 and the quantize below stays inside the working
+    # precision rather than raising an untyped decimal error.
+    with localcontext() as context:
+        context.prec = DECIMAL_WORKING_PRECISION
+        quotient = numerator / denominator
+        # A repeating quotient cannot be held exactly in decimal256(76,38), so the contract rounds
+        # once, at the physical scale, with banker's rounding -- the same single rounding step
+        # ``aggregate``'s ``mean`` takes, through the same shared kernel.
+        quotient = quotient.quantize(DECIMAL_QUANTUM, rounding=ROUND_HALF_EVEN)
+    # A negative denominator under a zero numerator, or a quotient that underflows the scale, lands
+    # on a signed zero.  Decimal keeps the sign, ``_normalize`` renders it into the digest, and the
+    # decimal256 column the value is written to does not have it -- so the audit and the stored
+    # bytes would disagree about a value that is equal to positive zero either way.  Settle it here.
+    result = _canonical_decimal(quotient if quotient else abs(quotient), node_id)
+    _value_bytes(result, node_id)
+    return result
+
+
+def _derive(expr: Any, row: Mapping[str, Any], node_id: str) -> Any:
+    if not isinstance(expr, Mapping):
+        return expr
+    if "column" in expr and set(expr) == {"column"}:
+        return _operand(expr, row, node_id)
+    if "literal" in expr and set(expr) == {"literal"}:
+        return expr["literal"]
+    op = expr.get("op")
+    if op == "if":
+        decision = _predicate(expr.get("condition"), row, node_id)
+        if decision is None:
+            return None
+        return _derive(expr.get("then") if decision is True else expr.get("else"), row, node_id)
+    args = [_derive(item, row, node_id) for item in expr.get("args", [])]
+    # Division is settled before the blanket null propagation below, because its two policies are
+    # about the denominator alone.  If the numerator decided whether a zero denominator refused,
+    # ``zero_denominator_policy`` would hold on some rows and not others for reasons having nothing
+    # to do with the denominator, which is the incidental behaviour a declared policy exists to
+    # rule out.  Inside ``_divide`` the null policy still propagates; it just does not get to
+    # answer first.
+    if op == "divide" and len(args) == 2:
+        return _divide(args, node_id)
+    if any(item is None for item in args):
+        return None
+    if op in {"add", "subtract", "multiply"} and len(args) == 2:
+        operand_types = tuple(_logical_type(item, node_id) for item in args)
+        if len(set(operand_types)) != 1 or operand_types[0] not in {
+            "int64",
+            "float64",
+            "decimal",
+        }:
+            raise GraphExecutionError(
+                "DERIVE_TYPE", node_id, "arithmetic requires one exact numeric logical type"
+            )
+        try:
+            if operand_types[0] == "decimal":
+                with localcontext() as context:
+                    context.prec = DECIMAL_WORKING_PRECISION
+                    result = {
+                        "add": args[0] + args[1],
+                        "subtract": args[0] - args[1],
+                        "multiply": args[0] * args[1],
+                    }[op]
+                result = _canonical_decimal(result, node_id)
+            else:
+                result = {
+                    "add": args[0] + args[1],
+                    "subtract": args[0] - args[1],
+                    "multiply": args[0] * args[1],
+                }[op]
+        except (TypeError, ValueError) as exc:
+            raise GraphExecutionError(
+                "DERIVE_TYPE", node_id, "derive operands are incompatible"
+            ) from exc
+        if isinstance(result, int) and not -(2**63) <= result < 2**63:
+            raise GraphExecutionError("DERIVE_OVERFLOW", node_id, "int64 arithmetic overflow")
+        _value_bytes(result, node_id)
+        return result
+    if op == "concat":
+        if any(not isinstance(item, str) for item in args):
+            raise GraphExecutionError("DERIVE_TYPE", node_id, "concat requires strings")
+        result = "".join(args)
+        _value_bytes(result, node_id)
+        return result
+    if op in {"trim", "case_fold"} and len(args) == 1:
+        if not isinstance(args[0], str):
+            raise GraphExecutionError("DERIVE_TYPE", node_id, f"{op} requires a string")
+        result = (
+            args[0].strip(ASCII_TRIM_CHARS) if op == "trim" else args[0].translate(_ASCII_CASE_FOLD)
+        )
+        _value_bytes(result, node_id)
+        return result
+    if op in {"year", "month", "day", "hour"} and len(args) == 1:
+        try:
+            if isinstance(args[0], datetime):
+                parsed = args[0]
+            elif isinstance(args[0], date):
+                if op == "hour":
+                    raise ValueError
+                return getattr(args[0], op)
+            else:
+                parsed = datetime.fromisoformat(str(args[0]).replace("Z", "+00:00"))
+            if parsed.tzinfo is None or parsed.utcoffset() is None:
+                raise ValueError
+        except (TypeError, ValueError) as exc:
+            raise GraphExecutionError(
+                "DERIVE_TYPE", node_id, "timestamp operand is invalid"
+            ) from exc
+        return getattr(parsed.astimezone(UTC), op)
+    raise GraphExecutionError("DERIVE_UNSUPPORTED", node_id, str(op))
+
+
+def _order_scalar(value: Any, node_id: str) -> tuple[int, Any]:
+    if type(value) is bool:
+        return (0, value)
+    if type(value) is int:
+        return (1, value)
+    if type(value) is float:
+        if not math.isfinite(value):
+            raise GraphExecutionError("NON_FINITE_VALUE", node_id, "non-finite floats refuse")
+        return (2, value)
+    if isinstance(value, Decimal):
+        return (3, value)
+    if isinstance(value, (date, datetime)):
+        return (4, value.isoformat())
+    if isinstance(value, str):
+        return (5, value)
+    raise GraphExecutionError("SORT_TYPE", node_id, f"unsupported sort value {type(value)!r}")
+
+
+def _sort_token(value: Any, *, nulls: str, direction: str, node_id: str) -> tuple[int, Any]:
+    null_rank = 0 if nulls == "first" else 2
+    if value is None:
+        return (null_rank, 0)
+    normalized = _order_scalar(value, node_id)
+    if direction == "desc":
+        return (1, _Descending(normalized))
+    return (1, normalized)
+
+
+@dataclass(frozen=True)
+class _Descending:
+    value: Any
+
+    def __lt__(self, other: _Descending) -> bool:
+        return self.value > other.value
+
+
+def _key_specs(value: Any, node_id: str) -> list[dict[str, str]]:
+    if not isinstance(value, list) or not value:
+        raise GraphExecutionError("OPERATION_PARAMETERS", node_id, "sort keys must be non-empty")
+    result: list[dict[str, str]] = []
+    for item in value:
+        if isinstance(item, str):
+            result.append({"column": item, "direction": "asc", "nulls": "last"})
+        elif isinstance(item, Mapping) and isinstance(item.get("column"), str):
+            direction = item.get("direction", "asc")
+            nulls = item.get("nulls", "last")
+            if direction not in {"asc", "desc"} or nulls not in {"first", "last"}:
+                raise GraphExecutionError("OPERATION_PARAMETERS", node_id, "invalid sort policy")
+            result.append({"column": item["column"], "direction": direction, "nulls": nulls})
+        else:
+            raise GraphExecutionError("OPERATION_PARAMETERS", node_id, "invalid sort key")
+    return result
+
+
+def _execute_node(
+    node: GraphNode,
+    inputs: tuple[GraphTable, ...],
+    source: GraphTable | None,
+    max_rows: int,
+    max_bytes: int,
+) -> tuple[GraphTable, int, int, str]:
+    params = _parameters(node)
+    if node.operation == "source":
+        assert source is not None
+        # A declared unit names a column the file has to hold. The plan cannot check that -- it
+        # does not know the header -- so it is checked here, where the header is known. One
+        # transposed letter would otherwise leave the declaration attached to nothing, and the two
+        # unit gates silently with nothing to compare in exactly the case they were written for.
+        declared = thaw_parameter(params.get("column_units"))
+        # An empty source has no columns to check against, and reporting every declaration as
+        # absent would name the wrong failure: the run already stops for the missing columns.
+        if isinstance(declared, Mapping) and source.columns:
+            absent = sorted(set(declared) - set(source.columns))
+            if absent:
+                raise GraphExecutionError(
+                    "UNIT_COLUMN_UNKNOWN",
+                    node.node_id,
+                    f"column_units declares columns this source does not hold: {absent}",
+                )
+            # A unit is a claim about a quantity, so the column has to hold one. The plan cannot
+            # tell -- it does not know the types either -- so this is the other half of the same
+            # check, and without it the merge gate ends up arbitrating units on strings.
+            unquantified = sorted(
+                column
+                for column in declared
+                if source.schema.get(column) not in {"int64", "float64", "decimal"}
+            )
+            if unquantified:
+                raise GraphExecutionError(
+                    "UNIT_COLUMN_NOT_NUMERIC",
+                    node.node_id,
+                    f"column_units declares columns that hold no quantity: {unquantified}",
+                )
+        return (
+            GraphTable(
+                source.columns,
+                source.rows,
+                _advance_lineage(node, source.lineage),
+                source.schema,
+            ),
+            0,
+            0,
+            "source order",
+        )
+    table = inputs[0]
+    index = _index(table, node.node_id)
+    if node.operation == "project":
+        columns = _columns(params["columns"], node.node_id)
+        _require_columns(table, columns, node.node_id)
+        return (
+            GraphTable(
+                columns,
+                tuple(tuple(row[index[col]] for col in columns) for row in table.rows),
+                _advance_lineage(
+                    node,
+                    MappingProxyType({column: table.lineage[column] for column in columns}),
+                ),
+                MappingProxyType({column: table.schema[column] for column in columns}),
+            ),
+            0,
+            0,
+            "input order",
+        )
+    if node.operation == "rename":
+        mappings = params["mappings"]
+        if not isinstance(mappings, Mapping):
+            raise GraphExecutionError(
+                "OPERATION_PARAMETERS", node.node_id, "mappings must be object"
+            )
+        _require_columns(table, mappings, node.node_id)
+        columns = tuple(str(mappings.get(column, column)) for column in table.columns)
+        if len(columns) != len(set(columns)):
+            raise GraphExecutionError("SCHEMA_DUPLICATE", node.node_id, "rename collides")
+        schema = MappingProxyType(
+            {str(mappings.get(column, column)): table.schema[column] for column in table.columns}
+        )
+        lineage = MappingProxyType(
+            {
+                str(mappings.get(column, column)): (
+                    _merge_lineage(node, table.lineage[column])
+                    if column in mappings
+                    else table.lineage[column]
+                )
+                for column in table.columns
+            }
+        )
+        return (
+            GraphTable(columns, table.rows, lineage, schema),
+            0,
+            0,
+            "input order",
+        )
+    if node.operation == "cast":
+        casts = params["columns"]
+        if not isinstance(casts, Mapping):
+            raise GraphExecutionError("OPERATION_PARAMETERS", node.node_id, "casts must be object")
+        _require_columns(table, casts, node.node_id)
+        rows = tuple(
+            tuple(
+                _cast(value, str(casts.get(column)), node.node_id) if column in casts else value
+                for column, value in zip(table.columns, row, strict=True)
+            )
+            for row in table.rows
+        )
+        schema = MappingProxyType(
+            {
+                column: str(casts[column]) if column in casts else table.schema[column]
+                for column in table.columns
+            }
+        )
+        return (
+            GraphTable(
+                table.columns,
+                rows,
+                MappingProxyType(
+                    {
+                        column: (
+                            _merge_lineage(node, table.lineage[column])
+                            if column in casts
+                            else table.lineage[column]
+                        )
+                        for column in table.columns
+                    }
+                ),
+                schema,
+            ),
+            0,
+            0,
+            "input order",
+        )
+    if node.operation == "filter":
+        selected: list[tuple[Any, ...]] = []
+        budget = _OutputBudget(node.node_id, max_rows, max_bytes)
+        for row in table.rows:
+            record = dict(zip(table.columns, row, strict=True))
+            if _predicate(params["predicate"], record, node.node_id) is True:
+                budget.retain(selected, row)
+        rows = tuple(selected)
+        return (
+            GraphTable(
+                table.columns,
+                rows,
+                _advance_lineage(node, table.lineage),
+                table.schema,
+            ),
+            len(table.rows) - len(rows),
+            0,
+            "stable filtered input order",
+        )
+    if node.operation == "derive":
+        expressions = params["expressions"]
+        if not isinstance(expressions, Mapping) or not expressions:
+            raise GraphExecutionError(
+                "OPERATION_PARAMETERS", node.node_id, "expressions must be object"
+            )
+        collisions = set(expressions) & set(table.columns)
+        if collisions:
+            raise GraphExecutionError(
+                "SCHEMA_DUPLICATE", node.node_id, f"derive collides: {sorted(collisions)}"
+            )
+        columns = (*table.columns, *expressions)
+        for specification in expressions.values():
+            expression_type = _expression_type(
+                specification["expression"], table.schema, node.node_id
+            )
+            output_type = str(specification["output_type"])
+            if expression_type not in {"null", output_type} and not (
+                expression_type == "int64" and output_type == "decimal"
+            ):
+                raise GraphExecutionError(
+                    "DERIVE_TYPE",
+                    node.node_id,
+                    f"expression type {expression_type} cannot produce {output_type}",
+                )
+        output_rows: list[tuple[Any, ...]] = []
+        budget = _OutputBudget(node.node_id, max_rows, max_bytes)
+        for row in table.rows:
+            record = dict(zip(table.columns, row, strict=True))
+            derived = tuple(
+                _cast(
+                    _derive(specification["expression"], record, node.node_id),
+                    specification["output_type"],
+                    node.node_id,
+                )
+                for specification in expressions.values()
+            )
+            budget.retain(output_rows, (*row, *derived))
+        rows = tuple(output_rows)
+        schema = dict(table.schema)
+        lineage = dict(table.lineage)
+        for name, specification in expressions.items():
+            schema[name] = str(specification["output_type"])
+            dependencies = tuple(
+                table.lineage[column] for column in _expression_columns(specification["expression"])
+            )
+            lineage[name] = (
+                _merge_lineage(node, *dependencies)
+                if dependencies
+                else ColumnLineage((), (_operation_coordinate(node),))
+            )
+        return (
+            GraphTable(
+                columns,
+                rows,
+                MappingProxyType(lineage),
+                MappingProxyType(schema),
+            ),
+            0,
+            0,
+            "input order",
+        )
+    if node.operation == "date_add_days":
+        # The parameter parser already settled these exact policies. Repeating the check at the
+        # executable boundary keeps a forged or legacy in-memory node from acquiring a second,
+        # implicit null or overflow behavior.
+        if params.get("null_policy") != "propagate" or params.get("overflow_policy") != "reject":
+            raise GraphExecutionError(
+                "OPERATION_PARAMETERS",
+                node.node_id,
+                "date_add_days policies differ from the closed contract",
+            )
+        days = params.get("days")
+        if (
+            isinstance(days, bool)
+            or not isinstance(days, int)
+            or not -MAX_DATE_ADD_DAYS <= days <= MAX_DATE_ADD_DAYS
+        ):
+            raise GraphExecutionError(
+                "OPERATION_PARAMETERS",
+                node.node_id,
+                f"days must be an integer from {-MAX_DATE_ADD_DAYS} to {MAX_DATE_ADD_DAYS}",
+            )
+        date_column = str(params["date_column"])
+        output_column = str(params["output_column"])
+        _require_columns(table, (date_column,), node.node_id)
+        if output_column in table.columns:
+            raise GraphExecutionError(
+                "DATE_ADD_DAYS_COLUMN", node.node_id, "output column already exists"
+            )
+        if table.schema[date_column] != "date":
+            raise GraphExecutionError(
+                "DATE_ADD_DAYS_TYPE",
+                node.node_id,
+                "date_column must be explicitly cast to date",
+            )
+        output_rows: list[tuple[Any, ...]] = []
+        budget = _OutputBudget(node.node_id, max_rows, max_bytes)
+        for row in table.rows:
+            value = row[index[date_column]]
+            if value is None:
+                result = None
+            elif type(value) is not date:
+                raise GraphExecutionError(
+                    "DATE_ADD_DAYS_TYPE", node.node_id, "date column contains a non-date value"
+                )
+            else:
+                try:
+                    # A ``date`` has no zone or time-of-day. This is calendar arithmetic, so the
+                    # result never depends on a DST transition or on elapsed hours.
+                    result = value + timedelta(days=days)
+                except OverflowError:
+                    raise GraphExecutionError(
+                        "DATE_ADD_DAYS_OVERFLOW",
+                        node.node_id,
+                        "calendar-day offset is outside the supported date range",
+                    ) from None
+            budget.retain(output_rows, (*row, result))
+        schema = dict(table.schema)
+        schema[output_column] = "date"
+        lineage = dict(table.lineage)
+        lineage[output_column] = _merge_lineage(node, table.lineage[date_column])
+        return (
+            GraphTable(
+                (*table.columns, output_column),
+                tuple(output_rows),
+                MappingProxyType(lineage),
+                MappingProxyType(schema),
+            ),
+            0,
+            0,
+            "input order; fixed calendar-day offset",
+        )
+    if node.operation == "unpivot":
+        value_columns = _columns(params["value_columns"], node.node_id)
+        _require_columns(table, value_columns, node.node_id)
+        if params.get("null_policy") != "retain":
+            raise GraphExecutionError(
+                "UNPIVOT_NULL_POLICY", node.node_id, "null policy must be retain"
+            )
+        name_column = str(params["name_column"])
+        value_column = str(params["value_column"])
+        melted = set(value_columns)
+        identity_columns = tuple(column for column in table.columns if column not in melted)
+        columns = (*identity_columns, name_column, value_column)
+        if len(columns) != len(set(columns)):
+            raise GraphExecutionError("SCHEMA_DUPLICATE", node.node_id, "unpivot columns collide")
+        # The long value column holds one column's worth of values per row, so every declared wide
+        # column must already be the type the plan declared for it.  Checking against the
+        # declaration rather than inferring from the columns is what keeps the output type
+        # readable from the recipe: an all-empty column would otherwise type the output
+        # differently from the same recipe's last run.  A plan whose wide columns disagree casts
+        # them first.
+        value_type = str(params["value_type"])
+        observed = {table.schema[column] for column in value_columns} - {"null"}
+        if observed - {value_type}:
+            raise GraphExecutionError(
+                "UNPIVOT_VALUE_TYPE",
+                node.node_id,
+                f"declared value columns are not all {value_type}: {sorted(observed)}",
+            )
+        # The expansion factor is declared, so the refusal can come before the copy exists.
+        if len(table.rows) * len(value_columns) > max_rows:
+            raise GraphExecutionError(
+                "ROW_BUDGET_EXCEEDED", node.node_id, f"unpivot upper bound exceeds {max_rows}"
+            )
+        output_rows = []
+        budget = _OutputBudget(node.node_id, max_rows, max_bytes)
+        for row in table.rows:
+            identity = tuple(row[index[column]] for column in identity_columns)
+            for column in value_columns:
+                budget.retain(output_rows, (*identity, column, row[index[column]]))
+        melted_lineage = _merge_lineage(node, *(table.lineage[column] for column in value_columns))
+        return (
+            GraphTable(
+                columns,
+                tuple(output_rows),
+                MappingProxyType(
+                    {
+                        **dict(
+                            _advance_lineage(
+                                node,
+                                MappingProxyType(
+                                    {column: table.lineage[column] for column in identity_columns}
+                                ),
+                            )
+                        ),
+                        name_column: melted_lineage,
+                        value_column: melted_lineage,
+                    }
+                ),
+                MappingProxyType(
+                    {
+                        **{column: table.schema[column] for column in identity_columns},
+                        name_column: "string",
+                        value_column: value_type,
+                    }
+                ),
+            ),
+            0,
+            0,
+            "input order then declared value-column order",
+        )
+    if node.operation == "union":
+        safe_casts = params["safe_casts"]
+        if not isinstance(safe_casts, Mapping):
+            raise GraphExecutionError(
+                "OPERATION_PARAMETERS", node.node_id, "safe_casts must be an object"
+            )
+        unknown_casts = sorted(set(safe_casts) - set(table.columns))
+        if unknown_casts:
+            raise GraphExecutionError(
+                "COLUMN_UNKNOWN", node.node_id, f"safe casts name absent columns: {unknown_casts}"
+            )
+        target_schema = {
+            column: str(safe_casts.get(column, table.schema[column])) for column in table.columns
+        }
+        for candidate in inputs[1:]:
+            if candidate.columns != table.columns:
+                raise GraphExecutionError(
+                    "UNION_SCHEMA_MISMATCH",
+                    node.node_id,
+                    "union inputs require exact ordered logical schema",
+                )
+        for candidate in inputs:
+            for column in table.columns:
+                source_type = candidate.schema[column]
+                target_type = target_schema[column]
+                if source_type == target_type or source_type == "null":
+                    continue
+                if (source_type, target_type) != ("int64", "decimal"):
+                    raise GraphExecutionError(
+                        "UNION_SCHEMA_MISMATCH",
+                        node.node_id,
+                        f"unsafe logical cast {column}: {source_type}->{target_type}",
+                    )
+        total = sum(len(candidate.rows) for candidate in inputs)
+        if total > max_rows:
+            raise GraphExecutionError(
+                "ROW_BUDGET_EXCEEDED", node.node_id, f"union exceeds {max_rows}"
+            )
+        union_rows: list[tuple[Any, ...]] = []
+        budget = _OutputBudget(node.node_id, max_rows, max_bytes)
+        for candidate in inputs:
+            for row in candidate.rows:
+                converted = tuple(
+                    _cast(value, target_schema[column], node.node_id)
+                    if candidate.schema[column] != target_schema[column]
+                    and candidate.schema[column] != "null"
+                    else value
+                    for column, value in zip(candidate.columns, row, strict=True)
+                )
+                budget.retain(union_rows, converted)
+        return (
+            GraphTable(
+                table.columns,
+                tuple(union_rows),
+                MappingProxyType(
+                    {
+                        column: _merge_lineage(
+                            node, *(candidate.lineage[column] for candidate in inputs)
+                        )
+                        for column in table.columns
+                    }
+                ),
+                MappingProxyType(target_schema),
+            ),
+            0,
+            0,
+            "declared input order then source order",
+        )
+    if node.operation in {"sort", "deduplicate"}:
+        specs = _key_specs(
+            params["keys"] if node.operation == "sort" else params["authority"], node.node_id
+        )
+        if node.operation == "deduplicate":
+            keys = _columns(params["keys"], node.node_id)
+            _require_columns(table, keys, node.node_id)
+            if params.get("tie_policy") != "stable_first":
+                raise GraphExecutionError(
+                    "DEDUP_TIE_POLICY", node.node_id, "tie policy must be stable_first"
+                )
+        _require_columns(table, (item["column"] for item in specs), node.node_id)
+        if node.operation == "sort":
+            # Sorting preserves every logical scalar, so refuse before allocating its ordering
+            # index rather than discovering an oversized output after the full copy exists.
+            if len(table.rows) > max_rows:
+                raise GraphExecutionError(
+                    "ROW_BUDGET_EXCEEDED", node.node_id, f"sort exceeds {max_rows}"
+                )
+            if _table_bytes(table, node.node_id) > max_bytes:
+                raise GraphExecutionError(
+                    "BYTE_BUDGET_EXCEEDED", node.node_id, f"sort exceeds {max_bytes}"
+                )
+        ordered = sorted(
+            enumerate(table.rows),
+            key=lambda pair: (
+                (
+                    *(
+                        _sort_token(
+                            pair[1][index[item["column"]]],
+                            nulls=item["nulls"],
+                            direction=item["direction"],
+                            node_id=node.node_id,
+                        )
+                        for item in specs
+                    ),
+                    pair[0],
+                )
+            ),
+        )
+        if node.operation == "sort":
+            return (
+                GraphTable(
+                    table.columns,
+                    tuple(row for _, row in ordered),
+                    _advance_lineage(node, table.lineage),
+                    table.schema,
+                ),
+                0,
+                0,
+                "declared keys then stable ordinal",
+            )
+        seen: set[tuple[tuple[str, Any], ...]] = set()
+        retained: list[tuple[int, tuple[Any, ...]]] = []
+        for ordinal, row in ordered:
+            values = tuple(row[index[column]] for column in keys)
+            if any(value is None for value in values):
+                raise GraphExecutionError(
+                    "DEDUP_NULL_KEY", node.node_id, "deduplication key contains null"
+                )
+            key = tuple(
+                (table.schema[column], value) for column, value in zip(keys, values, strict=True)
+            )
+            if key in seen:
+                continue
+            seen.add(key)
+            retained.append((ordinal, row))
+        retained.sort(key=lambda pair: pair[0])
+        duplicates = len(table.rows) - len(retained)
+        return (
+            GraphTable(
+                table.columns,
+                tuple(row for _, row in retained),
+                _advance_lineage(node, table.lineage),
+                table.schema,
+            ),
+            0,
+            duplicates,
+            "authority then stable original ordinal",
+        )
+    if node.operation == "prediction_label":
+        fixed_policies = {
+            "null_key_policy": "reject",
+            "duplicate_key_policy": "reject",
+            "missing_target_policy": "drop",
+            "null_target_policy": "drop",
+            "boundary_policy": "drop",
+        }
+        if any(params.get(name) != expected for name, expected in fixed_policies.items()):
+            raise GraphExecutionError(
+                "OPERATION_PARAMETERS",
+                node.node_id,
+                "prediction label policies differ from the closed contract",
+            )
+        horizon_days = params.get("horizon_days")
+        if (
+            isinstance(horizon_days, bool)
+            or not isinstance(horizon_days, int)
+            or not 1 <= horizon_days <= 3_650
+        ):
+            raise GraphExecutionError(
+                "OPERATION_PARAMETERS",
+                node.node_id,
+                "horizon_days must be an integer from 1 to 3650",
+            )
+        raw_partition_by = params["partition_by"]
+        if (
+            not isinstance(raw_partition_by, list)
+            or any(not isinstance(item, str) or not item for item in raw_partition_by)
+            or len(raw_partition_by) != len(set(raw_partition_by))
+        ):
+            raise GraphExecutionError(
+                "OPERATION_PARAMETERS",
+                node.node_id,
+                "partition_by must be a unique text list and may be empty",
+            )
+        partition_by = tuple(raw_partition_by)
+        time_column = str(params["time_column"])
+        source_column = str(params["source_column"])
+        output_column = str(params["output_column"])
+        _require_columns(table, (*partition_by, time_column, source_column), node.node_id)
+        if output_column in table.columns:
+            raise GraphExecutionError(
+                "PREDICTION_LABEL_COLUMN",
+                node.node_id,
+                "output column already exists",
+            )
+        if table.schema[time_column] not in {"date", "timestamp_utc"}:
+            raise GraphExecutionError(
+                "PREDICTION_LABEL_TIME_TYPE",
+                node.node_id,
+                "time column must be explicitly cast to date or timestamp_utc",
+            )
+
+        def temporal_key(value: Any) -> date | datetime:
+            if table.schema[time_column] == "date":
+                if type(value) is not date:
+                    raise GraphExecutionError(
+                        "PREDICTION_LABEL_TIME_TYPE",
+                        node.node_id,
+                        "date time column contains a non-date value",
+                    )
+                return value
+            if not isinstance(value, datetime) or value.tzinfo is None or value.utcoffset() is None:
+                raise GraphExecutionError(
+                    "PREDICTION_LABEL_TIME_TYPE",
+                    node.node_id,
+                    "timestamp time column contains a non-UTC value",
+                )
+            return value.astimezone(UTC)
+
+        keyed: dict[tuple[Any, ...], tuple[Any, ...]] = {}
+        ordered: list[tuple[tuple[Any, ...], date | datetime, tuple[Any, ...]]] = []
+        for row in table.rows:
+            partition = tuple(row[index[column]] for column in partition_by)
+            raw_time = row[index[time_column]]
+            if any(value is None for value in partition) or raw_time is None:
+                raise GraphExecutionError(
+                    "PREDICTION_LABEL_NULL_KEY",
+                    node.node_id,
+                    "partition and time keys must be non-null",
+                )
+            time = temporal_key(raw_time)
+            key = (*partition, time)
+            if key in keyed:
+                raise GraphExecutionError(
+                    "PREDICTION_LABEL_DUPLICATE_KEY",
+                    node.node_id,
+                    "partition and time keys must be unique",
+                )
+            keyed[key] = row
+            ordered.append((partition, time, row))
+        ordered.sort(
+            key=lambda item: (
+                *(
+                    _sort_token(
+                        value,
+                        nulls="last",
+                        direction="asc",
+                        node_id=node.node_id,
+                    )
+                    for value in item[0]
+                ),
+                _sort_token(
+                    item[1],
+                    nulls="last",
+                    direction="asc",
+                    node_id=node.node_id,
+                ),
+            )
+        )
+        horizon = timedelta(days=horizon_days)
+        output: list[tuple[Any, ...]] = []
+        budget = _OutputBudget(node.node_id, max_rows, max_bytes)
+        rejected = 0
+        for partition, time, row in ordered:
+            try:
+                target_time = time + horizon
+            except (OverflowError, ValueError) as exc:
+                raise GraphExecutionError(
+                    "PREDICTION_LABEL_TIME_RANGE",
+                    node.node_id,
+                    "future target date is outside the supported calendar range",
+                ) from exc
+            target = keyed.get((*partition, target_time))
+            if target is None or target[index[source_column]] is None:
+                rejected += 1
+                continue
+            budget.retain(output, (*row, target[index[source_column]]))
+        return (
+            GraphTable(
+                (*table.columns, output_column),
+                tuple(output),
+                MappingProxyType(
+                    {
+                        **dict(_advance_lineage(node, table.lineage)),
+                        output_column: _merge_lineage(node, table.lineage[source_column]),
+                    }
+                ),
+                MappingProxyType(
+                    {
+                        **dict(table.schema),
+                        output_column: table.schema[source_column],
+                    }
+                ),
+            ),
+            rejected,
+            0,
+            "partition keys ascending then exact calendar date ascending",
+        )
+    if node.operation == "join":
+        right = inputs[1]
+        right_index = _index(right, node.node_id)
+        keys = _columns(params["on"], node.node_id)
+        _require_columns(table, keys, node.node_id)
+        _require_columns(right, keys, node.node_id)
+        incompatible = [column for column in keys if table.schema[column] != right.schema[column]]
+        if incompatible:
+            raise GraphExecutionError(
+                "JOIN_KEY_TYPE",
+                node.node_id,
+                f"join keys have incompatible logical types: {incompatible}",
+            )
+        if len(table.rows) > max_rows:
+            raise GraphExecutionError(
+                "ROW_BUDGET_EXCEEDED", node.node_id, f"join upper bound exceeds {max_rows}"
+            )
+        left_bytes = _table_bytes(table, node.node_id)
+        kind = params["kind"]
+        # An anti join answers "which left rows have no match", so no right row is ever emitted
+        # and the right table contributes no columns.  Carrying them across as nulls would put a
+        # column in the output whose every value was manufactured by the join itself.
+        right_extra = (
+            ()
+            if kind == "anti"
+            else tuple(column for column in right.columns if column not in keys)
+        )
+        right_extra_max = max(
+            (
+                sum(_value_bytes(row[right_index[column]], node.node_id) for column in right_extra)
+                for row in right.rows
+            ),
+            default=sum(_value_bytes(None, node.node_id) for _ in right_extra),
+        )
+        if left_bytes + len(table.rows) * right_extra_max > max_bytes:
+            raise GraphExecutionError(
+                "BYTE_BUDGET_EXCEEDED", node.node_id, f"join upper bound exceeds {max_bytes}"
+            )
+        lookup: dict[tuple[tuple[str, Any], ...], list[tuple[Any, ...]]] = defaultdict(list)
+        for row in right.rows:
+            values = tuple(row[right_index[column]] for column in keys)
+            if any(value is None for value in values) and params["null_key_policy"] == "reject":
+                raise GraphExecutionError("JOIN_NULL_KEY", node.node_id, "right null key")
+            key = tuple(
+                (right.schema[column], value) for column, value in zip(keys, values, strict=True)
+            )
+            lookup[key].append(row)
+        # What the declared cardinality is for is bounding how far the output may grow, and an
+        # anti join reaches that bound by construction: it emits the left rows that matched
+        # nothing, so it is a subset of the left table however many right rows share a key.
+        # Matching there is existence, not lookup, and a duplicated right key cannot multiply a
+        # row that is only ever emitted when no right row was found.  So the right-key uniqueness
+        # rule the other kinds carry is not applied to ``anti``; requiring it would refuse the
+        # plainest anti join there is -- facilities with no readings, against a readings table
+        # that of course holds many rows per facility.  The left rule below is unchanged for
+        # every kind: ``one_to_one`` still says each left key appears once.
+        cardinality = params["cardinality"]
+        if (
+            kind != "anti"
+            and cardinality in {"one_to_one", "many_to_one"}
+            and any(len(rows) > 1 for rows in lookup.values())
+        ):
+            raise GraphExecutionError("JOIN_CARDINALITY", node.node_id, "right key is not unique")
+        output_columns = (*table.columns, *right_extra)
+        if len(output_columns) != len(set(output_columns)):
+            raise GraphExecutionError("SCHEMA_DUPLICATE", node.node_id, "join columns collide")
+        output: list[tuple[Any, ...]] = []
+        budget = _OutputBudget(node.node_id, max_rows, max_bytes)
+        rejected = 0
+        left_seen: set[tuple[tuple[str, Any], ...]] = set()
+        for left_row in table.rows:
+            values = tuple(left_row[index[column]] for column in keys)
+            if any(value is None for value in values):
+                raise GraphExecutionError("JOIN_NULL_KEY", node.node_id, "left null key")
+            key = tuple(
+                (table.schema[column], value) for column, value in zip(keys, values, strict=True)
+            )
+            if cardinality == "one_to_one" and key in left_seen:
+                raise GraphExecutionError(
+                    "JOIN_CARDINALITY", node.node_id, "left key is not unique"
+                )
+            left_seen.add(key)
+            matches = lookup.get(key, [])
+            if not matches:
+                if params["unmatched_policy"] == "reject":
+                    raise GraphExecutionError(
+                        "JOIN_UNMATCHED", node.node_id, "left row is unmatched"
+                    )
+                if kind in {"left", "anti"}:
+                    budget.retain(output, (*left_row, *(None for _ in right_extra)))
+                else:
+                    rejected += 1
+                continue
+            if kind == "anti":
+                rejected += 1
+                continue
+            for right_row in matches:
+                budget.retain(
+                    output,
+                    (*left_row, *(right_row[right_index[column]] for column in right_extra)),
+                )
+        return (
+            GraphTable(
+                output_columns,
+                tuple(output),
+                MappingProxyType(
+                    {
+                        **{
+                            column: _merge_lineage(node, item)
+                            for column, item in table.lineage.items()
+                        },
+                        **{
+                            column: _merge_lineage(node, right.lineage[column])
+                            for column in right_extra
+                        },
+                    }
+                ),
+                MappingProxyType(
+                    {
+                        **dict(table.schema),
+                        **{column: right.schema[column] for column in right_extra},
+                    }
+                ),
+            ),
+            rejected,
+            0,
+            "left order" if kind == "anti" else "left order then right source order",
+        )
+    if node.operation in {"aggregate", "resample"}:
+        return _aggregate(
+            node,
+            table,
+            params,
+            resample=node.operation == "resample",
+            max_rows=max_rows,
+            max_bytes=max_bytes,
+        )
+    raise GraphExecutionError("OPERATION_UNSUPPORTED", node.node_id, node.operation)
+
+
+def _decimal(value: Any, node_id: str, *, code: str = "AGGREGATE_VALUE") -> Decimal:
+    """Move one numeric scalar into the canonical decimal domain.
+
+    ``code`` names the caller's refusal so a derive expression does not report a measure error.
+    """
+
+    try:
+        result = Decimal(str(value))
+    except (InvalidOperation, ValueError) as exc:
+        raise GraphExecutionError(code, node_id, "value is not numeric") from exc
+    return _canonical_decimal(result, node_id)
+
+
+def _aggregate(
+    node: GraphNode,
+    table: GraphTable,
+    params: dict[str, Any],
+    *,
+    resample: bool,
+    max_rows: int,
+    max_bytes: int,
+) -> tuple[GraphTable, int, int, str]:
+    group_by = _columns(params["group_by"], node.node_id) if params["group_by"] else ()
+    _require_columns(table, group_by, node.node_id)
+    measures = params["aggregates"] if resample else params["measures"]
+    if not isinstance(measures, list) or not measures:
+        raise GraphExecutionError("OPERATION_PARAMETERS", node.node_id, "measures must be list")
+    event_time = str(params["event_time"]) if resample else None
+    if resample:
+        if params["timezone"] != "UTC":
+            raise GraphExecutionError(
+                "RESAMPLE_TIMEZONE_UNSUPPORTED", node.node_id, "only UTC is deterministic"
+            )
+        _require_columns(table, [event_time], node.node_id)  # type: ignore[list-item]
+    table_index = _index(table, node.node_id)
+    groups: dict[tuple[Any, ...], list[tuple[Any, ...]]] = defaultdict(list)
+    duration = int(params.get("duration_seconds", 0))
+    epoch = datetime(1970, 1, 1, tzinfo=UTC)
+    for row in table.rows:
+        key = tuple(row[table_index[column]] for column in group_by)
+        if resample:
+            try:
+                raw_time = row[table_index[event_time]]  # type: ignore[index]
+                if isinstance(raw_time, datetime):
+                    parsed = raw_time
+                elif isinstance(raw_time, str) and raw_time.endswith("Z"):
+                    parsed = datetime.fromisoformat(raw_time.replace("Z", "+00:00"))
+                else:
+                    raise ValueError
+            except (TypeError, ValueError) as exc:
+                raise GraphExecutionError(
+                    "RESAMPLE_TIME_INVALID", node.node_id, "event time is invalid"
+                ) from exc
+            if parsed.tzinfo is None or parsed.utcoffset() is None or duration <= 0:
+                raise GraphExecutionError(
+                    "RESAMPLE_TIME_INVALID", node.node_id, "UTC timestamp/duration required"
+                )
+            utc_time = parsed.astimezone(UTC)
+            delta = utc_time - epoch
+            microseconds = (delta.days * 86_400 + delta.seconds) * 1_000_000 + delta.microseconds
+            duration_microseconds = duration * 1_000_000
+            bucket_microseconds = (microseconds // duration_microseconds) * duration_microseconds
+            key = (
+                *key,
+                epoch + timedelta(microseconds=bucket_microseconds),
+            )
+        groups[key].append(row)
+    output_names: list[str] = [*group_by]
+    if resample:
+        output_names.append(f"{event_time}_bucket")
+    for measure in measures:
+        if not isinstance(measure, Mapping) or not all(
+            key in measure for key in ("column", "op", "as")
+        ):
+            raise GraphExecutionError("OPERATION_PARAMETERS", node.node_id, "invalid measure")
+        output_names.append(str(measure["as"]))
+    if len(output_names) != len(set(output_names)):
+        raise GraphExecutionError("SCHEMA_DUPLICATE", node.node_id, "aggregate names collide")
+    output: list[tuple[Any, ...]] = []
+    budget = _OutputBudget(node.node_id, max_rows, max_bytes)
+    for key in sorted(
+        groups,
+        key=lambda item: tuple(
+            _sort_token(value, nulls="last", direction="asc", node_id=node.node_id)
+            for value in item
+        ),
+    ):
+        rows = groups[key]
+        values: list[Any] = list(key)
+        for measure in measures:
+            column, op = str(measure["column"]), str(measure["op"])
+            _require_columns(table, [column], node.node_id)
+            if op in {"sum", "mean"} and table.schema[column] not in {
+                "int64",
+                "float64",
+                "decimal",
+            }:
+                raise GraphExecutionError(
+                    "AGGREGATE_VALUE",
+                    node.node_id,
+                    "sum and mean require an explicitly numeric input column",
+                )
+            column_index = table_index[column]
+            present = [row[column_index] for row in rows if row[column_index] is not None]
+            if op == "count":
+                value: Any = len(present)
+            elif not present:
+                value = None
+            elif op == "sum":
+                with localcontext() as context:
+                    context.prec = DECIMAL_WORKING_PRECISION
+                    total = sum((_decimal(item, node.node_id) for item in present), Decimal(0))
+                value = _canonical_decimal(total, node.node_id)
+            elif op == "mean":
+                with localcontext() as context:
+                    context.prec = DECIMAL_WORKING_PRECISION
+                    mean = sum(
+                        (_decimal(item, node.node_id) for item in present), Decimal(0)
+                    ) / len(present)
+                    # A repeating quotient cannot be represented exactly in decimal256(76,38).
+                    # The operation contract therefore rounds once, at the physical scale, using
+                    # banker's rounding.  Every engine routes through this shared scalar kernel.
+                    mean = mean.quantize(DECIMAL_QUANTUM, rounding=ROUND_HALF_EVEN)
+                value = _canonical_decimal(mean, node.node_id)
+            elif op == "min":
+                try:
+                    value = min(present)
+                except TypeError as exc:
+                    raise GraphExecutionError(
+                        "AGGREGATE_VALUE", node.node_id, "measure values are incompatible"
+                    ) from exc
+            elif op == "max":
+                try:
+                    value = max(present)
+                except TypeError as exc:
+                    raise GraphExecutionError(
+                        "AGGREGATE_VALUE", node.node_id, "measure values are incompatible"
+                    ) from exc
+            elif op == "first":
+                value = present[0]
+            elif op == "last":
+                value = present[-1]
+            else:
+                raise GraphExecutionError("AGGREGATE_UNSUPPORTED", node.node_id, op)
+            values.append(value)
+        budget.retain(output, tuple(values))
+    schema = {column: table.schema[column] for column in group_by}
+    if resample:
+        schema[f"{event_time}_bucket"] = "timestamp_utc"
+    for measure in measures:
+        operation = str(measure["op"])
+        schema[str(measure["as"])] = (
+            "int64"
+            if operation == "count"
+            else "decimal"
+            if operation in {"sum", "mean"}
+            else table.schema[str(measure["column"])]
+        )
+    lineage: dict[str, ColumnLineage] = {
+        column: _merge_lineage(node, table.lineage[column]) for column in group_by
+    }
+    if resample:
+        lineage[f"{event_time}_bucket"] = _merge_lineage(node, table.lineage[str(event_time)])
+    for measure in measures:
+        lineage[str(measure["as"])] = _merge_lineage(node, table.lineage[str(measure["column"])])
+    return (
+        GraphTable(
+            tuple(output_names),
+            tuple(output),
+            MappingProxyType(lineage),
+            MappingProxyType(schema),
+        ),
+        0,
+        0,
+        "group keys ascending; stable first/last",
+    )
+
+
+def execute_graph(
+    plan: GraphTablePlan,
+    sources: Mapping[str, Iterable[Mapping[str, Any]]],
+    *,
+    policy: GraphResourcePolicy | None = None,
+    engine: str = "reference",
+    backend: Backend | None = None,
+    source_columns: Mapping[str, Iterable[str]] | None = None,
+    node_started: Callable[[GraphNode], None] | None = None,
+    node_observer: Callable[[GraphNode, GraphTable, NodeAudit, Mapping[str, GraphTable]], None]
+    | None = None,
+) -> GraphExecution:
+    if backend is None and engine not in {"reference", "reference-graph-kernel"}:
+        raise GraphExecutionError(
+            "ENGINE_RESTRICTED",
+            "graph",
+            "local-graph-table-plan.v1 currently executes only on the reference graph kernel",
+        )
+    backend_name = "reference" if backend is None else backend.name
+    engine = f"shared-graph-kernel+{backend_name}"
+    policy = policy or GraphResourcePolicy()
+    declared = {source.source_id for source in plan.sources}
+    if set(sources) != declared:
+        raise GraphExecutionError("SOURCE_SET_MISMATCH", "graph", "source rows must match plan")
+    declared_source_columns = (
+        {source_id: tuple(columns) for source_id, columns in source_columns.items()}
+        if source_columns is not None
+        else {}
+    )
+    if source_columns is not None and set(declared_source_columns) != declared:
+        raise GraphExecutionError("SOURCE_SET_MISMATCH", "graph", "source schemas must match plan")
+    if any(
+        not columns or len(columns) != len(set(columns))
+        for columns in declared_source_columns.values()
+    ):
+        raise GraphExecutionError(
+            "SOURCE_SCHEMA_INVALID", "graph", "source schema columns must be non-empty and unique"
+        )
+    active_tables: dict[str, GraphTable] = {}
+    snapshots: dict[str, GraphTable] = {}
+    audits: list[NodeAudit] = []
+    retained_bytes = 0
+    peak_retained_bytes = 0
+    remaining_consumers = {
+        node.node_id: sum(candidate.inputs.count(node.node_id) for candidate in plan.nodes)
+        for node in plan.nodes
+    }
+    for node in plan.nodes:
+        if node_started is not None:
+            node_started(node)
+        inputs = tuple(active_tables[input_id] for input_id in node.inputs)
+        source_id = str(_parameters(node)["source"]) if node.operation == "source" else None
+        limit = (
+            policy.max_output_rows
+            if node.node_id == plan.terminal
+            else policy.max_intermediate_rows
+        )
+        scope_byte_limit = (
+            policy.max_source_bytes
+            if node.operation == "source"
+            else policy.max_output_bytes
+            if node.node_id == plan.terminal
+            else policy.max_intermediate_bytes
+        )
+        source_table = (
+            _table_from_records(
+                node.node_id,
+                source_id,
+                sources[source_id],
+                policy.max_source_rows,
+                min(policy.max_source_bytes, policy.max_retained_bytes - retained_bytes),
+                declared_source_columns.get(source_id),
+            )
+            if source_id is not None
+            else None
+        )
+        table, rejected, duplicates, order = _execute_node(
+            node, inputs, source_table, limit, scope_byte_limit
+        )
+        table_bytes = _table_bytes(table, node.node_id)
+        # A backend materialization transiently holds the contract table and its engine-shaped
+        # copy alongside every still-live input. This is canonical logical byte accounting, not
+        # an RSS claim, and refuses before asking an engine to allocate the copy.
+        transient_bytes = retained_bytes + (2 * table_bytes if backend is not None else table_bytes)
+        if transient_bytes > policy.max_retained_bytes:
+            raise GraphExecutionError(
+                "BYTE_BUDGET_EXCEEDED",
+                node.node_id,
+                f"logical transient tables exceed {policy.max_retained_bytes}",
+            )
+        peak_retained_bytes = max(peak_retained_bytes, transient_bytes)
+        if backend is not None:
+            try:
+                materialized = backend.materialize_graph_rows(table.columns, table.rows)
+            except Exception as exc:
+                raise GraphExecutionError(
+                    "ENGINE_EXECUTION_FAILED",
+                    node.node_id,
+                    f"{backend.name} could not materialize the graph node",
+                ) from exc
+            if materialized != table.rows:
+                raise GraphExecutionError(
+                    "ENGINE_DIVERGENCE",
+                    node.node_id,
+                    f"{backend.name} changed contract-owned graph scalars or ordering",
+                )
+            table = GraphTable(table.columns, materialized, table.lineage, table.schema)
+        if len(table.rows) > limit:
+            scope = "output" if node.node_id == plan.terminal else "intermediate"
+            raise GraphExecutionError(
+                "ROW_BUDGET_EXCEEDED", node.node_id, f"{scope} exceeds {limit}"
+            )
+        if table_bytes > scope_byte_limit:
+            scope = (
+                "source"
+                if node.operation == "source"
+                else "output"
+                if node.node_id == plan.terminal
+                else "intermediate"
+            )
+            raise GraphExecutionError(
+                "BYTE_BUDGET_EXCEEDED",
+                node.node_id,
+                f"{scope} exceeds {scope_byte_limit}",
+            )
+        for input_id in node.inputs:
+            remaining_consumers[input_id] -= 1
+            if remaining_consumers[input_id] == 0:
+                retained_bytes -= _table_bytes(active_tables.pop(input_id), node.node_id)
+        retained_bytes += table_bytes
+        if retained_bytes > policy.max_retained_bytes:
+            raise GraphExecutionError(
+                "BYTE_BUDGET_EXCEEDED",
+                node.node_id,
+                f"retained graph tables exceed {policy.max_retained_bytes}",
+            )
+        input_digests = tuple(table_digest(item) for item in inputs)
+        audit = NodeAudit(
+            node.node_id,
+            node.operation,
+            node.operation_version,
+            node.inputs,
+            _digest(_parameters(node)),
+            input_digests,
+            table_digest(table),
+            sum(len(item.rows) for item in inputs),
+            len(table.rows),
+            rejected,
+            duplicates,
+            order,
+            engine,
+            tuple(_schema_items(item) for item in inputs),
+            _schema_items(table),
+            sum(_table_bytes(item, node.node_id) for item in inputs),
+            table_bytes,
+            retained_bytes,
+        )
+        audits.append(audit)
+        active_tables[node.node_id] = table
+        snapshots[node.node_id] = GraphTable(
+            table.columns,
+            table.rows[:5],
+            table.lineage,
+            table.schema,
+        )
+        if node_observer is not None:
+            node_observer(
+                node,
+                table,
+                audit,
+                MappingProxyType(dict(zip(node.inputs, inputs, strict=True))),
+            )
+    terminal = active_tables[plan.terminal]
+    if terminal.columns != plan.output_columns:
+        raise GraphExecutionError(
+            "OUTPUT_SCHEMA_MISMATCH", plan.terminal, "terminal columns differ from output_columns"
+        )
+    if len(terminal.rows) < plan.quality.min_rows:
+        raise GraphExecutionError(
+            "QUALITY_MIN_ROWS", plan.terminal, "terminal row count is too small"
+        )
+    terminal_index = _index(terminal, plan.terminal)
+    for column in dict.fromkeys((*plan.grain, *plan.quality.not_null)):
+        if any(row[terminal_index[column]] is None for row in terminal.rows):
+            raise GraphExecutionError("QUALITY_NOT_NULL", plan.terminal, f"{column} contains null")
+    return GraphExecution(
+        terminal,
+        tuple(audits),
+        MappingProxyType(snapshots),
+        peak_retained_bytes,
+    )
+
+
+__all__ = [
+    "ASCII_TRIM_CHARS",
+    "HARD_MAX_FIELD_BYTES",
+    "HARD_MAX_INTERMEDIATE_ROWS",
+    "HARD_MAX_OUTPUT_ROWS",
+    "HARD_MAX_RETAINED_BYTES",
+    "HARD_MAX_SOURCE_ROWS",
+    "ColumnLineage",
+    "GraphExecution",
+    "GraphExecutionError",
+    "GraphResourcePolicy",
+    "GraphTable",
+    "NodeAudit",
+    "execute_graph",
+    "table_digest",
+]