tina4-python 3.13.103__tar.gz → 3.13.105__tar.gz

{tina4_python-3.13.103 → tina4_python-3.13.105}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tina4-python
-Version: 3.13.103
+Version: 3.13.105
 Summary: Tina4 Python v3 — Zero-dependency, lightweight web framework
 Author-email: Andre van Zuydam <andrevanzuydam@gmail.com>
 License: MIT

{tina4_python-3.13.103 → tina4_python-3.13.105}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tina4-python"
-version = "3.13.103"
+version = "3.13.105"
 description = "Tina4 Python v3 — Zero-dependency, lightweight web framework"
 authors = [
     {name = "Andre van Zuydam", email = "andrevanzuydam@gmail.com"}

{tina4_python-3.13.103 → tina4_python-3.13.105}/tina4_python/__init__.py

@@ -51,7 +51,7 @@ def _resolve_version() -> str:
     #
     # test_version_constant.py now asserts this literal equals the pyproject
     # version, so the release bump cannot leave it behind again.
-    return "3.13.103"
+    return "3.13.105"
 
 
 __version__ = _resolve_version()
@@ -108,6 +108,9 @@ _LAZY: dict[str, tuple[str, str]] = {
     "NumericField": ("tina4_python.orm", "NumericField"),
     "DecimalField": ("tina4_python.orm", "DecimalField"),
     "JSONField": ("tina4_python.orm", "JSONField"),
+    "PointField": ("tina4_python.orm", "PointField"),
+    "Point": ("tina4_python.orm", "Point"),
+    "feature_collection": ("tina4_python.orm", "feature_collection"),
     "ForeignKeyField": ("tina4_python.orm", "ForeignKeyField"),
     "IntField": ("tina4_python.orm", "IntField"),
     "StrField": ("tina4_python.orm", "StrField"),
@@ -141,6 +144,10 @@ _LAZY: dict[str, tuple[str, str]] = {
     "AiHTTPError": ("tina4_python.ai", "AiHTTPError"),
     "AiTimeoutError": ("tina4_python.ai", "AiTimeoutError"),
     "AiParseError": ("tina4_python.ai", "AiParseError"),
+    # Provider-neutral OpenID Connect SSO (ADR-0056)
+    "Sso": ("tina4_python.sso", "Sso"),
+    "SSO": ("tina4_python.sso", "SSO"),
+    "SsoError": ("tina4_python.sso", "SsoError"),
     # SOAP / WSDL
     "WSDL": ("tina4_python.wsdl", "WSDL"),
     "wsdl_operation": ("tina4_python.wsdl", "wsdl_operation"),

{tina4_python-3.13.103 → tina4_python-3.13.105}/tina4_python/cli/__init__.py

@@ -825,13 +825,8 @@ def _seed(args):
 
 def _routes(args):
     """List all registered routes."""
-    if Path("app.py").exists():
-        sys.path.insert(0, str(Path.cwd()))
-        import importlib
-        importlib.import_module("app")
-
-    from tina4_python.core.router import Router
-    routes = Router.get_routes()
+    from tina4_python.core import discover_routes
+    routes = discover_routes("src/routes")
     if not routes:
         print("No routes registered.")
         return

{tina4_python-3.13.103 → tina4_python-3.13.105}/tina4_python/core/__init__.py

@@ -19,7 +19,7 @@ from tina4_python.core.router import (
 from tina4_python.core.middleware import CorsMiddleware, RateLimiter
 from tina4_python.core.cache import Cache
 from tina4_python.core.events import on, off, emit, emit_async, once, listeners, events, clear as clear_events
-from tina4_python.core.server import run, resolve_config, handle, start, stop
+from tina4_python.core.server import discover_routes, run, resolve_config, handle, start, stop
 
 __all__ = [
     "Request", "Response", "Router",
@@ -28,5 +28,5 @@ __all__ = [
     "CorsMiddleware", "RateLimiter",
     "Cache",
     "on", "off", "emit", "emit_async", "once", "listeners", "events", "clear_events",
-    "run", "resolve_config", "handle", "start", "stop",
+    "discover_routes", "run", "resolve_config", "handle", "start", "stop",
 ]

{tina4_python-3.13.103 → tina4_python-3.13.105}/tina4_python/core/router.py

@@ -817,9 +817,23 @@ def noauth():
     def decorator(fn):
         fn._noauth = True
         # If route was already registered (decorator applied after @get/@post),
-        # update the route dict directly.
+        # update the route dict directly AND log the corrected state. The
+        # documented decorator order puts @noauth() ABOVE @get/@post, which
+        # means Python's bottom-up application runs @post first — so
+        # `_register_route` fires its "auth=required" line for a route that
+        # will be public a microsecond later. Without the corrective line
+        # below, the earlier log reads as definitive and misleads anyone
+        # reading startup output (issue #103: an AI reviewer drafted a false
+        # critical-security finding after reading the misleading line).
         if hasattr(fn, "_route_ref"):
-            fn._route_ref._route["auth_required"] = False
+            route = fn._route_ref._route
+            was_required = route.get("auth_required", False)
+            route["auth_required"] = False
+            if was_required:
+                Log.debug(
+                    f"Route auth updated: {route['method']} {route['path']} "
+                    f"(auth=public via @noauth)"
+                )
         return fn
     return decorator
 
@@ -828,10 +842,19 @@ def secured():
     """Require auth on a GET route (which is public by default)."""
     def decorator(fn):
         fn._secured = True
-        # If route was already registered (decorator applied after @get/@post),
-        # update the route dict directly.
+        # See @noauth() above: emit a corrective log line if we flip the flag
+        # on an already-registered route so a reader of the startup log sees
+        # the true final auth state after every decorator has applied
+        # (issue #103).
         if hasattr(fn, "_route_ref"):
-            fn._route_ref._route["auth_required"] = True
+            route = fn._route_ref._route
+            was_public = not route.get("auth_required", True)
+            route["auth_required"] = True
+            if was_public:
+                Log.debug(
+                    f"Route auth updated: {route['method']} {route['path']} "
+                    f"(auth=required via @secured)"
+                )
         # Same for a WebSocket route registered by @websocket() below this one.
         if hasattr(fn, "_ws_route_ref"):
             fn._ws_route_ref["auth_required"] = True

{tina4_python-3.13.103 → tina4_python-3.13.105}/tina4_python/core/server.py

@@ -316,6 +316,79 @@ async def background_tick_loop(callback, interval: float, executor, shutdown):
 _discovered_mtimes: dict[str, float] = {}
 
 
+def _cascade_reload_dependents(reloaded: str, root_pkg: str, visited: set[str]) -> None:
+    """After re-importing ``reloaded``, re-import any other in-scope module that
+    still holds a stale ``from <reloaded> import Foo`` reference.
+
+    Fixes https://github.com/tina4stack/tina4-python/issues/102 (hot reload
+    does not re-register ORM field metadata). Root cause: ``_auto_discover``
+    reloads the CHANGED module (say ``src.orm.Todo``) by ``del sys.modules[.]``
+    + ``importlib.import_module(.)``, which builds a fresh class object. But a
+    route module that did ``from src.orm.Todo import Todo`` at ITS first import
+    captured a reference to the OLD class, and unless that module ALSO
+    re-executes, its ``Todo(...)`` call still uses the old class -- with the
+    old ``_fields`` -- so a newly added column is silently absent from
+    ``to_dict()`` output. The DATA is written to the DB correctly (the ORM
+    knows the field via the new class), and the API just lies about it.
+
+    Detection: for every in-scope module already in ``sys.modules``, walk its
+    namespace and look for any attribute whose ``__module__`` matches the
+    reloaded module's name. That's the fingerprint of a ``from X import Y``
+    binding into an unchanged file. Re-import that file so its ``from`` binds
+    to the fresh class. Recurse (a dependent may itself be depended on).
+
+    Bounded to the discovery scope (``root_pkg`` and its subpackages) so we
+    never delete a framework or third-party module. ``visited`` breaks cycles
+    and prevents re-doing a module we already refreshed in this cascade.
+    """
+    # Snapshot: mutating sys.modules during the walk would break iteration.
+    for other_name in list(sys.modules):
+        if other_name in visited:
+            continue
+        if other_name == reloaded:
+            continue
+        if other_name != root_pkg and not other_name.startswith(root_pkg + "."):
+            continue
+        other = sys.modules.get(other_name)
+        if other is None or not hasattr(other, "__dict__"):
+            continue
+        # Any attribute whose __module__ names the reloaded module is a
+        # ``from X import Y`` binding into this file -- it is stale.
+        try:
+            attrs = vars(other)
+        except Exception:
+            continue
+        stale = False
+        for attr_name, attr in attrs.items():
+            if attr_name.startswith("__"):
+                continue
+            if getattr(attr, "__module__", None) == reloaded:
+                stale = True
+                break
+        if not stale:
+            continue
+        try:
+            from tina4_python.core.router import Router
+            Router.remove_routes_for_module(other_name)
+            del sys.modules[other_name]
+            importlib.import_module(other_name)
+            # Record so the next mtime tick sees this reload as authoritative.
+            try:
+                other_path = getattr(sys.modules[other_name], "__file__", None)
+                if other_path:
+                    _discovered_mtimes[other_name] = Path(other_path).stat().st_mtime
+            except OSError:
+                pass
+            visited.add(other_name)
+            Log.info(f"Cascaded reload of dependent module: {other_name}")
+            # A module that imported from `reloaded` may itself be imported
+            # from by yet another module. Cascade the same detection on THIS
+            # module now that its class objects are fresh.
+            _cascade_reload_dependents(other_name, root_pkg, visited)
+        except Exception as exc:
+            Log.error(f"Cascade reload failed for {other_name}: {exc}")
+
+
 def _auto_discover(root_dir: str = "src"):
     """Auto-import all .py files in ``root_dir`` to trigger route decorators.
 
@@ -444,6 +517,14 @@ def _auto_discover(root_dir: str = "src"):
                         f"Reloaded changed module: {module_name}"
                         + (f" (dropped {dropped} stale route(s))" if dropped else "")
                     )
+                    # Cascade to any in-scope module that captured a
+                    # ``from <module_name> import Foo`` binding at ITS first
+                    # import -- that binding still points at the OLD class
+                    # object we just replaced, so the dependent silently uses
+                    # stale field metadata / stale globals until it too
+                    # re-executes. See _cascade_reload_dependents above and
+                    # issue #102.
+                    _cascade_reload_dependents(module_name, root_pkg, {module_name})
                 else:
                     # Out-of-scope module changed — record mtime so we don't
                     # keep re-evaluating it, but do not re-import it.
@@ -468,6 +549,13 @@ def _auto_discover(root_dir: str = "src"):
             pass
 
 
+def discover_routes(root_dir: str = "src/routes"):
+    """Discover application routes without booting the application server."""
+    _auto_discover(root_dir)
+    from tina4_python.core.router import Router
+    return Router.get_routes()
+
+
 def _record_broken_import(py_file: Path, error: Exception) -> None:
     """Write a .broken sentinel so /health and the dev dashboard surface
     auto-discover failures instead of burying them in the console."""
@@ -1691,8 +1779,16 @@ def _check_auth(request: Request, response: Response, route: dict) -> bool:
     if not _auth_ok:
         _session = getattr(request, "session", None)
         if _session:
+            # A provider-verified OIDC identity is handed into the SAME auth
+            # gate as JWT. Provider credentials stay in the reserved Session
+            # value and never enter request.user.
+            _sso = _session.get("_tina4_sso")
+            _sso_identity = _sso.get("identity") if isinstance(_sso, dict) else None
+            if isinstance(_sso_identity, dict) and _sso_identity.get("issuer") and _sso_identity.get("subject"):
+                _auth_ok = True
+                request.user = _sso_identity
             _session_token = _session.get("token") if _session else ""
-            if _session_token:
+            if not _auth_ok and _session_token:
                 try:
                     from tina4_python.auth import Auth
                     _payload = Auth.valid_token_static(_session_token)
@@ -3669,6 +3765,10 @@ def run(host: str | None = None, port: int | None = None, no_browser: bool = Fal
 
     # Auto-discover routes
     _auto_discover("src")
+    # Configuration-first OIDC: canonical routes appear only when configured,
+    # after app discovery so collisions fail loudly rather than overwrite.
+    from tina4_python.sso import Sso as _Sso
+    _Sso.mount_configured()
     route_count = len(Router.get_routes())
     Log.info(f"Discovered {route_count} routes")
 

{tina4_python-3.13.103 → tina4_python-3.13.105}/tina4_python/database/__init__.py

@@ -11,7 +11,11 @@ SQL-first database layer. One interface, many drivers.
     row = db.fetch_one("SELECT * FROM users WHERE id = ?", [42])
     db.execute("INSERT INTO users (name) VALUES (?)", ["Alice"])
 """
-from tina4_python.database.adapter import DatabaseAdapter, DatabaseResult, SQLTranslator
+from tina4_python.database.adapter import DatabaseAdapter, DatabaseResult
+from tina4_python.database.sql_translator import SQLTranslator, SpatialNotSupportedError
 from tina4_python.database.connection import Database
 
-__all__ = ["Database", "DatabaseAdapter", "DatabaseResult", "SQLTranslator"]
+__all__ = [
+    "Database", "DatabaseAdapter", "DatabaseResult", "SQLTranslator",
+    "SpatialNotSupportedError",
+]

{tina4_python-3.13.103 → tina4_python-3.13.105}/tina4_python/database/adapter.py

@@ -1131,9 +1131,10 @@ class SqlCrudMixin:
 # ── SQL Translation Rules ──────────────────────────────────────
 # Reusable translation functions for common cross-engine quirks.
 
-
 # SQLTranslator moved to sql_translator.py (feature 3: the adapter module is the
 # adapter contract and nothing else). Re-exported here because the sqlite,
 # firebird, mssql and odbc adapters import it from this module, and a file move
 # is not the place to churn their imports.
-from tina4_python.database.sql_translator import SQLTranslator  # noqa: E402,F401
+from tina4_python.database.sql_translator import (  # noqa: E402,F401
+    SQLTranslator, SpatialNotSupportedError,
+)

{tina4_python-3.13.103 → tina4_python-3.13.105}/tina4_python/database/sql_translator.py

@@ -16,6 +16,10 @@ by engine; moving it here would flatten that override.
 import re
 
 
+class SpatialNotSupportedError(NotImplementedError):
+    """The selected database engine cannot honor the GIS contract."""
+
+
 class SQLTranslator:
     """Cross-engine SQL translator.
 
@@ -23,6 +27,124 @@ class SQLTranslator:
     and stateless — just string transforms.
     """
 
+    SPATIAL_ENGINES = ("postgres", "postgresql")
+    _IDENTIFIER = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$")
+
+    @classmethod
+    def supports_spatial(cls, engine: str) -> bool:
+        """Return whether Tina4 has a spatial provider for ``engine``."""
+        name = (engine or "").lower()
+        name = cls.ENGINE_ALIASES.get(name, name)
+        return name in cls.SPATIAL_ENGINES
+
+    @classmethod
+    def require_spatial(cls, engine: str, feature: str) -> str:
+        """Return the normalized spatial engine or fail with an actionable error."""
+        name = (engine or "unknown").lower()
+        name = cls.ENGINE_ALIASES.get(name, name)
+        if cls.supports_spatial(name):
+            return name
+        raise SpatialNotSupportedError(
+            f"{feature} is not supported on the '{name}' database engine. "
+            "Tina4 GIS support is PostGIS-first: use PostgreSQL with the "
+            "PostGIS extension (CREATE EXTENSION postgis). Tina4 will not "
+            "replace a spatial query with an approximate latitude/longitude query. "
+            "If the application needs storage only and no GIS behavior, declare "
+            "separate longitude and latitude FloatField columns instead."
+        )
+
+    @classmethod
+    def identifier(cls, name: str, what: str = "column") -> str:
+        """Validate an identifier before placing it in spatial SQL."""
+        if not isinstance(name, str) or not cls._IDENTIFIER.fullmatch(name):
+            raise ValueError(
+                f"Spatial {what} name {name!r} is not a valid SQL identifier"
+            )
+        return name
+
+    @staticmethod
+    def _srid(srid) -> int:
+        """Coerce the interpolated SRID to an integer."""
+        if isinstance(srid, bool):
+            raise ValueError(f"Spatial SRID must be an integer, got {srid!r}")
+        try:
+            value = int(srid)
+        except (TypeError, ValueError) as error:
+            raise ValueError(f"Spatial SRID must be an integer, got {srid!r}") from error
+        if value <= 0:
+            raise ValueError(f"Spatial SRID must be positive, got {value}")
+        return value
+
+    @classmethod
+    def point_column_type(cls, engine: str, srid: int = 4326) -> str:
+        """Return PostGIS geography Point DDL."""
+        cls.require_spatial(engine, "PointField")
+        return f"geography(Point,{cls._srid(srid)})"
+
+    @classmethod
+    def spatial_index(cls, engine: str, table: str, column: str) -> str:
+        """Return idempotent PostGIS GiST-index DDL."""
+        cls.require_spatial(engine, "spatial index creation")
+        table = cls.identifier(table, "table")
+        column = cls.identifier(column)
+        index = f"{table.replace('.', '_')}_{column}_gist"
+        return f"CREATE INDEX IF NOT EXISTS {index} ON {table} USING GIST ({column})"
+
+    @classmethod
+    def point_literal(cls, engine: str, srid: int = 4326) -> str:
+        """Return a bound PostGIS point expression in longitude/latitude order."""
+        cls.require_spatial(engine, "spatial predicates")
+        return f"ST_SetSRID(ST_MakePoint(?, ?), {cls._srid(srid)})::geography"
+
+    @classmethod
+    def within_distance(cls, engine: str, column: str, srid: int = 4326) -> str:
+        """Return a bound radius predicate whose distance uses metres."""
+        cls.require_spatial(engine, "within_distance()")
+        column = cls.identifier(column)
+        return f"ST_DWithin({column}, {cls.point_literal(engine, srid)}, ?)"
+
+    @classmethod
+    def distance(cls, engine: str, column: str, srid: int = 4326) -> str:
+        """Return a bound spheroid-distance expression in metres."""
+        cls.require_spatial(engine, "order_by_distance()")
+        column = cls.identifier(column)
+        return f"ST_Distance({column}, {cls.point_literal(engine, srid)})"
+
+    @classmethod
+    def distance_as(cls, engine: str, column: str, alias: str, srid: int = 4326) -> str:
+        """Return an aliased bound distance expression for a SELECT list."""
+        alias = cls.identifier(alias, "result alias")
+        return f"{cls.distance(engine, column, srid)} AS {alias}"
+
+    @classmethod
+    def geometry_literal(cls, engine: str, form: str = "ewkt", srid: int = 4326) -> str:
+        """Return a one-parameter PostGIS geometry expression."""
+        cls.require_spatial(engine, "spatial predicates")
+        if form == "ewkt":
+            return "ST_GeogFromText(?)"
+        if form == "geojson":
+            return f"ST_SetSRID(ST_GeomFromGeoJSON(?), {cls._srid(srid)})::geography"
+        raise ValueError(
+            f"Spatial geometry form {form!r} is not supported; use 'ewkt' or 'geojson'"
+        )
+
+    @classmethod
+    def intersects(cls, engine: str, column: str, form: str = "ewkt",
+                   srid: int = 4326) -> str:
+        """Return a bound PostGIS intersection predicate."""
+        column = cls.identifier(column)
+        return f"ST_Intersects({column}, {cls.geometry_literal(engine, form, srid)})"
+
+    @classmethod
+    def bbox(cls, engine: str, column: str, srid: int = 4326) -> str:
+        """Return a bound PostGIS bounding-box predicate."""
+        cls.require_spatial(engine, "bbox()")
+        column = cls.identifier(column)
+        return (
+            f"ST_Intersects({column}, "
+            f"ST_MakeEnvelope(?, ?, ?, ?, {cls._srid(srid)})::geography)"
+        )
+
     @staticmethod
     def limit_to_rows(sql: str) -> str:
         """Convert LIMIT/OFFSET to Firebird ROWS...TO syntax.

{tina4_python-3.13.103 → tina4_python-3.13.105}/tina4_python/orm/__init__.py

@@ -20,11 +20,12 @@ from tina4_python.orm.fields import (
     Field,
     IntegerField, StringField, BooleanField, FloatField,
     DateTimeField, TextField, BlobField, NumericField, DecimalField, JSONField,
-    ForeignKeyField,
+    PointField, ForeignKeyField,
     IntField, StrField, BoolField,  # short aliases
     has_many, has_one, belongs_to,  # relationship descriptors
 )
-from tina4_python.orm.model import ORM, bind_database
+from tina4_python.orm.point import Point
+from tina4_python.orm.model import ORM, bind_database, feature_collection
 
 __all__ = [
     "ORM", "bind_database",
@@ -32,9 +33,11 @@ __all__ = [
     # Verbose (preferred)
     "IntegerField", "StringField", "BooleanField", "FloatField",
     "DateTimeField", "TextField", "BlobField", "NumericField", "DecimalField", "JSONField",
-    "ForeignKeyField",
+    "PointField", "ForeignKeyField",
     # Short aliases (backwards compat)
     "IntField", "StrField", "BoolField",
     # Relationships
     "has_many", "has_one", "belongs_to",
+    # Spatial
+    "Point", "feature_collection",
 ]

{tina4_python-3.13.103 → tina4_python-3.13.105}/tina4_python/orm/fields.py

@@ -422,6 +422,131 @@ class JSONField(Field):
             raise ValueError(f"Field '{self.name}': value is not JSON-serializable") from e
 
 
+class PointField(Field):
+    """A column that stores a single geographic point, SRID-aware.
+
+    You work with a :class:`~tina4_python.orm.point.Point` value object; the ORM
+    writes EWKT on save and parses the engine's (HEX)EWKB back into a ``Point``
+    on load, so ``model.location.lat`` always works regardless of engine wire
+    format.
+
+    Assignment accepts any of these and normalises to ``Point``::
+
+        site.location = (18.4241, -33.9249)                            # (lon, lat) tuple
+        site.location = "POINT(18.4241 -33.9249)"                       # WKT
+        site.location = "SRID=4326;POINT(18.4241 -33.9249)"             # EWKT
+        site.location = {"type": "Point", "coordinates": [18.42, -33.9]}  # GeoJSON
+
+    Reading it back gives the value object::
+
+        site.location.lon       # 18.4241
+        site.location.lat       # -33.9249
+        site.location.wkt       # 'POINT(18.4241 -33.9249)'
+        site.location.geojson   # {'type': 'Point', 'coordinates': [18.4241, -33.9249]}
+
+    ``to_dict()`` / ``to_json()`` / ``response()`` emit the GeoJSON form, so a
+    map front end consumes a Tina4 route with no translation layer.
+
+    **Engine support is PostGIS-first and never silently wrong.** The column DDL
+    is ``geography(Point,<srid>)`` on PostgreSQL, and
+    :meth:`~tina4_python.orm.model.ORM.create_table` also creates a GiST index
+    for it. On any engine without spatial support, ``create_table()`` raises
+    :class:`~tina4_python.database.adapter.SpatialNotSupportedError` naming that
+    engine rather than creating a wrong column type.
+
+    Usage::
+
+        class ChargePoint(ORM):
+            id       = IntegerField(primary_key=True, auto_increment=True)
+            name     = StringField()
+            location = PointField()          # geography(Point,4326) + GiST index
+
+        ChargePoint({"name": "V&A", "location": (18.4241, -33.9249)}).save()
+
+        near = ChargePoint.query() \\
+            .within_distance("location", (18.42, -33.92), 5000) \\
+            .order_by_distance("location", (18.42, -33.92)) \\
+            .get()
+
+    Args:
+        srid: Spatial reference id for the column. Defaults to 4326 (WGS 84).
+        spatial_index: Create the engine's spatial index for this column in
+            ``create_table()``. Defaults to True — a radius query without one
+            is a full table scan.
+    """
+
+    def __init__(self, srid: int = None, spatial_index: bool = True, **kwargs):
+        from tina4_python.orm.point import DEFAULT_SRID, Point
+        super().__init__(Point, **kwargs)
+        self.kind = "PointField"
+        self.srid = DEFAULT_SRID if srid is None else int(srid)
+        self.spatial_index = spatial_index
+
+    def _resolve_default(self):
+        # ORM.__init__ seeds attributes straight from _resolve_default (it does
+        # not route through validate), so coerce here too — otherwise a
+        # ``default=(lon, lat)`` would leave ``model.location`` as a raw tuple on
+        # an unsaved instance and ``.lat`` would fail.
+        from tina4_python.orm.point import Point
+
+        default = super()._resolve_default()
+        if default is None:
+            return default
+        return self._parse_point(default)
+
+    def _parse_point(self, value):
+        from tina4_python.orm.point import Point
+
+        try:
+            point = Point.parse(value, self.srid)
+        except ValueError as e:
+            raise ValueError(f"Field '{self.name}': {e}") from e
+        if point.srid != self.srid:
+            raise ValueError(
+                f"Field '{self.name}' expects SRID {self.srid}; received {point.srid}. "
+                "Tina4 never silently reprojects or restamps spatial data."
+            )
+        return point
+
+    def coerce(self, value):
+        """Hydrate/assign through the Point parser, not ``Point(value)``."""
+        return None if value is None else self._parse_point(value)
+
+    def validate(self, value):
+        """Coerce any supported point representation into a ``Point``.
+
+        Runs on BOTH the write path (tuple / WKT / GeoJSON from a route) and the
+        read path (the engine's HEXEWKB), which is what makes the column
+        round-trip identically no matter how it was assigned.
+        """
+        from tina4_python.orm.point import Point
+
+        if value is None:
+            if self.required and self.default is None:
+                raise ValueError(f"Field '{self.name}' is required")
+            default = self._resolve_default()
+            return None if default is None else Point.parse(default, self.srid)
+
+        point = self._parse_point(value)
+
+        if self.validator is not None:
+            self.validator(point)
+        return point
+
+    def to_db(self, value):
+        """Serialise to EWKT — ``SRID=4326;POINT(lon lat)``.
+
+        EWKT carries the SRID with the geometry, so the engine never has to
+        assume one, and it is accepted verbatim by PostGIS geography input. The
+        value is bound as a normal parameter; it is never formatted into SQL.
+        """
+        from tina4_python.orm.point import Point
+
+        if value is None:
+            return None
+        return self._parse_point(value).ewkt
+
+
 class ForeignKeyField(Field):
     """Integer field that references another model's primary key.