mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/backends/polars_backend.py

@@ -0,0 +1,366 @@
+"""The polars backend: ``PolarsBackend`` over an eager ``pl.DataFrame`` container.
+
+The direct twin of ``PandasBackend`` with the engine swapped. ``PolarsBackend`` re-owns the
+narrow ``clean -> join -> select`` triple behind the ``Backend`` protocol; every other
+candidate byte is still produced by the shared layer (the one pyarrow sink, the canonical
+schema, ``_coerce_native_rows``, the evidence serializer). Because the shared layer
+downstream is unchanged, the backend's job is to reproduce the reference compute
+byte-identically while genuinely exercising a polars object.
+
+Design (the load-bearing execution posture):
+
+- The row-shape transforms (``clean``/``join``/``select``) are computed **value-wise** in
+  plain Python, mirroring ``pipeline._apply_cleaning`` / ``_join`` / ``_select`` exactly so
+  unicode-whitespace, empty-vs-null, ordering, and the typed ``BuildError`` refusals match
+  the reference bit-for-bit. Every value-level cast routes through the shared
+  ``pipeline._cast`` — never an engine-native parser, which is what keeps cast results and
+  cast refusals identical across engines.
+- The op's output is then materialized as an **eager** ``pl.DataFrame`` — one explicit
+  polars dtype per column drawn from the closed ``_POLARS_BY_LOGICAL`` vocabulary aligned to
+  the sink's ``pipeline._ARROW_BY_LOGICAL`` map, constructed from the already-typed native
+  values (never inferred, never an engine-native cast token, never a ``pl.DataFrame`` handed
+  to the sink). Explicit ``pl.Int64``/``pl.Float64``/``pl.String``/``pl.Boolean``/``pl.Date``/
+  UTC ``pl.Datetime`` columns carry
+  true polars nulls (never ``NaN``) and keep an ``int64`` column ``int64`` under nulls (no
+  int->float promotion).
+- The frame is used **only** as a typed shaping/materialization container: it is never a
+  lazy frame, is never collected, never runs a polars ``join``/``group_by``, never enables the
+  global string cache, and never uses a polars categorical type. Order is imposed
+  positionally in Python (strictly stronger than any polars ordering guarantee), so polars'
+  documented ordering/streaming/thread nondeterminism can never touch the digest path, and the
+  streaming engine is structurally unreachable.
+- The frame is converted back to an ordered native ``list[dict]`` at the boundary
+  (``_rows_from_frame``): column order = the frame's schema order, and each cell is read
+  through polars' native ``to_dicts()`` so a polars null becomes Python ``None``, a
+  ``pl.String`` cell (Arrow ``large_utf8`` internally) becomes a native ``str`` with no width
+  tag, a ``pl.Date`` cell becomes ``datetime.date``, and an ``pl.Int64``/``pl.Float64`` cell
+  becomes a native ``int``/``float`` — no engine scalar. Because the backend returns native
+  rows (not a ``pl.DataFrame`` or its Arrow table), the ``large_utf8`` distinction is gone at
+  the boundary and the shared sink's ``pa.string()`` imposition normalizes it with no sink
+  change. ``pipeline._coerce_native_rows`` remains the shared backstop.
+
+``import polars`` is **function-local** (mirroring ``reference.py`` / ``pandas_backend.py``'s
+lazy-engine-import ethos), so ``import backends`` and constructing ``PolarsBackend()`` at
+registry load never import polars. The module is named ``polars_backend`` (not ``polars``) to
+avoid the ``import polars`` self-shadow footgun.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mostlyright.data_harness.local_contracts import CleaningStep, TablePlan
+
+
+class PolarsBackend:
+    """polars engine for the ``clean -> join -> select`` triple over an eager frame."""
+
+    # A plain literal (not a lazy ``pipeline`` import), so constructing the backend at
+    # ``registry`` module load never imports ``pipeline`` or polars. The seam resolves the
+    # backend by this exact name; any drift fails closed at ``get_backend`` (BACKEND_UNKNOWN).
+    name: str = "polars"
+
+    def versions(self) -> dict[str, str]:
+        # Provenance only (engine-runtime.v2 ``backend_versions``). The polars import is
+        # function-local (only reached during a build, when polars is already dispatched), so
+        # ``import backends`` / constructing the backend stay polars-free. The version is read
+        # from the module attribute ``pl.__version__`` rather than the stdlib metadata-version
+        # helper: that helper's module name is one of the dynamic-import tokens banned under
+        # ``backends/`` by ``test_backend_registry.py``. For a pinned release the two
+        # spellings are identical.
+        import polars as pl
+
+        return {"polars": str(pl.__version__)}
+
+    def materialize_graph_rows(
+        self,
+        columns: tuple[str, ...],
+        rows: tuple[tuple[Any, ...], ...],
+    ) -> tuple[tuple[Any, ...], ...]:
+        """Exercise a Polars object frame while preserving contract-owned Python scalars."""
+
+        import polars as pl
+
+        if any(len(row) != len(columns) for row in rows):
+            raise ValueError("graph row width differs from its columns")
+        frame = pl.DataFrame(
+            [
+                pl.Series(column, [row[index] for row in rows], dtype=pl.Object)
+                for index, column in enumerate(columns)
+            ]
+        )
+        return tuple(tuple(row) for row in frame.iter_rows())
+
+    def clean(
+        self,
+        rows: list[dict[str, Any]],
+        columns: list[str],
+        lineage: dict[str, dict[str, Any]],
+        step: CleaningStep,
+    ) -> tuple[list[dict[str, Any]], list[str], dict[str, dict[str, Any]]]:
+        # Value-wise reproduction of ``pipeline._apply_cleaning`` (the DataFrame is a shaping
+        # container, not a transform engine): shared ``_require_columns`` refusals, Python
+        # shared ASCII-only trim, ``== ""`` -> None, positional
+        # rename with ``RENAME_COLLISION``, and every cast through the shared ``_cast``.
+        from mostlyright.data_harness import pipeline
+
+        output_rows = [dict(row) for row in rows]
+        output_columns = list(columns)
+        output_lineage = {
+            column: {**entry, "operations": list(entry["operations"])}
+            for column, entry in lineage.items()
+        }
+        if step.operation in {"trim", "empty_to_null"}:
+            target_columns = tuple(step.columns)
+            pipeline._require_columns(output_columns, target_columns, step.operation)
+            for row in output_rows:
+                for column in target_columns:
+                    value = row[column]
+                    if step.operation == "trim":
+                        if value is not None and not isinstance(value, str):
+                            raise pipeline.BuildError(
+                                "CLEAN_TYPE", f"trim requires strings in {column!r}"
+                            )
+                        row[column] = None if value is None else pipeline._trim_ascii(value)
+                    elif value == "":
+                        row[column] = None
+            for column in target_columns:
+                output_lineage[column]["operations"].append(step.operation)
+        elif step.operation == "rename":
+            mapping = dict(step.columns)
+            pipeline._require_columns(output_columns, tuple(mapping), "rename")
+            final_columns = [mapping.get(column, column) for column in output_columns]
+            if len(final_columns) != len(set(final_columns)):
+                raise pipeline.BuildError("RENAME_COLLISION", "rename creates a column collision")
+            output_rows = [
+                {mapping.get(column, column): row[column] for column in output_columns}
+                for row in output_rows
+            ]
+            new_lineage: dict[str, dict[str, Any]] = {}
+            for column in output_columns:
+                target = mapping.get(column, column)
+                entry = output_lineage[column]
+                if target != column:
+                    entry["operations"].append(f"rename:{column}->{target}")
+                new_lineage[target] = entry
+            output_columns = final_columns
+            output_lineage = new_lineage
+        elif step.operation == "cast":
+            mapping = dict(step.columns)
+            pipeline._require_columns(output_columns, tuple(mapping), "cast")
+            for row_index, row in enumerate(output_rows, start=1):
+                for column, target in mapping.items():
+                    row[column] = pipeline._cast(row[column], target, column, row_index)
+            for column, target in mapping.items():
+                output_lineage[column]["operations"].append(f"cast:{target}")
+        else:  # pragma: no cover - contract parser makes this unreachable
+            raise pipeline.ContractError(
+                "plan.cleaning.operation",
+                "CLEAN_OPERATION_UNSUPPORTED",
+                f"unsupported operation: {step.operation}",
+            )
+
+        shaped = _rows_from_frame(
+            _frame_from_rows(
+                output_rows, output_columns, _logical_by_column(output_lineage, output_columns)
+            )
+        )
+        return shaped, output_columns, output_lineage
+
+    def join(
+        self,
+        plan: TablePlan,
+        rows_by_source: dict[str, list[dict[str, Any]]],
+        columns_by_source: dict[str, list[str]],
+        lineage_by_source: dict[str, dict[str, dict[str, Any]]],
+    ) -> tuple[
+        list[dict[str, Any]],
+        list[str],
+        dict[str, dict[str, Any]],
+        dict[str, Any],
+    ]:
+        # Value-wise reproduction of ``pipeline._join``. Left-source order is imposed
+        # positionally (iterate the left rows; look up the right by an equality index) — never
+        # a polars ``join``/``group_by``, so polars' ordering nondeterminism never touches the
+        # digest. Same guards and typed refusals; output columns ``[*left_columns,
+        # *right_nonkeys]``; merged lineage; and a ``report`` byte-identical to the reference
+        # one. The report counts stay native ``int`` because they are pure-Python
+        # ``len(...)``; an engine scalar there would change the evidence bytes.
+        from mostlyright.data_harness import pipeline
+
+        spec = plan.join
+        left_rows = rows_by_source[spec.left]
+        right_rows = rows_by_source[spec.right]
+        left_columns = columns_by_source[spec.left]
+        right_columns = columns_by_source[spec.right]
+        pipeline._require_columns(left_columns, spec.on, "join.left keys")
+        pipeline._require_columns(right_columns, spec.on, "join.right keys")
+        for key in spec.on:
+            left_types = {type(row[key]) for row in left_rows if row[key] is not None}
+            right_types = {type(row[key]) for row in right_rows if row[key] is not None}
+            if any(row[key] is None for row in left_rows + right_rows):
+                raise pipeline.BuildError("JOIN_NULL_KEY", f"join key {key!r} contains null")
+            if len(left_types) != 1 or left_types != right_types:
+                raise pipeline.BuildError(
+                    "JOIN_KEY_TYPE", f"join key {key!r} types do not match exactly"
+                )
+        right_nonkeys = [column for column in right_columns if column not in spec.on]
+        collisions = set(left_columns) & set(right_nonkeys)
+        if collisions:
+            raise pipeline.BuildError(
+                "JOIN_COLUMN_COLLISION", f"join column collision: {sorted(collisions)}"
+            )
+        right_index: dict[tuple[Any, ...], dict[str, Any]] = {}
+        for row in right_rows:
+            key = tuple(row[column] for column in spec.on)
+            if key in right_index:
+                raise pipeline.BuildError("JOIN_CARDINALITY", "right join keys are not unique")
+            right_index[key] = row
+        if spec.cardinality == "one_to_one":
+            left_keys = [tuple(row[column] for column in spec.on) for row in left_rows]
+            if len(left_keys) != len(set(left_keys)):
+                raise pipeline.BuildError("JOIN_CARDINALITY", "left join keys are not unique")
+        output: list[dict[str, Any]] = []
+        unmatched = 0
+        for left_row in left_rows:
+            key = tuple(left_row[column] for column in spec.on)
+            right_row = right_index.get(key)
+            if right_row is None:
+                unmatched += 1
+                merged = {**left_row, **{column: None for column in right_nonkeys}}
+            else:
+                merged = {**left_row, **{column: right_row[column] for column in right_nonkeys}}
+            output.append(merged)
+        multiplier = len(output) / len(left_rows)
+        if unmatched:
+            raise pipeline.BuildError("JOIN_UNMATCHED", f"left join has {unmatched} unmatched rows")
+        if multiplier != 1.0:
+            raise pipeline.BuildError("JOIN_MULTIPLIER", f"join row multiplier is {multiplier}")
+        columns = [*left_columns, *right_nonkeys]
+        lineage = {
+            **lineage_by_source[spec.left],
+            **{column: lineage_by_source[spec.right][column] for column in right_nonkeys},
+        }
+        report = {
+            "schema_version": "join-evidence.v1",
+            "left_source": spec.left,
+            "right_source": spec.right,
+            "keys": list(spec.on),
+            "cardinality": spec.cardinality,
+            "left_rows": len(left_rows),
+            "right_rows": len(right_rows),
+            "output_rows": len(output),
+            "matched_left_rows": len(output) - unmatched,
+            "unmatched_left_rows": unmatched,
+            "row_multiplier": multiplier,
+            "stable_order": "left_source_order",
+        }
+        shaped = _rows_from_frame(
+            _frame_from_rows(output, columns, _logical_by_column(lineage, columns))
+        )
+        return shaped, columns, lineage, report
+
+    def select(
+        self,
+        plan: TablePlan,
+        rows: list[dict[str, Any]],
+        columns: list[str],
+        lineage: dict[str, dict[str, Any]],
+    ) -> tuple[list[dict[str, Any]], dict[str, dict[str, Any]]]:
+        # Value-wise reproduction of ``pipeline._select``: project/order columns to
+        # ``plan.select`` (shared ``_require_columns`` for the missing-column refusal);
+        # ``selected_lineage`` in ``plan.select`` order.
+        from mostlyright.data_harness import pipeline
+
+        pipeline._require_columns(columns, plan.select, "select")
+        selected_rows = [{column: row[column] for column in plan.select} for row in rows]
+        selected_lineage = {column: lineage[column] for column in plan.select}
+        shaped = _rows_from_frame(
+            _frame_from_rows(
+                selected_rows,
+                list(plan.select),
+                _logical_by_column(selected_lineage, plan.select),
+            )
+        )
+        return shaped, selected_lineage
+
+
+def _logical_by_column(lineage: dict[str, dict[str, Any]], columns: Any) -> dict[str, str]:
+    """Map each column to its closed logical type via the shared ``_logical_type_for``.
+
+    The logical type is drawn only from the column's lineage ``operations`` (the last
+    ``cast:<target>``, else ``"string"``) — never from an engine scalar's class name — so
+    the polars dtype the frame is built with matches the sink's imposed schema.
+    """
+
+    from mostlyright.data_harness import pipeline
+
+    return {column: pipeline._logical_type_for(lineage[column]) for column in columns}
+
+
+def _polars_dtype_for(logical: str) -> Any:
+    """Return the explicit polars dtype for one authoritative local logical type.
+
+    ``_POLARS_BY_LOGICAL`` is aligned one-to-one with the sink's closed
+    ``pipeline._ARROW_BY_LOGICAL`` vocabulary, so the frame's per-column dtype is canonical and
+    can never be inferred/lenient. Built with a function-local ``pl`` reference so ``import
+    backends`` never imports polars.
+    """
+
+    import polars as pl
+
+    _POLARS_BY_LOGICAL = {
+        "string": pl.String,
+        "int64": pl.Int64,
+        "float64": pl.Float64,
+        "boolean": pl.Boolean,
+        "date": pl.Date,
+        "timestamp_utc": pl.Datetime(time_unit="us", time_zone="UTC"),
+    }
+    return _POLARS_BY_LOGICAL[logical]
+
+
+def _frame_from_rows(
+    rows: list[dict[str, Any]], columns: Any, logical_by_column: dict[str, str]
+) -> Any:
+    """Build an EAGER ``pl.DataFrame`` with an explicit per-column dtype.
+
+    Each column is constructed as a ``pl.Series(name, values, dtype=<explicit>)`` from the
+    already-typed native values — never inferred, never an engine-native cast token, never a
+    ``pl.DataFrame`` handed to the sink. Explicit closed dtypes carry true polars nulls (never
+    ``NaN``) and keep ``int64`` as ``int64`` under nulls (no float promotion). The zero-column
+    shape is unreachable in the contract
+    (every stage yields >=1 output column) but is handled defensively — an empty frame — so a
+    degenerate op cannot raise here.
+    """
+
+    import polars as pl
+
+    column_order = list(columns)
+    if not column_order:
+        return pl.DataFrame()
+    series = [
+        pl.Series(
+            column,
+            [row[column] for row in rows],
+            dtype=_polars_dtype_for(logical_by_column[column]),
+        )
+        for column in column_order
+    ]
+    return pl.DataFrame(series)
+
+
+def _rows_from_frame(frame: Any) -> list[dict[str, Any]]:
+    """Convert an eager ``pl.DataFrame`` back to an ordered native ``list[dict]``.
+
+    Column (key) order follows the frame's schema order; each cell is read through polars'
+    native ``to_dicts()`` so a polars null becomes Python ``None`` and every scalar is a native
+    Python builtin — ``pl.String`` (Arrow ``large_utf8``) -> ``str`` with no width tag,
+    ``pl.Int64`` -> ``int``, ``pl.Float64`` -> ``float``, ``pl.Date`` -> ``datetime.date`` — no
+    engine scalar, no polars categorical type. Returning native rows (not a ``pl.DataFrame`` /
+    its Arrow table) is what strips the ``large_utf8`` width tag, so the shared sink's imposed
+    ``pa.string()`` normalizes it with no sink change. ``pipeline._coerce_native_rows`` remains
+    the shared backstop downstream.
+    """
+
+    return frame.to_dicts()

mostlyright/data_harness/backends/protocol.py

@@ -0,0 +1,124 @@
+"""The named backend protocol at the ``clean -> join -> select`` row-transform seam.
+
+The protocol boundary is the inner ``clean -> join -> select`` triple over ``list[dict]``
+of native Python scalars — not the outer ``pipeline._replay_candidate_derivations``
+signature. Making the whole replay pluggable would force every backend to re-own the
+Parquet sink, the casts, validation and evidence, which is the entire byte-parity risk
+surface. Keeping the seam narrow means the shared layer still produces every candidate
+byte no matter which engine is selected.
+
+The three method signatures are the signatures of ``pipeline._apply_cleaning`` /
+``pipeline._join`` / ``pipeline._select`` (only ``self`` is added), so a backend is a
+drop-in for those functions and ``reference.py`` can delegate to them unchanged.
+
+A backend must be byte-identical to the reference implementation, not merely equivalent:
+same row order, same column order, same Python scalar types, same typed refusals in the
+same order. Any divergence changes the sealed candidate digest.
+
+This module imports only ``local_contracts`` for typing and never ``pipeline``, which
+keeps ``import backends`` free of a module-load dependency on ``pipeline``. ``pipeline``
+imports the registry, so a top-level ``pipeline`` import here would close a cycle.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from mostlyright.data_harness.local_contracts import CleaningStep, TablePlan
+
+
+@runtime_checkable
+class Backend(Protocol):
+    """A named engine for the ``clean -> join -> select`` row-transform triple."""
+
+    name: str
+
+    def versions(self) -> dict[str, str]:
+        """Engine-library versions for provenance (``{}`` for a pure-Python backend)."""
+        ...
+
+    def materialize_graph_rows(
+        self,
+        columns: tuple[str, ...],
+        rows: tuple[tuple[Any, ...], ...],
+    ) -> tuple[tuple[Any, ...], ...]:
+        """Round-trip one graph node through this engine's deterministic container."""
+        ...
+
+    def clean(
+        self,
+        rows: list[dict[str, Any]],
+        columns: list[str],
+        lineage: dict[str, dict[str, Any]],
+        step: CleaningStep,
+    ) -> tuple[list[dict[str, Any]], list[str], dict[str, dict[str, Any]]]:
+        """Apply one cleaning step and return ``(rows, columns, lineage)``.
+
+        ``step.operation`` is one of ``trim`` / ``empty_to_null`` / ``rename`` / ``cast``.
+        The inputs must not be mutated; return fresh structures. Row order is the input
+        order. ``columns`` is the output column order (only ``rename`` changes it, and it
+        renames in place, positionally). ``lineage`` keeps one entry per output column,
+        with the applied operation appended to that entry's ``operations`` list
+        (``rename:<from>-><to>`` and ``cast:<target>`` carry their argument).
+
+        Required typed refusals, all ``pipeline.BuildError``: ``COLUMN_MISSING`` when the
+        step names a column that is absent, ``CLEAN_TYPE`` when ``trim`` meets a non-string
+        non-null value, ``RENAME_COLLISION`` when a rename would produce duplicate column
+        names, and ``CAST_INVALID`` / ``CAST_TYPE`` from the cast. Casts must route through
+        ``pipeline._cast`` rather than an engine-native parser, so cast results and cast
+        refusals stay identical across engines. Reference implementation:
+        ``pipeline._apply_cleaning``.
+        """
+        ...
+
+    def join(
+        self,
+        plan: TablePlan,
+        rows_by_source: dict[str, list[dict[str, Any]]],
+        columns_by_source: dict[str, list[str]],
+        lineage_by_source: dict[str, dict[str, dict[str, Any]]],
+    ) -> tuple[
+        list[dict[str, Any]],
+        list[str],
+        dict[str, dict[str, Any]],
+        dict[str, Any],
+    ]:
+        """Run ``plan.join`` and return ``(rows, columns, lineage, report)``.
+
+        One left equality join on ``plan.join.on``. Output row order is left-source order,
+        positionally: iterate the left rows and look up the right row by key. Do not rely
+        on an engine join operator's ordering. Output columns are
+        ``[*left_columns, *right_non_key_columns]``; lineage merges the two sources under
+        those columns.
+
+        Required typed refusals, all ``pipeline.BuildError``: ``COLUMN_MISSING`` for an
+        absent key, ``JOIN_NULL_KEY`` for a null key value on either side,
+        ``JOIN_KEY_TYPE`` when the left key does not have exactly one observed non-null
+        value type, or when the left and right key value types are not exactly equal
+        (so two empty sources refuse, even though their type sets are both empty),
+        ``JOIN_COLUMN_COLLISION`` when a right non-key column name already exists on the
+        left, ``JOIN_CARDINALITY`` for non-unique right keys (or non-unique left keys under
+        ``one_to_one``), ``JOIN_UNMATCHED`` for any unmatched left row, and
+        ``JOIN_MULTIPLIER`` when the output/left row ratio is not exactly 1.
+
+        ``report`` is the ``join-evidence.v1`` payload that is serialized into candidate
+        evidence, so its counts must be plain Python ``int`` — never an engine scalar type.
+        Reference implementation: ``pipeline._join``.
+        """
+        ...
+
+    def select(
+        self,
+        plan: TablePlan,
+        rows: list[dict[str, Any]],
+        columns: list[str],
+        lineage: dict[str, dict[str, Any]],
+    ) -> tuple[list[dict[str, Any]], dict[str, dict[str, Any]]]:
+        """Project to ``plan.select`` and return ``(rows, lineage)``.
+
+        Every returned row carries exactly the columns of ``plan.select``, in that order;
+        ``lineage`` is restricted and reordered the same way. Row order is the input order.
+        Raise ``pipeline.BuildError("COLUMN_MISSING", ...)`` when ``plan.select`` names a
+        column that is not present. Reference implementation: ``pipeline._select``.
+        """
+        ...

mostlyright/data_harness/backends/reference.py

@@ -0,0 +1,83 @@
+"""The reference backend: the pure-Python compute behind the protocol.
+
+``ReferenceBackend`` is a thin dispatch adapter that delegates ``clean`` / ``join`` /
+``select`` to ``pipeline._apply_cleaning`` / ``pipeline._join`` / ``pipeline._select``.
+It must never re-implement that compute: delegation is what makes its bytes provably the
+shared layer's own, which is why the sealed goldens reproduce byte-for-byte when the build
+seam dispatches through it.
+
+The compute functions live in ``pipeline``, and ``pipeline`` imports the registry, so
+importing ``pipeline`` at module top would form a
+``pipeline -> registry -> reference -> pipeline`` cycle. Each method therefore imports
+``pipeline`` function-locally, so ``import backends`` never triggers ``import pipeline``
+at module-load time.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mostlyright.data_harness.local_contracts import CleaningStep, TablePlan
+
+
+class ReferenceBackend:
+    """Pure-Python reference engine delegating to the shared ``pipeline`` compute."""
+
+    # Must stay equal to ``pipeline.REFERENCE_BACKEND_NAME``, which is the single source of
+    # truth. Deliberately a plain literal here — not a lazy ``pipeline`` import — so
+    # constructing the backend (done at ``registry`` module load) never imports
+    # ``pipeline`` and cannot form the import cycle. Drift fails closed at build time: the
+    # seam resolves ``get_backend(pipeline.REFERENCE_BACKEND_NAME)``, which raises
+    # ``BACKEND_UNKNOWN`` if this name no longer matches.
+    name: str = "reference"
+
+    def versions(self) -> dict[str, str]:
+        # Pure Python — no external engine library to version.
+        return {}
+
+    def materialize_graph_rows(
+        self,
+        columns: tuple[str, ...],
+        rows: tuple[tuple[Any, ...], ...],
+    ) -> tuple[tuple[Any, ...], ...]:
+        if any(len(row) != len(columns) for row in rows):
+            raise ValueError("graph row width differs from its columns")
+        return tuple(tuple(row) for row in rows)
+
+    def clean(
+        self,
+        rows: list[dict[str, Any]],
+        columns: list[str],
+        lineage: dict[str, dict[str, Any]],
+        step: CleaningStep,
+    ) -> tuple[list[dict[str, Any]], list[str], dict[str, dict[str, Any]]]:
+        from mostlyright.data_harness import pipeline
+
+        return pipeline._apply_cleaning(rows, columns, lineage, step)
+
+    def join(
+        self,
+        plan: TablePlan,
+        rows_by_source: dict[str, list[dict[str, Any]]],
+        columns_by_source: dict[str, list[str]],
+        lineage_by_source: dict[str, dict[str, dict[str, Any]]],
+    ) -> tuple[
+        list[dict[str, Any]],
+        list[str],
+        dict[str, dict[str, Any]],
+        dict[str, Any],
+    ]:
+        from mostlyright.data_harness import pipeline
+
+        return pipeline._join(plan, rows_by_source, columns_by_source, lineage_by_source)
+
+    def select(
+        self,
+        plan: TablePlan,
+        rows: list[dict[str, Any]],
+        columns: list[str],
+        lineage: dict[str, dict[str, Any]],
+    ) -> tuple[list[dict[str, Any]], dict[str, dict[str, Any]]]:
+        from mostlyright.data_harness import pipeline
+
+        return pipeline._select(plan, rows, columns, lineage)

mostlyright/data_harness/backends/registry.py

@@ -0,0 +1,55 @@
+"""Explicit named backend registration and fail-closed dispatch.
+
+The registry is a literal dict populated at import time by explicit named registration.
+No dynamic module import, no packaging entry-point discovery, no resource-based plugin
+lookup, and no runtime import hook of any kind is permitted anywhere under ``backends/``:
+an engine that can be swapped in at runtime is an engine that can change sealed candidate
+bytes without a code review. ``tests/test_backend_registry.py`` statically asserts none of
+those dynamic-import tokens appear in this package.
+
+``get_backend`` fails closed on an unknown name with a typed
+``BuildError("BACKEND_UNKNOWN", ...)`` — never a silent default engine, because silently
+falling back would produce bytes under an engine name the caller did not select.
+"""
+
+from __future__ import annotations
+
+from mostlyright.data_harness.backends.pandas_backend import PandasBackend
+from mostlyright.data_harness.backends.polars_backend import PolarsBackend
+from mostlyright.data_harness.backends.protocol import Backend
+from mostlyright.data_harness.backends.reference import ReferenceBackend
+
+# Explicit, literal registration — the only way a backend enters the table. Constructing
+# ``PandasBackend()``/``PolarsBackend()`` here does NOT import pandas/polars: each engine
+# import is function-local, so ``import backends`` stays import-light (the lazy-import
+# contract, mirrored from the reference). ``get_backend`` still fails closed on an unknown
+# name (BACKEND_UNKNOWN).
+_REGISTRY: dict[str, Backend] = {
+    ReferenceBackend.name: ReferenceBackend(),
+    PandasBackend.name: PandasBackend(),
+    PolarsBackend.name: PolarsBackend(),
+}
+
+
+def get_backend(name: str) -> Backend:
+    """Return the registered backend for ``name`` or fail closed.
+
+    An unknown/unregistered name is a typed refusal
+    (``BuildError("BACKEND_UNKNOWN", ...)``), never a silent default backend.
+    """
+
+    backend = _REGISTRY.get(name)
+    if backend is None:
+        # Lazy import keeps ``import backends`` free of a module-load dependency on
+        # ``pipeline``; ``pipeline`` imports this module, so a top-level import would
+        # cycle. Only this failure path needs ``BuildError``.
+        from mostlyright.data_harness.pipeline import BuildError
+
+        raise BuildError("BACKEND_UNKNOWN", f"no registered backend {name!r}")
+    return backend
+
+
+def registered_backends() -> frozenset[str]:
+    """Return the frozenset of registered backend names."""
+
+    return frozenset(_REGISTRY)