django-data-shape 0.16.0__tar.gz → 0.17.0__tar.gz

{django_data_shape-0.16.0 → django_data_shape-0.17.0}/CHANGELOG.md

@@ -7,6 +7,71 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0] — 2026-09-05
+
+### Added
+
+- **`Product`, `Offset` and `Copied`: the commonest arithmetic, said as data.**
+  They compute nothing `Derived` could not. They exist because of what `Derived`
+  costs: it takes a callable, a callable cannot be honestly digested, and a
+  shape holding one is refused by `template_database`. So a column as ordinary
+  as `total = quantity * unit_price` took a whole declaration out of the reuse
+  that turns a forty-second build into a hundred-millisecond clone -- and
+  `build()` kept working, so nothing said what it had cost.
+
+  The refusal stays; it is right. These three are pure data, implement
+  `Canonical`, and hash. `Derived` remains the answer for computation that
+  really is code.
+
+  `Offset` is also the same-row half of `After`, which is parent-scoped only.
+  Its gap is fixed rather than spread across a window, because a due date thirty
+  days after an issue date is a term and not a distribution.
+
+### Changed
+
+- **A scaled world can now be built over a session world.** The two pytest
+  surfaces this package ships wanted the same tables in any application with one
+  model graph, and were mutually exclusive: the session world holds its rows for
+  the whole run, so the scaled build met a table that was not empty and refused.
+  The documented answer -- give the two different models -- is not available to a
+  project whose plan assertions and growth assertions are about the same flow,
+  because that is what the application is.
+
+  It was also order-dependent, which is what made it worth fixing rather than
+  documenting better: a suite whose growth tests happened to be collected first
+  passed, and the same tests named in the other order failed.
+
+  `scaled_world` now empties the tables its shape declares before building.
+  **Nothing is snapshotted, and nothing needs to be**: this happens inside the
+  atomic block it already rolls back, so whatever was there comes back when the
+  block ends. A table whose keys are `Disjoint` is left alone, mirroring the
+  exemption `build` already makes, so the documented hybrid -- parents made by
+  your code, children made here -- keeps working.
+
+  `build()` keeps its refusal. It has no transaction of its own to undo and
+  would be destroying rows for good.
+
+  The two statement-count constants moved: one TRUNCATE on PostgreSQL, one
+  DELETE per declared table elsewhere. Both are properties of the declaration
+  rather than the factor, so what those tests pin -- fixed on PostgreSQL at
+  every factor, a curve off it -- is unchanged.
+
+### Fixed
+
+- **`After` across a parent column of a different kind is refused.**
+  `date + timedelta` is a `date`, so a `DateTimeField` child whose parent column
+  was a `DateField` was filled with dates: `COPY` accepted them and they landed
+  as naive midnights. A world whose orders went on sale in 2024 had shows
+  starting in 1900, and the only signal was Django's own per-row
+  `RuntimeWarning` in the middle of a build that prints thousands of lines.
+
+  Both field types are on `_meta` and both are known before a row is generated,
+  so this belonged in the class of things already refused at declaration time.
+  Only `After` is checked, deliberately: `After` *is* `parent + offset` written
+  into this column, so the two describe the same quantity by construction, while
+  a `Derived` reading a parent column may legitimately convert -- turning a
+  timestamp into a count of days is an ordinary thing to declare.
+
 ## [0.16.0] — 2026-09-04
 
 ### Fixed
@@ -1050,7 +1115,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   into `COPY FROM STDIN`, which psycopg 2 cannot do without materialising them
   first.
 
-[Unreleased]: https://github.com/Artui/django-data-shape/compare/v0.16.0...HEAD
+[Unreleased]: https://github.com/Artui/django-data-shape/compare/v0.17.0...HEAD
+[0.17.0]: https://github.com/Artui/django-data-shape/compare/v0.16.0...v0.17.0
 [0.16.0]: https://github.com/Artui/django-data-shape/compare/v0.15.0...v0.16.0
 [0.15.0]: https://github.com/Artui/django-data-shape/compare/v0.14.0...v0.15.0
 [0.14.0]: https://github.com/Artui/django-data-shape/compare/v0.13.0...v0.14.0

{django_data_shape-0.16.0 → django_data_shape-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: django-data-shape
-Version: 0.16.0
+Version: 0.17.0
 Summary: A realistically shaped test database from Django models: declare cardinality, skew and fan-out, load by COPY, and make the query planner believe it.
 Project-URL: Homepage, https://github.com/Artui/django-data-shape
 Project-URL: Repository, https://github.com/Artui/django-data-shape

{django_data_shape-0.16.0 → django_data_shape-0.17.0}/django_data_shape/__init__.py

@@ -11,10 +11,13 @@ from django_data_shape.clone_database import clone_database
 from django_data_shape.derivation_queried_database import DerivationQueriedDatabase
 from django_data_shape.derivations.after import After
 from django_data_shape.derivations.aligned import Aligned
+from django_data_shape.derivations.copied import Copied
 from django_data_shape.derivations.derivation import Derivation
 from django_data_shape.derivations.derived import Derived
 from django_data_shape.derivations.given import Given
+from django_data_shape.derivations.offset import Offset
 from django_data_shape.derivations.per_parent import PerParent
+from django_data_shape.derivations.product import Product
 from django_data_shape.derivations.scope import Scope
 from django_data_shape.distributions.ascending import Ascending
 from django_data_shape.distributions.bounded import Bounded
@@ -67,6 +70,7 @@ __all__ = [
     "Categorical",
     "ChildrenPerParent",
     "Constant",
+    "Copied",
     "Derivation",
     "DerivationQueriedDatabase",
     "Derived",
@@ -81,8 +85,10 @@ __all__ = [
     "KeyFunction",
     "Md5Keys",
     "KeyStrategy",
+    "Offset",
     "Paired",
     "PerParent",
+    "Product",
     "Projection",
     "ScaleProtocol",
     "Scope",

django_data_shape-0.17.0/django_data_shape/derivations/copied.py

@@ -0,0 +1,46 @@
+"""A column taken verbatim from the parent's."""
+
+from __future__ import annotations
+
+from django_data_shape.derivations.scope import Scope
+
+
+class Copied:
+    """``relation.field``, unchanged.
+
+    A ticket's face value is the unit price of the order it belongs to; a line's
+    currency is its invoice's. There is no arithmetic at all, which is what made
+    needing a lambda for it -- and losing the template-database cache with it --
+    annoying rather than merely unfortunate. See
+    :class:`~django_data_shape.derivations.product.Product`.
+
+    Worth saying what this is *not*, because the two are easy to confuse. A
+    denormalised copy is a column with its own statistics: the planner sees a
+    distribution over the child table rather than a join, which is the whole
+    reason schemas carry such columns and the reason a shaped database has to
+    reproduce them. Reading the parent's column through the join is a different
+    query with a different plan.
+    """
+
+    def __init__(self, source: str) -> None:
+        self._source = source
+
+    @property
+    def scope(self) -> Scope:
+        return Scope.PARENT
+
+    @property
+    def sources(self) -> tuple[str, ...]:
+        return (self._source,)
+
+    def value(self, row: int, draw: float, sources: tuple[object, ...]) -> object:
+        return sources[0]
+
+    def canonical(self) -> object:
+        return ("Copied", self._source)
+
+    def __repr__(self) -> str:
+        return f"Copied({self._source!r})"
+
+
+__all__ = ["Copied"]

django_data_shape-0.17.0/django_data_shape/derivations/offset.py

@@ -0,0 +1,65 @@
+"""A fixed distance past another column of the same row."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from django_data_shape.derivations.scope import Scope
+from django_data_shape.invalid_shape import InvalidShape
+
+
+class Offset:
+    """``source + by``, where ``source`` is another column of this row.
+
+    The same-row half of :class:`~django_data_shape.derivations.after.After`,
+    which is parent-scoped only. A show goes on sale and then happens; an
+    invoice is issued and then falls due. Both columns are on the same row, and
+    until this existed the only way to say so was a lambda -- which cost the
+    whole shape its template-database cache. See
+    :class:`~django_data_shape.derivations.product.Product` for why that
+    mattered.
+
+    The gap is **fixed**, which is the difference from ``After``: that one
+    spreads a gap across ``within`` using the column's own draw, because a
+    child's distance from its parent is a real distribution. A due date thirty
+    days after an issue date is not a distribution, it is a term. Where the
+    spread is wanted on the same row, ``Derived`` still takes a callable.
+
+    ``by`` is in the column's own units -- a ``timedelta`` for a datetime
+    column, a number for a numeric one -- and anything supporting
+    ``source + by`` works.
+    """
+
+    def __init__(self, source: str, *, by: Any) -> None:
+        zero = by * 0
+        if by < zero:
+            raise InvalidShape(
+                f"Offset needs a non-negative by, got {by!r}. A column that lands "
+                "*before* another is that other column's Offset, declared the other "
+                "way round -- which keeps the two readable in the order they happen."
+            )
+        self._source = source
+        self._by = by
+
+    @property
+    def scope(self) -> Scope:
+        return Scope.ROW
+
+    @property
+    def sources(self) -> tuple[str, ...]:
+        return (self._source,)
+
+    def value(self, row: int, draw: float, sources: tuple[object, ...]) -> object:
+        # cast for the same reason After does: the column's type is the model's
+        # business, and a guard here is a branch no declaration reaches.
+        source = cast("Any", sources[0])
+        return source + self._by
+
+    def canonical(self) -> object:
+        return ("Offset", self._source, self._by)
+
+    def __repr__(self) -> str:
+        return f"Offset({self._source!r}, by={self._by!r})"
+
+
+__all__ = ["Offset"]

django_data_shape-0.17.0/django_data_shape/derivations/product.py

@@ -0,0 +1,67 @@
+"""The product of two columns of the same row."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from django_data_shape.derivations.scope import Scope
+
+
+class Product:
+    """``left * right``, read from two other columns of this row.
+
+    One of three derivations that exist because
+    :class:`~django_data_shape.derivations.derived.Derived` -- the only shipped
+    face that can read another column of the same row -- takes a callable, and
+    a callable cannot be digested. A shape holding one is refused by
+    :func:`~django_data_shape.template_database.template_database`, so a column
+    as ordinary as ``total = quantity * unit_price`` excluded the whole
+    declaration from the reuse that turns a forty-second build into a
+    hundred-millisecond clone.
+
+    That refusal is right and stays: two lambdas share a name, and identical
+    bytecode returns something else when a constant it reads is edited in
+    another module. What was wrong is what it excluded. These three say the
+    commonest arithmetic as **data**, so they implement
+    :class:`~django_data_shape.canonical.Canonical` and the shape hashes::
+
+        Table(
+            Order,
+            rows=2_000_000,
+            quantity=Aligned("basket", Uniform(1, 8, places=0)),
+            unit_price=Aligned("basket", Uniform(1500, 25000, places=0)),
+            total=Product("quantity", "unit_price"),
+        )
+
+    ``Derived`` is unchanged and remains the answer for computation that really
+    is code. The line between them is whether the declaration can be written
+    down: a product of two named columns can, a lambda cannot.
+    """
+
+    def __init__(self, left: str, right: str) -> None:
+        self._left = left
+        self._right = right
+
+    @property
+    def scope(self) -> Scope:
+        return Scope.ROW
+
+    @property
+    def sources(self) -> tuple[str, ...]:
+        return (self._left, self._right)
+
+    def value(self, row: int, draw: float, sources: tuple[object, ...]) -> object:
+        # cast rather than a narrowing check, as the other derivations do: what
+        # a column holds is decided by the model, not by this package, and a
+        # runtime guard would be a branch no declaration can reach.
+        left, right = (cast("Any", source) for source in sources)
+        return left * right
+
+    def canonical(self) -> object:
+        return ("Product", self._left, self._right)
+
+    def __repr__(self) -> str:
+        return f"Product({self._left!r}, {self._right!r})"
+
+
+__all__ = ["Product"]

{django_data_shape-0.16.0 → django_data_shape-0.17.0}/django_data_shape/scaled_world.py

@@ -5,9 +5,10 @@ from __future__ import annotations
 from collections.abc import Iterator
 from contextlib import contextmanager
 
-from django.db import DEFAULT_DB_ALIAS, transaction
+from django.db import DEFAULT_DB_ALIAS, connections, transaction
 
 from django_data_shape.build import build
+from django_data_shape.keys.disjoint import Disjoint
 from django_data_shape.scaled_shape import scaled_shape
 from django_data_shape.shape import Shape
 
@@ -81,8 +82,10 @@ def scaled_world(shape: Shape, factor: int, *, using: str = DEFAULT_DB_ALIAS) ->
     not drawn -- so the only visible effect is that a row created by the ORM
     after a world is torn down gets a larger id than it otherwise would.
     """
+    scaled = scaled_shape(shape, factor)
     with transaction.atomic(using=using):
-        result = build(scaled_shape(shape, factor), using=using, require_statistics=False)
+        _empty_declared_tables(scaled, using)
+        result = build(scaled, using=using, require_statistics=False)
         yield result.rows
         # Rolling back on the way out rather than raising and swallowing an
         # exception to get there: set_rollback is the supported way to leave an
@@ -90,3 +93,54 @@ def scaled_world(shape: Shape, factor: int, *, using: str = DEFAULT_DB_ALIAS) ->
         # never reaches this line and does not need to -- atomic rolls back for
         # exactly that case already.
         transaction.set_rollback(True, using=using)
+
+
+def _empty_declared_tables(shape: Shape, using: str) -> None:
+    """Clear the tables ``shape`` declares, inside the caller's transaction.
+
+    A world at a factor is the declared shape at that size and nothing else, so
+    rows already in those tables are not this world's -- and emptying them is
+    what lets a scaled world be built over a session world, which is the one
+    composition of this package's two pytest surfaces that an application with a
+    single model graph needs and could not have.
+
+    **Nothing is snapshotted, and nothing needs to be.** This runs inside the
+    atomic block ``scaled_world`` already rolls back, so whatever was there
+    comes back when the block ends -- the session world included. That is the
+    whole reason the fix is four lines rather than a save-and-restore: the
+    database was already going to undo this.
+
+    Emptying rather than refusing is safe *only* here, and that is why it lives
+    in this function and not in ``build``. A bare ``build()`` keeps its refusal,
+    because it has no transaction of its own to undo and would be destroying
+    rows for good.
+
+    A table whose keys are :class:`~django_data_shape.keys.disjoint.Disjoint`
+    is left alone, mirroring the exemption ``build`` makes for the same reason:
+    those keys cannot collide with a caller's rows, so the hybrid this package
+    documents -- parents made by your code, children made here -- must keep
+    working. Deleting the parents would break it in a new way.
+    """
+    connection = connections[using]
+    tables = [
+        table.db_table
+        for table in shape.tables
+        if not isinstance(getattr(table, "keys", None), Disjoint)
+    ]
+    if not tables:
+        return
+    quoted = ", ".join(connection.ops.quote_name(name) for name in tables)
+    with connection.cursor() as cursor:
+        if connection.vendor == "postgresql":
+            # TRUNCATE is transactional on PostgreSQL, so it rolls back with the
+            # rest of the block. CASCADE covers a foreign key from a table this
+            # shape does not declare; RESTART IDENTITY is deliberately omitted,
+            # because a sequence reset is not transactional and would leave the
+            # counter behind the rows that came back.
+            cursor.execute(f"TRUNCATE {quoted} CASCADE")
+        else:
+            # DELETE rather than TRUNCATE off PostgreSQL: SQLite has no
+            # TRUNCATE, and the loads here are small enough that the difference
+            # does not matter.
+            for name in reversed(tables):
+                cursor.execute(f"DELETE FROM {connection.ops.quote_name(name)}")

{django_data_shape-0.16.0 → django_data_shape-0.17.0}/django_data_shape/table.py

@@ -8,6 +8,7 @@ from typing import Any, cast
 
 from django.db.models import Field, Model
 
+from django_data_shape.derivations.after import After
 from django_data_shape.derivations.derivation import Derivation
 from django_data_shape.derivations.per_parent import PerParent
 from django_data_shape.derivations.scope import Scope
@@ -26,6 +27,7 @@ from django_data_shape.utils import (
     check_not_inherited,
     check_statistics_target,
     has_db_default,
+    offsettable_kind,
     primary_key_field,
 )
 
@@ -370,6 +372,47 @@ class Table:
                     f"field named {field_name}. Its concrete fields are: "
                     f"{', '.join(sorted(available))}."
                 )
+            if isinstance(declared, After):
+                self._check_offset_units(name, source, parent, field_name, known[name])
+
+    def _check_offset_units(
+        self,
+        name: str,
+        source: str,
+        parent: type[Model],
+        field_name: str,
+        column: Field[Any, Any],
+    ) -> None:
+        """Refuse an ``After`` whose parent column is a different kind of thing.
+
+        Only ``After`` is checked, and deliberately not every parent-scoped
+        derivation: ``After`` *is* ``parent + offset`` written into this column,
+        so the two columns describe the same quantity by construction. A
+        ``Derived`` reading a parent column may legitimately convert -- turning
+        a timestamp into a count of days is an ordinary thing to declare -- and
+        a check that could not tell the two apart would refuse it.
+
+        The failure this prevents is silent rather than loud, which is why it
+        is worth a refusal at declaration time. ``date + timedelta`` is a
+        ``date``; the load accepts it, the rows arrive as naive midnights, and
+        the only complaint is Django's own per-row warning in the middle of a
+        build that prints thousands of lines.
+        """
+        parent_field = cast("Field[Any, Any]", parent._meta.get_field(field_name))
+        parent_kind = offsettable_kind(parent_field)
+        column_kind = offsettable_kind(column)
+        if parent_kind is None or column_kind is None or parent_kind == column_kind:
+            return
+        raise InvalidShape(
+            f"{self.model.__name__}.{name} is After({source!r}), which writes that parent "
+            f"column plus an offset into this one -- but {parent.__name__}.{field_name} is a "
+            f"{type(parent_field).__name__} and {self.model.__name__}.{name} is a "
+            f"{type(column).__name__}. Adding an offset to a "
+            f"{type(parent_field).__name__} produces a {parent_kind}, so this column would be "
+            f"filled with the wrong kind of value and the load would accept it. Read a "
+            f"{type(column).__name__} on the parent, or fill this column with a distribution "
+            "of its own."
+        )
 
     def _check_group_sources(self, name: str, declared: Derivation) -> None:
         """Refuse a group-scoped column whose groups are not there to be grouped by.

{django_data_shape-0.16.0 → django_data_shape-0.17.0}/django_data_shape/utils.py

@@ -5,7 +5,17 @@ from __future__ import annotations
 import hashlib
 from typing import Any
 
-from django.db.models import Field, Model
+from django.db.models import (
+    DateField,
+    DateTimeField,
+    DecimalField,
+    DurationField,
+    Field,
+    FloatField,
+    IntegerField,
+    Model,
+    TimeField,
+)
 from django.db.models.fields import NOT_PROVIDED
 
 from django_data_shape.invalid_shape import InvalidShape
@@ -191,3 +201,34 @@ def check_not_inherited(model: type[Model]) -> None:
         f"{parents} on its own for the columns that live in its table, and make the rows of "
         f"{model.__name__} another way."
     )
+
+
+def offsettable_kind(field: Field[Any, Any]) -> str | None:
+    """What kind of thing this column holds, for the purpose of adding to it.
+
+    ``After`` writes ``parent + offset`` into a column, so the parent's column
+    and the child's have to be the same kind of thing. They are not
+    interchangeable even when Python will add them: ``date + timedelta`` is a
+    ``date``, so a ``DateTimeField`` filled from a ``DateField`` parent gets
+    dates, ``COPY`` accepts them, and they land as naive midnights.
+
+    ``DateTimeField`` is checked before ``DateField`` because it *subclasses*
+    it -- the one ordering in this function that is load-bearing, and the reason
+    an ``isinstance`` chain is used rather than a mapping keyed on the class.
+
+    Returns ``None`` for a column this package has no opinion about, and the
+    caller then declines to judge rather than inventing a refusal: a custom
+    field that adds cleanly to an offset is a legitimate thing to declare, and
+    refusing it would cost a caller a working shape to buy nothing.
+    """
+    if isinstance(field, DateTimeField):
+        return "datetime"
+    if isinstance(field, DateField):
+        return "date"
+    if isinstance(field, TimeField):
+        return "time"
+    if isinstance(field, DurationField):
+        return "duration"
+    if isinstance(field, (IntegerField, FloatField, DecimalField)):
+        return "number"
+    return None

{django_data_shape-0.16.0 → django_data_shape-0.17.0}/django_data_shape/version.py

@@ -2,6 +2,6 @@
 
 from __future__ import annotations
 
-__version__: str = "0.16.0"
+__version__: str = "0.17.0"
 
 __all__ = ["__version__"]

{django_data_shape-0.16.0 → django_data_shape-0.17.0}/docs/derivations.md

@@ -35,6 +35,9 @@ different places, and the place is the only thing that varies:
 | `After` | `parent` | `"relation.field"` on the parent row | an order opened after its account signed up |
 | `Given` | `parent` | `"relation.field"` on the parent row | severity skewed by the account's plan |
 | `Aligned` | `rank` | a shared rank the declaration names | the whales are the same whales |
+| `Product` | `row` | two other columns of this row | `total = quantity * unit_price` |
+| `Offset` | `row` | one other column of this row | a show starts 75 days after it goes on sale |
+| `Copied` | `parent` | `"relation.field"`, unchanged | a ticket's face value is its order's unit price |
 
 `Derived` is the mechanism and the other three are shorthand over it. The scope
 is a parameter, so a correlation nobody shipped a face for is still declarable:
@@ -43,6 +46,35 @@ is a parameter, so a correlation nobody shipped a face for is still declarable:
 region = Derived("account.country", compute=region_of, scope="parent")
 ```
 
+## Why three of them say arithmetic as data
+
+`Product`, `Offset` and `Copied` compute nothing `Derived` could not. They exist
+because of what `Derived` costs, and the cost is not obvious from the
+declaration.
+
+`Derived` takes a **callable**, and a callable cannot be honestly digested: two
+lambdas share a name, and identical bytecode returns something else when a
+constant it reads is edited in another module. So a shape holding one is refused
+by [`template_database`](statistics.md) -- and that refusal is right, because a
+cache key that agreed while the data changed would serve a stale database to a
+suite that then passes.
+
+What was wrong is what it excluded. `total = quantity * unit_price` is about as
+ordinary as a column gets, and declaring it with a lambda took the whole shape
+out of the reuse that turns a forty-second build into a hundred-millisecond
+clone. `build()` kept working, so nothing said what it had cost.
+
+These three are pure data -- a product of two named columns, a fixed offset, a
+parent column unchanged -- so they implement `Canonical` and the shape hashes.
+Reach for `Derived` when the computation really is code; reach for these when it
+can be written down.
+
+`Offset` is also the same-row half of `After`, which is parent-scoped only. The
+difference beyond scope is that `After` spreads its gap across `within` using
+the column's own draw, because a child's distance from its parent is a real
+distribution; `Offset`'s gap is fixed, because a due date thirty days after an
+issue date is a term rather than a distribution.
+
 That is why they are one thing. Built separately, "custom creation logic" and
 "correlate across a relation" become two vocabularies overlapping on the
 interesting half -- and the half a consumer asks for first is the within-row one,

{django_data_shape-0.16.0 → django_data_shape-0.17.0}/docs/reference.md

@@ -76,6 +76,12 @@
 
 ::: django_data_shape.derivations.aligned.Aligned
 
+::: django_data_shape.derivations.product.Product
+
+::: django_data_shape.derivations.offset.Offset
+
+::: django_data_shape.derivations.copied.Copied
+
 ## Keys
 
 ::: django_data_shape.keys.key_strategy.KeyStrategy

{django_data_shape-0.16.0 → django_data_shape-0.17.0}/pyproject.toml

@@ -170,7 +170,7 @@ skip-magic-trailing-comma = false
 root = ["./django_data_shape"]
 
 [tool.bumpversion]
-current_version = "0.16.0"
+current_version = "0.17.0"
 allow_dirty = false
 commit = false
 tag = false

django_data_shape-0.17.0/tests/derivations/test_after_units.py

@@ -0,0 +1,77 @@
+"""``After`` writes the parent's value plus an offset, so the two columns have
+to be the same kind of thing.
+
+``date + timedelta`` is a ``date``. A ``DateTimeField`` child filled across an
+edge whose parent column is a ``DateField`` was therefore filled with dates:
+``COPY`` accepted them, they landed as naive midnights, and the only signal was
+Django's own per-row ``RuntimeWarning`` in the middle of a build.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+
+import pytest
+
+from django_data_shape import After, Constant, FanOut, InvalidShape, Sequential, Table, Zipf
+from tests.testapp.models import Performance, Ticket
+
+
+def test_a_date_parent_under_a_datetime_child_is_refused() -> None:
+    with pytest.raises(InvalidShape) as excinfo:
+        Table(
+            Performance,
+            rows=10,
+            playhouse=FanOut(Zipf()),
+            starts_at=After("playhouse.opened_on", within=dt.timedelta(days=1)),
+            doors_on=Constant(dt.date(2026, 1, 1)),
+        )
+
+    message = str(excinfo.value)
+    assert "Performance.starts_at" in message
+    assert "playhouse.opened_on" in message
+    # Both kinds named, because a reader who has to look them up has been given
+    # an error that knows more than it says.
+    assert "DateField" in message
+    assert "DateTimeField" in message
+
+
+def test_a_datetime_parent_under_a_date_child_is_refused() -> None:
+    """The other direction truncates rather than misdating, and is still wrong."""
+    with pytest.raises(InvalidShape, match="doors_on"):
+        Table(
+            Performance,
+            rows=10,
+            playhouse=FanOut(Zipf()),
+            starts_at=Sequential(
+                dt.datetime(2026, 1, 1, tzinfo=dt.timezone.utc), dt.timedelta(hours=1)
+            ),
+            doors_on=After("playhouse.announced_at", within=dt.timedelta(days=1)),
+        )
+
+
+def test_matching_kinds_are_accepted() -> None:
+    """A `DateField` after a `DateField` is exactly what the edge is for."""
+    Table(
+        Performance,
+        rows=10,
+        playhouse=FanOut(Zipf()),
+        starts_at=Sequential(
+            dt.datetime(2026, 1, 1, tzinfo=dt.timezone.utc), dt.timedelta(hours=1)
+        ),
+        doors_on=After("playhouse.opened_on", within=dt.timedelta(days=1)),
+    )
+
+
+def test_the_documented_datetime_case_still_builds() -> None:
+    """The example in `After`'s own docstring, unchanged."""
+    Table(
+        Ticket,
+        rows=10,
+        account=FanOut(Zipf()),
+        opened_at=After("account.signed_up_at", within=dt.timedelta(days=365)),
+        severity=Constant("low"),
+        quantity=Constant(1),
+        unit_price=Constant("1.00"),
+        total=Constant("1.00"),
+    )