smart-data-engine-sdk 0.1.0__py3-none-any.whl

sde/types.py

@@ -0,0 +1,228 @@
+"""The neutral type vocabulary, and the mapping from Python's types onto it.
+
+Why a vocabulary at all: ``Decimal`` in Python and ``BigDecimal`` in Java have to land on the same
+bytes in the canonical IR, or the same model gets two versions and the control plane sees two
+models. So no language's own type names ever reach the IR. Each library maps its host language onto
+this closed set, and the mapping is part of the published contract rather than an implementation
+detail.
+
+The set:
+
+    bool int32 int64 float32 float64 decimal(p,s) string bytes uuid date timestamp timestamptz json
+
+``decimal`` is the only parameterised member, written ``decimal(12,2)`` - precision then scale, no
+spaces. It is parameterised because a decimal without precision is not a storable type in any of the
+engines we place data in, and asking the engine to pick would make the physical schema depend on
+something the model did not say.
+
+**Floats are in the vocabulary, and this needed a correction to the specification.** The first draft
+of the format contract said "no floating point anywhere", conflating two different things. Canonical
+*encoding* must contain no float literals, because their textual form differs between languages -
+that rule stands and ``canonical.py`` enforces it. But a *field* may perfectly well be a float:
+sensor readings are the obvious case, and IoT at scale is one of the segments this product is aimed
+at. A field of type ``float64`` is recorded in the IR as the string ``"float64"``, so there is no
+float literal involved and no conflict. Forbidding the type would have meant telling a client to
+store temperatures as decimals, which is worse engineering than the rule was worth.
+
+Two mappings are defaults rather than one-to-one, and both are documented here because a silent
+default in a type mapping is the kind of thing that surfaces two years later as a timezone bug:
+
+* ``int`` maps to ``int64``. Python's integers are unbounded, so any choice is a narrowing; 64 bits
+  is what every target engine has a native type for. Use :data:`Int32` to say so explicitly.
+* ``datetime`` maps to ``timestamptz``. A naive timestamp is a latent bug in a system that may move
+  data between engines and regions, so the safe reading is the default and the narrow one has to be
+  asked for by name with :data:`Timestamp`.
+
+Anything with no mapping - a bare ``Decimal``, a custom class, ``complex`` - is a
+:class:`~sde.errors.DeclarationError`. Guessing would produce a physical schema the model did not
+ask for.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import decimal as _decimal
+import types as _pytypes
+import typing
+import uuid as _uuid
+from dataclasses import dataclass
+from typing import Annotated, Any, Final, get_args, get_origin
+
+from .errors import DeclarationError
+
+__all__ = [
+    "NEUTRAL_TYPES",
+    "Float32",
+    "Int32",
+    "Json",
+    "Timestamp",
+    "precision",
+    "resolve_type",
+]
+
+NEUTRAL_TYPES: Final[frozenset[str]] = frozenset(
+    {
+        "bool",
+        "int32",
+        "int64",
+        "float32",
+        "float64",
+        "string",
+        "bytes",
+        "uuid",
+        "date",
+        "timestamp",
+        "timestamptz",
+        "json",
+        # decimal is parameterised and validated by pattern, not by membership here.
+    }
+)
+
+
+@dataclass(frozen=True)
+class _Marker:
+    """Base for the annotations that disambiguate a mapping."""
+
+    kind: str
+
+
+@dataclass(frozen=True)
+class _Precision(_Marker):
+    digits: int
+    scale: int
+
+
+def precision(digits: int, scale: int) -> _Precision:
+    """Annotate a ``Decimal`` field with its precision and scale.
+
+    ``total: Annotated[Decimal, precision(12, 2)]``
+
+    Both are required. A decimal without them is not a storable type, and letting the engine choose
+    would make the physical schema depend on something the model never stated.
+    """
+    if digits < 1 or scale < 0 or scale > digits:
+        raise DeclarationError(
+            f"precision({digits}, {scale}) is not a usable decimal: digits must be at least 1 and "
+            "scale must be between 0 and digits"
+        )
+    return _Precision(kind="precision", digits=digits, scale=scale)
+
+
+Int32 = Annotated[int, _Marker(kind="int32")]
+"""A 32-bit integer, said explicitly. Bare ``int`` maps to ``int64``."""
+
+Float32 = Annotated[float, _Marker(kind="float32")]
+"""A single-precision float. Bare ``float`` maps to ``float64``."""
+
+Timestamp = Annotated[_dt.datetime, _Marker(kind="naive")]
+"""A timestamp without a zone. Bare ``datetime`` maps to ``timestamptz`` on purpose."""
+
+Json = Annotated[object, _Marker(kind="json")]
+"""An opaque JSON document. Use when the shape genuinely is not fixed, not to avoid declaring it."""
+
+_SIMPLE: Final[dict[Any, str]] = {
+    bool: "bool",
+    int: "int64",
+    float: "float64",
+    str: "string",
+    bytes: "bytes",
+    _uuid.UUID: "uuid",
+    _dt.date: "date",
+    _dt.datetime: "timestamptz",
+    dict: "json",
+    list: "json",
+}
+
+
+def _markers(annotation: object) -> tuple[object, tuple[_Marker, ...]]:
+    """Peel ``Annotated`` and ``Optional`` off an annotation.
+
+    Returns the bare type plus any markers found. Nullability is handled by the caller, which needs
+    to record it separately in the IR rather than as part of the type name.
+    """
+    markers: list[_Marker] = []
+    current = annotation
+    while get_origin(current) is Annotated:
+        args = get_args(current)
+        current = args[0]
+        markers.extend(m for m in args[1:] if isinstance(m, _Marker))
+    return current, tuple(markers)
+
+
+def _is_optional(annotation: object) -> tuple[bool, object]:
+    """Peel ``| None`` off, and refuse anything wider.
+
+    ``str | None`` is a nullable string. ``int | str`` is not a field: it has no single physical
+    representation, so there is no column we could create for it and no index we could put on it.
+    Refusing here rather than falling through to the vocabulary check matters only for the error
+    message, and the error message is the whole product for someone who mistyped an annotation.
+    """
+    origin = get_origin(annotation)
+    if origin is typing.Union or origin is _pytypes.UnionType:
+        args = get_args(annotation)
+        non_none = [a for a in args if a is not type(None)]
+        if len(non_none) != 1:
+            raise DeclarationError(
+                f"{annotation!r} is a union of several types. A field has one type; a union of two "
+                "real types has no single physical representation, so it cannot be placed. Model "
+                "it "
+                "as separate nullable fields, or as json if the shape really is not fixed."
+            )
+        return len(non_none) != len(args), non_none[0]
+    return False, annotation
+
+
+def resolve_type(annotation: object, *, field: str, entity: str) -> tuple[str, bool]:
+    """Map a Python annotation onto ``(neutral_type, nullable)``.
+
+    Raises :class:`~sde.errors.DeclarationError` naming the field, because the reader has to fix
+    their declaration and a traceback into this module tells them nothing.
+    """
+    nullable, inner = _is_optional(annotation)
+    bare, markers = _markers(inner)
+    # Optional may sit inside Annotated as well: Annotated[int | None, ...].
+    nested_nullable, bare = _is_optional(bare)
+    nullable = nullable or nested_nullable
+
+    kinds = {m.kind for m in markers}
+
+    if bare is _decimal.Decimal:
+        found = [m for m in markers if isinstance(m, _Precision)]
+        if not found:
+            raise DeclarationError(
+                f"{entity}.{field} is a Decimal without precision. Write "
+                f"Annotated[Decimal, precision(digits, scale)] - a decimal without precision is "
+                "not "
+                "a storable type in any engine we place data in, and choosing for you would make "
+                "the physical schema depend on something your model did not say."
+            )
+        p = found[0]
+        return f"decimal({p.digits},{p.scale})", nullable
+
+    if "json" in kinds:
+        return "json", nullable
+    if "int32" in kinds:
+        return "int32", nullable
+    if "float32" in kinds:
+        return "float32", nullable
+    if "naive" in kinds:
+        if bare is not _dt.datetime:
+            raise DeclarationError(
+                f"{entity}.{field} is annotated as a naive timestamp but is not a datetime"
+            )
+        return "timestamp", nullable
+
+    origin = get_origin(bare)
+    if origin in (dict, list):
+        return "json", nullable
+
+    mapped = _SIMPLE.get(bare)
+    if mapped is not None:
+        return mapped, nullable
+
+    raise DeclarationError(
+        f"{entity}.{field} has type {bare!r}, which has no place in the neutral type vocabulary "
+        f"({', '.join(sorted(NEUTRAL_TYPES))}, decimal(p,s)). Map it yourself - to a string, to "
+        "json, to a decimal with stated precision - so that the choice is visible in the model "
+        "instead of being guessed here."
+    )

sde/verification.py

@@ -0,0 +1,220 @@
+"""Bind a comparison to one request, project and exact placement map, without carrying rows.
+
+A matching row count is not evidence about a particular migration. The request is persisted by
+the controller before comparison and echoed by the verifier only after checking its local session.
+Its unpredictable id distinguishes repeated verification rounds; the project id comes from local
+client configuration, so identical models/maps in two projects are not interchangeable evidence.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+from .errors import MigrationRefused
+
+if TYPE_CHECKING:
+    from .placement import PlacementMap
+
+REQUEST_PROTOCOL = 1
+
+
+def aware_time(value: str) -> datetime:
+    pattern = (
+        r"\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d"
+        r"(?:\.\d{1,6})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)"
+    )
+    if not isinstance(value, str) or re.fullmatch(pattern, value) is None:
+        raise MigrationRefused("verification time must be an ISO timestamp with an offset")
+    try:
+        result = datetime.fromisoformat(value[:-1] + "Z" if value.endswith("z") else value)
+    except (TypeError, ValueError) as exc:
+        raise MigrationRefused("verification time must be an ISO timestamp with an offset") from exc
+    if result.tzinfo is None or result.utcoffset() is None:
+        raise MigrationRefused("verification time must include its UTC offset")
+    return result
+
+
+def _hex(value: str, width: int, field: str) -> None:
+    if not isinstance(value, str) or re.fullmatch(f"[0-9a-f]{{{width}}}", value) is None:
+        raise MigrationRefused(f"verification {field} must be {width} lowercase hexadecimal digits")
+
+
+def _name(value: str) -> None:
+    if not isinstance(value, str) or not value:
+        raise MigrationRefused("verification names must be nonempty strings")
+
+
+@dataclass(frozen=True)
+class VerificationRequest:
+    request_id: str
+    project_id: str
+    model_version: str
+    map_version: int
+    map_fingerprint: str
+    group: str
+    source_engine: str
+    source_id: str
+    targets: tuple[tuple[str, str], ...]
+    requested_at: str
+    requires_signature: bool
+
+    def __post_init__(self) -> None:
+        for value, width, name in (
+            (self.request_id, 32, "request_id"),
+            (self.project_id, 32, "project_id"),
+            (self.model_version, 16, "model_version"),
+            (self.map_fingerprint, 64, "map_fingerprint"),
+        ):
+            _hex(value, width, name)
+        if type(self.map_version) is not int or not 1 <= self.map_version <= 9_007_199_254_740_991:
+            raise MigrationRefused("verification map_version must be a positive integer")
+        if type(self.requires_signature) is not bool:
+            raise MigrationRefused("verification requires_signature must be a boolean")
+        for name in (self.group, self.source_engine, self.source_id):
+            _name(name)
+        if (
+            not isinstance(self.targets, tuple)
+            or not self.targets
+            or any(not isinstance(target, tuple) or len(target) != 2 for target in self.targets)
+        ):
+            raise MigrationRefused("verification targets must be nonempty engine/id pairs")
+        for engine, identity in self.targets:
+            _name(engine)
+            _name(identity)
+            if identity == self.source_id:
+                raise MigrationRefused("verification source cannot also be a target")
+        if len({identity for _, identity in self.targets}) != len(self.targets):
+            raise MigrationRefused("verification target ids must be unique")
+        if self.targets != tuple(sorted(self.targets)):
+            raise MigrationRefused("verification targets must be sorted by engine and id")
+        aware_time(self.requested_at)
+
+    def as_record(self) -> dict[str, Any]:
+        return {
+            "protocol": REQUEST_PROTOCOL,
+            "request_id": self.request_id,
+            "project_id": self.project_id,
+            "model_version": self.model_version,
+            "map_version": self.map_version,
+            "map_fingerprint": self.map_fingerprint,
+            "group": self.group,
+            "source": {"engine": self.source_engine, "id": self.source_id},
+            "targets": [{"engine": engine, "id": identity} for engine, identity in self.targets],
+            "requested_at": self.requested_at,
+            "requires_signature": self.requires_signature,
+        }
+
+    @classmethod
+    def from_record(cls, record: Mapping[str, Any]) -> VerificationRequest:
+        fields = {
+            "protocol",
+            "request_id",
+            "project_id",
+            "model_version",
+            "map_version",
+            "map_fingerprint",
+            "group",
+            "source",
+            "targets",
+            "requested_at",
+            "requires_signature",
+        }
+        if not isinstance(record, Mapping) or set(record) != fields:
+            raise MigrationRefused("verification request has missing or unknown fields")
+        if type(record["protocol"]) not in (int, float) or record["protocol"] != REQUEST_PROTOCOL:
+            raise MigrationRefused("unsupported verification request protocol")
+        source, targets = record["source"], record["targets"]
+        if not isinstance(source, Mapping) or set(source) != {"engine", "id"}:
+            raise MigrationRefused("verification source must contain exactly engine and id")
+        if not isinstance(targets, list) or any(
+            not isinstance(target, Mapping) or set(target) != {"engine", "id"} for target in targets
+        ):
+            raise MigrationRefused("verification targets must contain exactly engine and id")
+        return cls(
+            request_id=record["request_id"],
+            project_id=record["project_id"],
+            model_version=record["model_version"],
+            map_version=_integer(record["map_version"], "map_version"),
+            map_fingerprint=record["map_fingerprint"],
+            group=record["group"],
+            source_engine=source["engine"],
+            source_id=source["id"],
+            targets=tuple((target["engine"], target["id"]) for target in targets),
+            requested_at=record["requested_at"],
+            requires_signature=record["requires_signature"],
+        )
+
+    def check_session(self, placement: PlacementMap, *, project_id: str | None, group: str) -> None:
+        if project_id != self.project_id:
+            raise MigrationRefused(
+                "verification request names another project, or this session has no project_id. "
+                "Configure the project id from the client's enrollment, not from the request."
+            )
+        if group != self.group:
+            raise MigrationRefused("verification request names another group")
+        expected = verification_request(
+            placement,
+            group=group,
+            project_id=project_id,
+            request_id=self.request_id,
+            requested_at=self.requested_at,
+        )
+        if self != expected:
+            raise MigrationRefused(
+                "verification request does not match this session's model, map, source or targets; "
+                "no comparison was started"
+            )
+
+    def check_time(self, at: str) -> None:
+        if aware_time(at) < aware_time(self.requested_at):
+            raise MigrationRefused(
+                "verification predates its request; check the verifier's clock and run the "
+                "comparison for the current request"
+            )
+
+
+def verification_request(
+    placement: PlacementMap,
+    *,
+    group: str,
+    project_id: str,
+    request_id: str,
+    requested_at: str,
+) -> VerificationRequest:
+    if placement.fingerprint is None:
+        raise MigrationRefused("verification needs a loaded, canonically encodable placement map")
+    spot = placement.placement_of(group)
+    return VerificationRequest(
+        request_id=request_id,
+        project_id=project_id,
+        model_version=placement.model_version,
+        map_version=placement.map_version,
+        map_fingerprint=placement.fingerprint,
+        group=group,
+        source_engine=spot.source.engine,
+        source_id=spot.source.id,
+        targets=tuple(sorted((target.engine, target.id) for target in spot.also_write)),
+        requested_at=requested_at,
+        requires_signature=placement.signed,
+    )
+
+
+def check_project_id(value: str | None) -> None:
+    if value is not None:
+        _hex(value, 32, "project_id")
+
+
+def _integer(value: Any, field: str) -> int:
+    # JSON Schema integers include an integral JSON number such as 1.0. JavaScript has one
+    # number type, so normalize that value here without ever truncating a fractional value.
+    if (
+        type(value) not in (int, float)
+        or not 1 <= value <= 9_007_199_254_740_991
+        or int(value) != value
+    ):
+        raise MigrationRefused(f"verification {field} must be a positive safe integer")
+    return int(value)

sde/watermark.py

@@ -0,0 +1,222 @@
+"""Refusing a placement map that goes backwards, and the durable state that makes it possible.
+
+A signed map for version 3 verifies correctly forever - that is what a signature is. So replacing
+the client's map file with an older signed one loads cleanly, routes writes to the previous
+placement, and **nothing protests**. Today that costs a client a stale schema. Once the migration
+state travels in the map, it costs them writes: a library reverted from dual-write to single-write
+in the middle of a migration drops exactly the rows the migration exists not to drop.
+
+Refusing it needs one thing the library has never had: **memory**. Everything else here is a pure
+function of a document, a model and a key, which is why it can be verified by reading it. This
+module is the exception, and each of the three obvious places to keep that memory is worse than the
+one chosen:
+
+- **in the process** protects until the first restart, and a restart is when a swapped file is
+  read. A protection that lapses exactly when it is needed;
+- **in a file** needs a configured path, and in a container that path is usually ephemeral - so it
+  degrades to the first option while continuing to look like the third. The worst property
+  available: a guarantee that is present in the code and absent in production;
+- **with us** would mean the library asking our service whether it may start, which is the one
+  thing this product promises it will never need to do. Our outage would become the client's.
+
+So it lives **in the client's own engines**, in a table this library owns. The library already
+creates tables there; this is one more, it holds no client data, and we still never see a row of it.
+
+Four properties, and the first two are what make it safe rather than merely present.
+
+**Append-only, and the watermark is `max(map_version)`.** No update, no key enforcement, no
+row-level contention - and therefore identical semantics in PostgreSQL and in ClickHouse, which is
+the engine that has no unique constraint to offer. A stale row can never lower the bar. It also
+leaves an audit trail for free: which map versions this deployment has seen, and when.
+
+**Every participating engine is written, and the watermark is the maximum over all of them.**
+Losing an engine cannot lose the protection, and one engine lagging cannot weaken it.
+
+**An engine that cannot store it does not participate, and that is reported rather than hidden.**
+The orderbook engine has a schema fixed in its own source and no room for bookkeeping, so a client
+whose only engine is that one has no rollback protection and cannot have any. The honest maximum is
+to say so - :class:`WatermarkCheck` carries it and ``Session`` exposes it, because a protection
+whose state cannot be read is a protection taken on trust.
+
+**Only signed maps are checked.** An unsigned map is the client's own document: hand-writing one and
+pointing a library at it is the no-account mode, and their business what they replace it with. A
+signed map is one we issued, which is precisely when we are the authority on what the newest version
+is. In pure no-account mode this module does nothing at all - no table, no query, no cost.
+
+The escape hatch is deliberately not a parameter. A legitimate rollback - we issued a bad map -
+means clearing the bookkeeping, and the refusal says how. A parameter called ``allow_rollback``
+would be set once during an incident and left set.
+
+**A limitation worth stating.** The watermark is per engine and the format has no field naming which
+stream of maps a document belongs to, so an engine shared by two independent map streams would have
+the higher one refusing the lower. The fix is a separate database per stream, which a shared engine
+wants regardless; inventing a stream identifier would mean a new key in a signed document, which is
+a loosening of the format and a contract bump in every language at once.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Literal, Protocol, runtime_checkable
+
+from .capabilities import satisfies
+from .errors import MapRolledBack
+from .logging import log
+from .placement import WATERMARK_TABLE, PlacementMap
+
+__all__ = [
+    "WATERMARK_TABLE",
+    "Protection",
+    "WatermarkCheck",
+    "WatermarkStore",
+    "enforce_forward_only",
+]
+
+Protection = Literal["enforced", "unavailable", "not_applicable"]
+
+
+@runtime_checkable
+class WatermarkStore(Protocol):
+    """What an engine adapter needs to offer to take part.
+
+    A separate protocol from :class:`~sde.session.Engine`, and optional. Adding two methods to
+    ``Engine`` would break every adapter anybody has written against it - including the fakes in
+    somebody else's test suite - for a capability one of our own three engines cannot provide
+    anyway. So participation is discovered rather than required, and non-participation is a
+    reportable state instead of a crash.
+    """
+
+    def map_watermark(self) -> int | None: ...
+    def record_map_version(self, version: int, *, model_version: str) -> None: ...
+
+
+@dataclass(frozen=True)
+class WatermarkCheck:
+    """What the check did, in a form a client can assert on.
+
+    Exposed rather than kept private on purpose. A protection whose state cannot be read is a
+    protection taken on trust, and this product's whole argument is that its guarantees are
+    checkable by reading the code and now by reading this.
+    """
+
+    protection: Protection
+    map_version: int
+    highest_seen: int | None
+    participating: tuple[str, ...]
+    unable: tuple[str, ...]
+    why: str
+
+    def as_record(self) -> dict[str, Any]:
+        return {
+            "protection": self.protection,
+            "map_version": self.map_version,
+            "highest_seen": self.highest_seen,
+            "participating": list(self.participating),
+            "unable": list(self.unable),
+            "why": self.why,
+        }
+
+
+def _split(engines: Mapping[str, Any]) -> tuple[tuple[str, ...], tuple[str, ...]]:
+    """Which engines can keep the bookkeeping and which cannot, both sorted.
+
+    Asked with :func:`sde.capabilities.satisfies` rather than `isinstance`, because a
+    runtime_checkable protocol resolves members without consulting `__getattr__` - so a client
+    wrapping one of our adapters for metrics or retries would be reported here as an engine with
+    nowhere to keep the bookkeeping, and would silently lose rollback protection under a message
+    blaming their engine's schema.
+    """
+    able = sorted(name for name, engine in engines.items() if satisfies(engine, WatermarkStore))
+    unable = sorted(set(engines) - set(able))
+    return tuple(able), tuple(unable)
+
+
+def enforce_forward_only(
+    placement: PlacementMap, engines: Mapping[str, Any]
+) -> WatermarkCheck:
+    """Refuse a signed map older than the newest one these engines have seen.
+
+    Raises :class:`~sde.errors.MapRolledBack`. Equal is allowed - restarting a process against the
+    same map is the ordinary case - and only strictly lower is refused.
+    """
+    if not placement.signed:
+        return WatermarkCheck(
+            protection="not_applicable",
+            map_version=placement.map_version,
+            highest_seen=None,
+            participating=(),
+            unable=tuple(sorted(engines)),
+            why=(
+                "this map is unsigned, so it is your own document rather than one we issued. "
+                "Replacing it with another is the no-account mode working as documented, and there "
+                "is no newest version for us to be the authority on."
+            ),
+        )
+
+    able, unable = _split(engines)
+    if not able:
+        check = WatermarkCheck(
+            protection="unavailable",
+            map_version=placement.map_version,
+            highest_seen=None,
+            participating=(),
+            unable=unable,
+            why=(
+                f"none of the engines in this map can keep bookkeeping ({list(unable)}), so a map "
+                f"that goes backwards cannot be recognised. An engine whose schema is fixed in its "
+                f"own source - ours is - has nowhere to put it. Nothing is wrong with your "
+                f"configuration; this protection simply does not exist for it."
+            ),
+        )
+        log(
+            "sde.map.rollback_unprotected",
+            map_version=placement.map_version,
+            engines=len(unable),
+        )
+        return check
+
+    seen = [store.map_watermark() for store in (engines[name] for name in able)]
+    known = [value for value in seen if value is not None]
+    highest = max(known) if known else None
+
+    if highest is not None and placement.map_version < highest:
+        raise MapRolledBack(
+            f"this map is version {placement.map_version} and version {highest} has already been "
+            f"applied against these engines. Refusing to go backwards: an older signed map "
+            f"verifies perfectly - that is what a signature is - so nothing else here would notice "
+            f"that the file was replaced, and the writes would go to the previous placement. If "
+            f"this is deliberate, because the newer map was wrong, clear the bookkeeping: "
+            f"DELETE FROM {WATERMARK_TABLE} WHERE map_version > {placement.map_version}; in "
+            f"{list(able)}, and on an engine that deletes asynchronously, let the deletion finish "
+            f"before restarting. That is a deliberate act with a stated consequence, which is why "
+            f"it is not a flag."
+        )
+
+    if highest is None or placement.map_version > highest:
+        # Written only when it moves. Recording every start would grow the table by one row per
+        # process restart, and the watermark would say nothing more than it does now.
+        for name in able:
+            store: WatermarkStore = engines[name]
+            store.record_map_version(
+                placement.map_version, model_version=placement.model_version
+            )
+
+    log(
+        "sde.map.forward_only",
+        map_version=placement.map_version,
+        highest_seen=highest,
+        engines=len(able),
+    )
+    return WatermarkCheck(
+        protection="enforced",
+        map_version=placement.map_version,
+        highest_seen=highest,
+        participating=able,
+        unable=unable,
+        why=(
+            f"the highest map version applied against these engines is "
+            f"{highest if highest is not None else placement.map_version}, kept in "
+            f"{WATERMARK_TABLE} in {list(able)}. A map older than that is refused."
+        ),
+    )