Skip to content

Derive the lattice's type membership from the source #104

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
estebanzimanyi merged 1 commit into from
Aug 31, 2026
Merged

Derive the lattice's type membership from the source #104

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 6 additions & 87 deletions meta/object-model.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,28 +84,6 @@
"prefixes": [
"temporal"
],
"temptypes": [
"T_TBOOL",
"T_TTEXT",
"T_TJSONB",
"T_TINT",
"T_TBIGINT",
"T_TFLOAT",
"T_TGEOMPOINT",
"T_TGEOGPOINT",
"T_TGEOMETRY",
"T_TGEOGRAPHY",
"T_TCBUFFER",
"T_TNPOINT",
"T_TPOSE",
"T_TPOSECHAIN",
"T_TRGEOMETRY",
"T_TH3INDEX",
"T_TQUADBIN",
"T_TS2CELL",
"T_TPCPOINT",
"T_TPCPATCH"
],
"doc": "Superclass of every temporal type; temporal_* functions are late-bound over `subtype` and `temptype`."
},
"TAlpha": {
Expand All @@ -115,11 +93,6 @@
"prefixes": [
"talpha"
],
"temptypes": [
"T_TBOOL",
"T_TTEXT",
"T_TJSONB"
],
"doc": "Non-numeric, non-spatial temporal types (step/discrete interpolation only). A real MEOS grouping (talpha_type) with no user-facing class name in PyMEOS — see corrections."
},
"TBool": {
Expand All @@ -131,8 +104,7 @@
],
"temptypes": [
"T_TBOOL"
],
"cBaseType": "T_BOOL"
]
},
"TText": {
"kind": "leaf",
Expand All @@ -143,8 +115,7 @@
],
"temptypes": [
"T_TTEXT"
],
"cBaseType": "T_TEXT"
]
},
"TJsonb": {
"kind": "leaf",
Expand All @@ -155,8 +126,7 @@
],
"temptypes": [
"T_TJSONB"
],
"cBaseType": "T_JSONB"
]
},
"TNumber": {
"kind": "abstract",
Expand All @@ -165,11 +135,6 @@
"prefixes": [
"tnumber"
],
"temptypes": [
"T_TINT",
"T_TBIGINT",
"T_TFLOAT"
],
"basePredicate": "tnumber_basetype",
"doc": "Temporal numbers; supports linear interpolation."
},
Expand All @@ -182,8 +147,7 @@
],
"temptypes": [
"T_TINT"
],
"cBaseType": "T_INT4"
]
},
"TBigint": {
"kind": "leaf",
Expand All @@ -194,8 +158,7 @@
],
"temptypes": [
"T_TBIGINT"
],
"cBaseType": "T_INT8"
]
},
"TFloat": {
"kind": "leaf",
Expand All @@ -206,8 +169,7 @@
],
"temptypes": [
"T_TFLOAT"
],
"cBaseType": "T_FLOAT8"
]
},
"TSpatial": {
"kind": "abstract",
Expand All @@ -216,22 +178,6 @@
"prefixes": [
"tspatial"
],
"temptypes": [
"T_TGEOMPOINT",
"T_TGEOGPOINT",
"T_TGEOMETRY",
"T_TGEOGRAPHY",
"T_TCBUFFER",
"T_TNPOINT",
"T_TPOSE",
"T_TPOSECHAIN",
"T_TRGEOMETRY",
"T_TH3INDEX",
"T_TQUADBIN",
"T_TS2CELL",
"T_TPCPOINT",
"T_TPCPATCH"
],
"doc": "Temporal types carrying an STBox spatial bounding box."
},
"TGeo": {
Expand All @@ -243,12 +189,6 @@
"tgeo"
],
"userFacingName": "TGeo",
"temptypes": [
"T_TGEOMETRY",
"T_TGEOGRAPHY",
"T_TGEOMPOINT",
"T_TGEOGPOINT"
],
"doc": "All PostGIS-derived spatiotemporal types (geometry/geography-based). Authoritative parent per MobilityDB manual Ch.7 Figure 7.1 (= the broad C predicate tgeo_type_all). NOTE: the narrower C predicate tgeo_type() and most tgeo_* functions reject points — class membership (manual) is broader than tgeo_* API applicability; see correction OM-M1."
},
"TPoint": {
Expand All @@ -259,10 +199,6 @@
"tpoint"
],
"userFacingName": "TPoint",
"temptypes": [
"T_TGEOMPOINT",
"T_TGEOGPOINT"
],
"doc": "Temporal points. API-level intermediate (C predicate tpoint_type + the tpoint_* method family); NOT drawn in the manual Figure 7.1 (a conceptual diagram) but required so the tpoint_* methods bind to a class — see correction OM-M6."
},
"TGeomPoint": {
Expand All @@ -276,7 +212,6 @@
"temptypes": [
"T_TGEOMPOINT"
],
"cBaseType": "T_GEOMETRY",
"traits": [
"geometryBased"
]
Expand All @@ -292,7 +227,6 @@
"temptypes": [
"T_TGEOGPOINT"
],
"cBaseType": "T_GEOGRAPHY",
"traits": [
"geodetic"
]
Expand All @@ -308,7 +242,6 @@
"temptypes": [
"T_TGEOMETRY"
],
"cBaseType": "T_GEOMETRY",
"traits": [
"geometryBased"
]
Expand All @@ -324,7 +257,6 @@
"temptypes": [
"T_TGEOGRAPHY"
],
"cBaseType": "T_GEOGRAPHY",
"traits": [
"geodetic"
]
Expand All @@ -340,7 +272,6 @@
"temptypes": [
"T_TCBUFFER"
],
"cBaseType": "T_CBUFFER",
"conditional": "CBUFFER"
},
"TNpoint": {
Expand All @@ -354,7 +285,6 @@
"temptypes": [
"T_TNPOINT"
],
"cBaseType": "T_NPOINT",
"conditional": "NPOINT"
},
"TPose": {
Expand All @@ -368,7 +298,6 @@
"temptypes": [
"T_TPOSE"
],
"cBaseType": "T_POSE",
"conditional": "POSE"
},
"TRGeometry": {
Expand All @@ -384,7 +313,6 @@
"temptypes": [
"T_TRGEOMETRY"
],
"cBaseType": "T_POSE",
"conditional": "RGEO",
"note": "Base type is T_POSE, not a geometry — base != name (see corrections). User-facing API name is `trgeometry`; internal C functions keep the `trgeo_` prefix and must NOT be normalized."
}
Expand All @@ -393,19 +321,10 @@
"_comment": "Orthogonal boolean axes — NOT inheritance parents (modelling them as parents would create a diamond TGeomPoint<-{TPoint,TGeometryBased}). Tagged on leaves; each backed by a MEOS predicate, gated against source.",
"geometryBased": {
"predicate": "tgeometry_type",
"temptypes": [
"T_TGEOMPOINT",
"T_TGEOMETRY"
],
"doc": "Cartesian (planar) base — geometry."
},
"geodetic": {
"predicate": "tgeodetic_type",
"temptypes": [
"T_TGEOGPOINT",
"T_TGEOGRAPHY",
"T_TH3INDEX"
],
"doc": "Ellipsoidal base — geography; also the H3 DGGS cells (geodetic, SRID 4326)."
}
},
Expand Down
98 changes: 96 additions & 2 deletions parser/object_model.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ class is invented; a function with no prefix match is recorded honestly as
import re
from pathlib import Path

from parser.typerelations import locate_catalog, temptype_basetypes


def find_mobilitydb_src(headers_dir: Path | None = None) -> Path | None:
"""Resolve the MobilityDB C source root for the error scan / drift gate.
Expand Down Expand Up @@ -298,15 +300,106 @@ def _scan_errors(src_root: Path, public: set) -> dict:
return result


class MembershipUnavailable(RuntimeError):
"""The source states a membership the lattice cannot use.

Raised where ``meos_catalog.c`` IS readable and disagrees with the model —
a predicate the model names that MEOS does not declare, a predicate
admitting nothing, a leaf modelling a type the relation catalog does not
relate. Each is a real disagreement, never a missing file: an unreachable
source is reported as ``membership.status`` instead, the way the error
contract reports one.
"""


_PREDICATE_TEMPTYPE_RE = re.compile(r"\bT_T[A-Z0-9_]+\b")

#: The tdoubleN types exist for temporal aggregation and are not part of the
#: published model, so a predicate admitting them contributes the rest.
_INTERNAL_TEMPTYPES = frozenset({"T_TDOUBLE2", "T_TDOUBLE3", "T_TDOUBLE4"})


def _predicate_body(cat_src: str, name: str) -> str:
"""The body of the ``name(MeosType ...)`` membership predicate."""
m = re.search(r"\n" + re.escape(name) + r"\(MeosType \w+\)\s*", cat_src)
if not m:
raise MembershipUnavailable(
f"meos_catalog.c declares no `{name}` predicate — the lattice names "
"a membership oracle MEOS does not have")
i = cat_src.index("{", m.end())
depth, j = 0, i
while j < len(cat_src):
depth += (cat_src[j] == "{") - (cat_src[j] == "}")
if depth == 0:
return cat_src[i:j + 1]
j += 1
return cat_src[i:]


def predicate_temptypes(cat_src: str, name: str) -> list:
"""The temporal types a membership predicate admits, in MeosType order."""
seen, out = set(), []
for t in _PREDICATE_TEMPTYPE_RE.findall(_predicate_body(cat_src, name)):
if t not in _INTERNAL_TEMPTYPES and t not in seen:
seen.add(t)
out.append(t)
if not out:
raise MembershipUnavailable(f"`{name}` admits no temporal type")
return out


def derive_membership(nodes: dict, cat_src: str, basetypes: dict) -> None:
"""Fill each node's membership from the catalog, in place.

A node naming a `predicate` takes the types that predicate admits; a leaf
takes the base type ``MEOS_RELTYPE_CATALOG`` gives the one type it models.
Neither is stated in the model file: both are MEOS's to say, and a copy of
either is a second source that goes stale the next time MEOS gains a type.
"""
for name, spec in nodes.items():
pred = spec.get("predicate")
if pred:
spec["temptypes"] = predicate_temptypes(cat_src, pred)
temptypes = spec.get("temptypes")
if spec.get("kind") == "leaf" and temptypes:
temptype = temptypes[0]
if temptype not in basetypes:
raise MembershipUnavailable(
f"{name} models {temptype}, which the relation catalog "
"gives no base type")
spec["cBaseType"] = basetypes[temptype]


def attach_object_model(idl: dict, path: Path,
mobilitydb_src: Path | None = None) -> dict:
"""Attach ``idl["objectModel"]`` from the canonical lattice file."""
if not Path(path).exists():
return idl
model = json.loads(Path(path).read_text())

lat = _tree({k: v for k, v in model["lattice"].items()
if not k.startswith("_")})
# The lattice's type membership is MEOS's to state, so it is read from
# meos_catalog.c at each parse rather than carried in the model file. A
# class the model names gains the types its predicate admits, and a leaf the
# base type the relation catalog gives it, so a type MEOS adds reaches the
# published model with no edit here.
catalog = locate_catalog(mobilitydb_src)
lattice_nodes = {k: v for k, v in model["lattice"].items()
if not k.startswith("_")}
trait_nodes = {k: v for k, v in model["traits"].items()
if not k.startswith("_")}
if catalog is not None:
cat_src = catalog.read_text(errors="ignore")
basetypes = temptype_basetypes(cat_src)
derive_membership(lattice_nodes, cat_src, basetypes)
derive_membership(trait_nodes, cat_src, basetypes)
membership = {"status": "derived", "source": str(catalog)}
else:
# Say so rather than publish an empty membership: a class naming no
# type would be indistinguishable from one MEOS has no type for. The
# error contract answers an unreachable source the same way.
membership = {"status": "source-unavailable", "source": None}

lat = _tree(lattice_nodes)
for fam in ("Box", "Collection"):
_tree({k: v for k, v in model["companions"][fam]["nodes"].items()
if not k.startswith("_")})
Expand Down Expand Up @@ -376,6 +469,7 @@ def attach_object_model(idl: dict, path: Path,
idl["objectModel"] = {
"provenance": model["provenance"],
"axes": model["axes"],
"membership": membership,
"lattice": lat,
"traits": model["traits"],
"companions": model["companions"],
Expand Down
4 changes: 2 additions & 2 deletions parser/typerelations.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ def temptype_basetypes(cat_src: str) -> dict:
if "temptype_basetype" in fields}


def _locate_catalog(src_root: Path | None) -> Path | None:
def locate_catalog(src_root: Path | None) -> Path | None:
"""The ``meos_catalog.c`` path from the resolved source root, or the ``MDB_SRC_ROOT`` checkout.

The object-model resolver returns the ``meos/src`` directory when it can, but on the
Expand Down Expand Up @@ -95,7 +95,7 @@ def attach_type_relations(idl: dict, src_root: Path | None) -> dict:
registry: the consumers read the registry to resolve a concrete collection
type, so an empty one silently degrades every one of them.
"""
catalog = _locate_catalog(src_root)
catalog = locate_catalog(src_root)
if catalog is None:
return idl

Expand Down
Loading
Loading