tenspec 0.1.0__tar.gz

tenspec-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+build/
+dist/
+
+# Env + tool caches
+.venv/
+.env
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Editor state
+.vscode/
+.idea/
+.DS_Store
+
+# Retained release evidence (visible, never committed)
+artifacts/

tenspec-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Egor Dmitriev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tenspec-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: tenspec
+Version: 0.1.0
+Summary: Tensor specifications that a function, a model, or a direct call checks at its boundary.
+Project-URL: Source, https://github.com/egordm/tenspec
+Project-URL: Documentation, https://egordm.github.io/tenspec/
+Project-URL: Issues, https://github.com/egordm/tenspec/issues
+Author: Egor Dmitriev
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: pydantic<3,>=2.13.4
+Requires-Dist: typing-extensions>=4.13
+Provides-Extra: dev
+Requires-Dist: numpy>=2.1; (python_version < '3.14') and extra == 'dev'
+Requires-Dist: numpy>=2.3.2; (python_version >= '3.14') and extra == 'dev'
+Requires-Dist: poethepoet>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: torch>=2.6; (python_version < '3.14') and extra == 'dev'
+Requires-Dist: torch>=2.9; (python_version >= '3.14') and extra == 'dev'
+Requires-Dist: ty>=0.0.78; extra == 'dev'
+Provides-Extra: numpy
+Requires-Dist: numpy>=2.1; (python_version < '3.14') and extra == 'numpy'
+Requires-Dist: numpy>=2.3.2; (python_version >= '3.14') and extra == 'numpy'
+Provides-Extra: torch
+Requires-Dist: torch>=2.6; (python_version < '3.14') and extra == 'torch'
+Requires-Dist: torch>=2.9; (python_version >= '3.14') and extra == 'torch'
+Description-Content-Type: text/markdown
+
+# tenspec
+
+Declare what an array must be, beside the value it describes, and check it at one boundary.
+
+Tenspec moves the shape and dtype checks from the top of a function into its signature, where a
+reader and a type checker both see them. It accepts or refuses the array the caller passed. It
+converts nothing, moves nothing, and copies nothing, unless the declaration names a transform
+that copies.
+
+This is an early release, at version 0.1.0. The interface can change before version 1.0.
+
+## Install
+
+Install it with pip, or with uv. Either one is enough, so run the line for the tool you use:
+
+```bash
+pip install "tenspec[numpy]"   # or: uv add "tenspec[numpy]"
+```
+
+Name the array library you need as an extra: `numpy` or `torch`. `import tenspec` loads neither
+one. It needs Python 3.13 or newer.
+
+## What it gives you
+
+- **Ordinary types.** A declaration is an ordinary annotation carrying your backend's array
+  type, so a type checker reads it and untouched code still runs. The checkers, the settings
+  they need and their measured limits are on
+  [Type checkers and Ruff](https://egordm.github.io/tenspec/type-checkers.html).
+- **Pydantic boundaries, natively.** `TensorContracts` relates the fields of your own model
+  inside one model validation.
+- **Runtime checks are opt in.** An annotation alone performs no runtime work.
+- **Transforms are explicit.** A value changes only when a declaration names a transform, and
+  the runtime verifies the result kept its class, shape, native dtype and device.
+
+## The three entry points
+
+| Entry point | Use it for |
+|---|---|
+| `@checked` | a function or a method, with its arguments and its return |
+| `TensorContracts` | a Pydantic model, whose related fields share one boundary |
+| `validate(value, annotation)` | one value, or one tuple of related values |
+
+```python
+from typing import Literal as Shape
+
+import numpy as np
+
+from tenspec import checked
+from tenspec.numpy import Float
+
+
+@checked
+def weigh_columns(
+    values: Float[Shape["rows features"]], weights: Float[Shape["features"]]
+) -> Float[Shape["rows features"]]:
+    return values * weights
+
+
+print(weigh_columns(np.ones((3, 4)), np.array([1.0, 2.0, 3.0, 4.0])).shape)
+```
+
+`weights` must cover as many features as `values` has columns. A disagreement is a run-time
+refusal naming the axis, both extents, and the bindings the boundary held.
+
+No type checker compares two shapes. A shape that disagrees is a run-time refusal, never a
+static error.
+
+## Documentation
+
+[The documentation site](https://egordm.github.io/tenspec/) holds the guide, the API reference
+and two executed tutorials. The
+[repository](https://github.com/egordm/tenspec) holds the source.
+
+## Attribution
+
+The shape notation follows [jaxtyping](https://github.com/patrick-kidger/jaxtyping), which is
+MIT licensed. jaxtyping is not a dependency of this package.
+
+## License
+
+MIT. See `LICENSE`.

tenspec-0.1.0/README.md

@@ -0,0 +1,81 @@
+# tenspec
+
+Declare what an array must be, beside the value it describes, and check it at one boundary.
+
+Tenspec moves the shape and dtype checks from the top of a function into its signature, where a
+reader and a type checker both see them. It accepts or refuses the array the caller passed. It
+converts nothing, moves nothing, and copies nothing, unless the declaration names a transform
+that copies.
+
+This is an early release, at version 0.1.0. The interface can change before version 1.0.
+
+## Install
+
+Install it with pip, or with uv. Either one is enough, so run the line for the tool you use:
+
+```bash
+pip install "tenspec[numpy]"   # or: uv add "tenspec[numpy]"
+```
+
+Name the array library you need as an extra: `numpy` or `torch`. `import tenspec` loads neither
+one. It needs Python 3.13 or newer.
+
+## What it gives you
+
+- **Ordinary types.** A declaration is an ordinary annotation carrying your backend's array
+  type, so a type checker reads it and untouched code still runs. The checkers, the settings
+  they need and their measured limits are on
+  [Type checkers and Ruff](https://egordm.github.io/tenspec/type-checkers.html).
+- **Pydantic boundaries, natively.** `TensorContracts` relates the fields of your own model
+  inside one model validation.
+- **Runtime checks are opt in.** An annotation alone performs no runtime work.
+- **Transforms are explicit.** A value changes only when a declaration names a transform, and
+  the runtime verifies the result kept its class, shape, native dtype and device.
+
+## The three entry points
+
+| Entry point | Use it for |
+|---|---|
+| `@checked` | a function or a method, with its arguments and its return |
+| `TensorContracts` | a Pydantic model, whose related fields share one boundary |
+| `validate(value, annotation)` | one value, or one tuple of related values |
+
+```python
+from typing import Literal as Shape
+
+import numpy as np
+
+from tenspec import checked
+from tenspec.numpy import Float
+
+
+@checked
+def weigh_columns(
+    values: Float[Shape["rows features"]], weights: Float[Shape["features"]]
+) -> Float[Shape["rows features"]]:
+    return values * weights
+
+
+print(weigh_columns(np.ones((3, 4)), np.array([1.0, 2.0, 3.0, 4.0])).shape)
+```
+
+`weights` must cover as many features as `values` has columns. A disagreement is a run-time
+refusal naming the axis, both extents, and the bindings the boundary held.
+
+No type checker compares two shapes. A shape that disagrees is a run-time refusal, never a
+static error.
+
+## Documentation
+
+[The documentation site](https://egordm.github.io/tenspec/) holds the guide, the API reference
+and two executed tutorials. The
+[repository](https://github.com/egordm/tenspec) holds the source.
+
+## Attribution
+
+The shape notation follows [jaxtyping](https://github.com/patrick-kidger/jaxtyping), which is
+MIT licensed. jaxtyping is not a dependency of this package.
+
+## License
+
+MIT. See `LICENSE`.

tenspec-0.1.0/examples/forecast_scale.py

@@ -0,0 +1,92 @@
+"""Forecasting: a NaN-aware scaler whose method shape the declarations must fit.
+
+A demonstration against the accepted method shape of Cairn's ContextScale, in
+`packages/cairn-nn/src/cairn/nn/normalization.py` at Cairn b869c260. No consumer file is
+read at run time and no consumer file changes. The body holds only the statistics needed to
+show that the declarations fit the real boundary.
+
+Run it with `uv run python packages/tenspec/examples/forecast_scale.py`.
+"""
+
+from typing import Any, Self
+from typing import Literal as Shape
+
+import numpy as np
+from numpy.typing import NDArray
+
+from pydantic import ValidationError
+from tenspec import checked
+from tenspec.numpy import Bool, Float, Float64
+
+
+class ContextScale:
+    """A mean and a floored scale along the last axis, fitted once per context."""
+
+    def __init__(self, location: NDArray[np.float64], scale: NDArray[np.float64]) -> None:
+        self.location = location
+        self.scale = scale
+
+    @classmethod
+    @checked
+    def fit(
+        cls,
+        values: Float[Shape["*batch time"]],
+        mask: Bool[Shape["*batch time"]] | None = None,
+        *,
+        flatness_floor: float = 1e-3,
+    ) -> Self:
+        """Fit over the last axis. A NaN and a False mask step are both missing.
+
+        Returns:
+            A scaler of the class that received the call.
+        """
+        observed = values if mask is None else np.where(mask, values, np.nan)
+        location = np.nanmean(observed, axis=-1)
+        spread = np.nanstd(observed, axis=-1)
+        floor = flatness_floor * (np.abs(location) + 1.0)
+        return cls(np.asarray(location, np.float64), np.asarray(np.maximum(spread, floor)))
+
+    @checked
+    def normalize(self, values: Float[Shape["*batch time"]]) -> Float64[Shape["*batch time"]]:
+        """Centre and scale, and let a missing observation pass through.
+
+        Returns:
+            The normalized block, in float64.
+        """
+        return (values - self.location[..., None]) / self.scale[..., None]
+
+
+class RobustScale(ContextScale):
+    """A subclass. Its fit must return a RobustScale, never a ContextScale."""
+
+
+def main() -> None:
+    """Fit and normalize a target history and a covariate history of different ranks."""
+    target = np.array([1.0, np.nan, 3.0, 5.0], dtype=np.float32)
+    covariates = np.array([[2.0, 4.0, 6.0, 8.0], [1.0, 1.0, np.nan, 1.0]], dtype=np.float32)
+    observed = np.array([[True, True, True, False], [True, True, True, True]])
+
+    target_scale = ContextScale.fit(target)
+    covariate_scale = ContextScale.fit(covariates, observed, flatness_floor=0.05)
+    print(f"Target location {target_scale.location.round(3).tolist()}")
+    print(f"Covariate location {covariate_scale.location.round(3).tolist()}")
+
+    normalized: Any = covariate_scale.normalize(covariates)
+    print(f"Normalized {normalized.shape}, dtype {normalized.dtype}")
+    print(f"A missing observation passes through: {bool(np.isnan(normalized[1, 2]))}")
+
+    print(f"A subclass fit returns its own class: {type(RobustScale.fit(target)).__name__}")
+
+    try:
+        ContextScale.fit(covariates, np.array([True, False, True, True]))
+    except ValidationError as refusal:
+        print(f"The mask must cover the same axes: {refusal.errors()[0]['msg']}")
+
+    try:
+        ContextScale.fit(np.array([1, 2, 3]))
+    except ValidationError as refusal:
+        print(f"An integer history is refused: {refusal.errors()[0]['msg']}")
+
+
+if __name__ == "__main__":
+    main()

tenspec-0.1.0/examples/locos_capture.py

@@ -0,0 +1,161 @@
+"""LOCOS: a capture boundary, and related measurement fields.
+
+A demonstration against the real operand relationships of
+`packages/skllm/src/skllm/attribution/locos/torch.py` and `.../locos/models.py` at Nightjar
+476e2743. No consumer file is read at run time and no consumer file changes. The numerical
+bodies are the smallest work that shows the declarations fit the real boundary.
+
+Run it with `uv run python packages/tenspec/examples/locos_capture.py`.
+"""
+
+from typing import Annotated, Any, TypeVar
+from typing import Literal as Shape
+
+import numpy as np
+import torch
+from numpy.typing import NDArray
+from torch import Tensor
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict, Field, ValidationError
+from tenspec import Finite, Floating, Materialized, NonEmpty, TensorContracts, checked, validate
+from tenspec.numpy import Float64, ReadOnly
+from tenspec.torch import Float
+from tenspec.types.properties import Device
+
+Scalar = TypeVar("Scalar", bound=Floating)
+Placement = TypeVar("Placement", bound=Device)
+
+
+@checked
+def head_directions[Scalar: Floating, Placement: Device](
+    output_projection: Float[
+        Shape["heads head_dim hidden"], Scalar, Placement, NonEmpty, Materialized
+    ],
+    token_direction: Float[Shape["hidden"], Scalar, Placement, NonEmpty, Materialized],
+) -> Tensor:
+    """One direction per head, in the operands' own format and placement.
+
+    The contraction needs a populated axis and actual values on both operands, so both
+    say so. An empty head dimension would otherwise reach the einsum and return a
+    direction of no length.
+    """
+    return torch.einsum("hdm,m->hd", output_projection, token_direction)
+
+
+def measure_step(
+    attention: Tensor, values: Tensor, directions: Tensor, source_span: tuple[int, int]
+) -> tuple[Tensor, Tensor]:
+    """The contribution of a source span, and the contribution outside it, per head.
+
+    The capture boundary checks the related operands together, then the numerical body runs
+    with no further check. Every operand must be populated and hold actual values, because
+    the modulo and the contraction below read both. Grouped-head divisibility and the span
+    bounds stay ordinary Python, because neither is a relation between axes.
+
+    Returns:
+        The source contribution and the background contribution, one value per head.
+
+    Raises:
+        ValidationError: when an operand is empty, or disagrees with a related operand.
+        ValueError: when the head groups do not divide, or the span leaves no background.
+    """
+    attention, values, directions = validate(
+        (attention, values, directions),
+        tuple[
+            Float[Shape["heads keys"], Scalar, Placement, NonEmpty, Materialized],
+            Float[Shape["kv_heads keys head_dim"], Scalar, Placement, NonEmpty, Materialized],
+            Float[Shape["heads head_dim"], Scalar, Placement, NonEmpty, Materialized],
+        ],
+    )
+    heads, keys = attention.shape
+    kv_heads = values.shape[0]
+    if heads % kv_heads:
+        raise ValueError(f"{heads} query heads do not divide over {kv_heads} key-value heads")
+    start, stop = source_span
+    if not 0 <= start < stop <= keys or stop - start == keys:
+        raise ValueError(f"span {source_span} leaves no background inside {keys} keys")
+
+    grouped = directions.reshape(kv_heads, heads // kv_heads, values.shape[2])
+    per_key = torch.einsum("kjd,kgd->kgj", values, grouped).reshape(heads, keys)
+    weighted = attention * per_key
+    return weighted[:, start:stop].sum(dim=1), weighted.sum(dim=1) - weighted[:, start:stop].sum(
+        dim=1
+    )
+
+
+def sealed(values: NDArray[np.float64]) -> NDArray[np.float64]:
+    """A read-only copy, the way the consumer's own base prepares a block.
+
+    The result owns its storage. It is a copy, not a view of what the caller passed.
+
+    Returns:
+        The read-only copy.
+    """
+    copy = np.array(values, dtype=np.float64, copy=True)
+    copy.setflags(write=False)
+    return copy
+
+
+Block = Annotated[
+    Float64[Shape["selected_steps layers heads"], Finite, ReadOnly], BeforeValidator(sealed)
+]
+
+
+class FrozenArrays(BaseModel):
+    """The consumer's own base. Tenspec adds none of its own and changes no setting."""
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
+
+class LocosAttribution(TensorContracts, FrozenArrays):
+    """Two representative measurement fields, on the same axes, stated once per field."""
+
+    source_attention: Block = Field(description="Source attention per step, layer, and head.")
+    background_attention: Block = Field(description="Background attention on the same axes.")
+
+
+def main() -> None:
+    """Run the capture boundary and the measurement model."""
+    heads, kv_heads, keys, head_dim, hidden = 4, 2, 6, 3, 5
+    projection = torch.ones(heads, head_dim, hidden)
+    token = torch.ones(hidden)
+    directions = head_directions(projection, token)
+    print(f"Directions: {tuple(directions.shape)}, dtype {directions.dtype}")
+
+    attention = torch.full((heads, keys), 1.0 / keys)
+    values = torch.ones(kv_heads, keys, head_dim)
+    source, background = measure_step(attention, values, directions, (1, 3))
+    print(f"Source contribution {source.tolist()}")
+    print(f"Background contribution {background.tolist()}")
+
+    try:
+        measure_step(attention, torch.ones(3, keys, head_dim), directions, (1, 3))
+    except ValueError as refusal:
+        print(f"Grouped heads stay ordinary Python: {refusal}")
+
+    try:
+        measure_step(attention, torch.ones(kv_heads, keys + 1, head_dim), directions, (1, 3))
+    except ValidationError as refusal:
+        print(f"The shared key axis is a declaration: {refusal.errors()[0]['msg']}")
+
+    try:
+        measure_step(attention, torch.ones(0, keys, head_dim), directions, (1, 3))
+    except ValidationError as refusal:
+        print(f"An empty operand refuses before the modulo: {refusal.errors()[0]['msg']}")
+
+    measurements = LocosAttribution(
+        source_attention=np.ones((2, 3, heads)), background_attention=np.zeros((2, 3, heads))
+    )
+    stored: Any = measurements.source_attention
+    print(f"Stored block {stored.shape}, writeable {stored.flags.writeable}")
+
+    try:
+        LocosAttribution(
+            source_attention=np.ones((2, 3, heads)), background_attention=np.zeros((5, 3, heads))
+        )
+    except ValidationError as refusal:
+        print(f"Related fields share their axes: {refusal.errors()[0]['msg']}")
+
+
+if __name__ == "__main__":
+    main()

tenspec-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "tenspec"
+version = "0.1.0"
+description = "Tensor specifications that a function, a model, or a direct call checks at its boundary."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Egor Dmitriev" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.13.4,<3",
+    "typing-extensions>=4.13",
+]
+
+[project.urls]
+Source = "https://github.com/egordm/tenspec"
+Documentation = "https://egordm.github.io/tenspec/"
+Issues = "https://github.com/egordm/tenspec/issues"
+
+[project.optional-dependencies]
+# One extra per array backend. The common tenspec import loads neither library.
+#
+# One floor per Python release. Each one is the oldest release tested on the interpreter it
+# applies to: numpy 2.1 and torch 2.6 on Python 3.13, and numpy 2.3.2 and torch 2.9 on 3.14.
+numpy = [
+    "numpy>=2.1; python_version < '3.14'",
+    "numpy>=2.3.2; python_version >= '3.14'",
+]
+torch = [
+    "torch>=2.6; python_version < '3.14'",
+    "torch>=2.9; python_version >= '3.14'",
+]
+dev = [
+    "tenspec[numpy,torch]",
+    "pytest>=8.0",
+    "ruff>=0.8",
+    "ty>=0.0.78",
+    "poethepoet>=0.30",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tenspec"]
+
+[tool.hatch.build.targets.sdist]
+# README.md joins the list because `readme` names it: a source archive must be able to rebuild
+# its own metadata.
+include = ["src", "tests", "examples", "pyproject.toml", "README.md"]
+
+# ruff + ty + pytest + poe are configured ONCE at the workspace root (../../pyproject.toml,
+# ruff.toml, poe_tasks.toml): this member carries none of its own.

tenspec-0.1.0/src/tenspec/__init__.py

@@ -0,0 +1,39 @@
+"""Tenspec: declare what an array must be, and check it at one boundary.
+
+Write the declaration once, beside the value it describes. A checked function, a model
+mixin, or a standalone call then holds it. Import a backend module for the array library
+you use: `tenspec.numpy` or `tenspec.torch`. This module loads neither one.
+
+This is the common surface. Everything below it keeps its defining module, including
+`tenspec.errors.TensorMismatch`, `tenspec.errors.BindingError`,
+`tenspec.runtime.validation.validate_array`, `tenspec.runtime.bindings.Bindings`,
+`tenspec.runtime.arrays.ArrayBackend`, and `tenspec.pydantic.annotations.prepare_annotation`.
+"""
+
+from typing import Literal as Shape
+
+from tenspec.errors import AnnotationError, ConstraintEvaluationError
+from tenspec.pydantic.calls import checked
+from tenspec.pydantic.models import TensorContracts
+from tenspec.pydantic.standalone import validate
+from tenspec.runtime.bindings import axis_size
+from tenspec.types.dtypes import DType, Floating
+from tenspec.types.properties import Contiguous, Finite, Materialized, NonEmpty
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AnnotationError",
+    "ConstraintEvaluationError",
+    "Contiguous",
+    "DType",
+    "Finite",
+    "Floating",
+    "Materialized",
+    "NonEmpty",
+    "Shape",
+    "TensorContracts",
+    "axis_size",
+    "checked",
+    "validate",
+]

tenspec-0.1.0/src/tenspec/errors.py

@@ -0,0 +1,89 @@
+"""The errors Tenspec raises, and what each one reports."""
+
+from collections.abc import Mapping
+from enum import StrEnum
+
+
+class AnnotationError(TypeError):
+    """A declaration is invalid, unsupported, or never reached Tenspec's preparation."""
+
+
+class ConstraintEvaluationError(RuntimeError):
+    """A backend cannot inspect a declared property of this value.
+
+    This never reports a measured mismatch. It reports that the check could not run.
+    """
+
+
+class BindingReason(StrEnum):
+    """Why a dimension lookup found no extent."""
+
+    NO_SCOPE = "no_scope"
+    UNBOUND = "unbound"
+    NOT_SCALAR = "not_scalar"
+
+
+class BindingError(ValueError):
+    """A required dimension was unavailable, rather than different.
+
+    The reason says which lookup failed. The name is the dimension the caller asked for.
+    """
+
+    def __init__(self, reason: BindingReason, name: str | None = None) -> None:
+        self.reason = reason
+        self.name = name
+        messages = {
+            BindingReason.NO_SCOPE: "no Tenspec validation scope is open",
+            BindingReason.UNBOUND: f"dimension {name!r} has no binding in this scope",
+            BindingReason.NOT_SCALAR: f"dimension {name!r} holds a group of axes, not one extent",
+        }
+        super().__init__(messages[reason])
+
+
+class TensorMismatch(ValueError):  # noqa: N818  the accepted contract fixes this name.
+    """An array disagrees with its declared requirement.
+
+    The requirement, the observed fact, and the relevant bindings stay readable on the
+    error. The error holds no array.
+    """
+
+    def __init__(
+        self,
+        *,
+        requirement: str,
+        observed: str,
+        bindings: Mapping[str, int | tuple[int, ...]] | None = None,
+    ) -> None:
+        self.requirement = requirement
+        self.observed = observed
+        self.bindings: Mapping[str, int | tuple[int, ...]] = dict(bindings or {})
+        detail = f", with {self.bindings}" if self.bindings else ""
+        super().__init__(f"expected {requirement}, but the array has {observed}{detail}")
+
+
+def describe_empty(shape: tuple[int, ...]) -> str:
+    """What a refusal reports about an array that holds no elements.
+
+    It reads the shape alone. Axis indices start at 0.
+
+    describe_empty((2, 0, 0)) returns "shape (2, 0, 0), with no elements at axis 1, axis 2".
+
+    Returns:
+        The observed text for a TensorMismatch.
+    """
+    empty = ", ".join(f"axis {index}" for index, extent in enumerate(shape) if extent == 0)
+    return f"shape {shape}, with no elements at {empty}"
+
+
+class TransformContractError(RuntimeError):
+    """A transform changed a structural fact that it had to preserve.
+
+    This reports a defect in the transform, not invalid caller input, so it is a
+    RuntimeError and never a ValueError. It names the transform and the one fact that
+    changed. Every field is text, so the error holds no array.
+    """
+
+    def __init__(self, *, transform: str, fact: str, before: str, after: str) -> None:
+        self.transform = transform
+        self.fact = fact
+        super().__init__(f"{transform} changed the {fact} of its input, from {before} to {after}")