MobilityDB · estebanzimanyi · May 20, 2026
diff --git a/Makefile b/Makefile
@@ -0,0 +1,62 @@
+# MobilityAPI build & vendoring targets
+
+MEOS_API_REPO   ?= https://github.com/MobilityDB/MEOS-API
+MEOS_API_REF    ?= master
+MEOS_API_PR5    ?= refs/pull/5/head       # MEOS-API PR #5 (OpenAPI projection)
+MEOS_API_PR4    ?= refs/pull/4/head       # MEOS-API PR #4 (enrichment)
+MOBILITYDB_REPO ?= https://github.com/MobilityDB/MobilityDB
+MOBILITYDB_REF  ?= master
+VENDOR_DIR      := vendor/meos-api
+
+.PHONY: vendor-meos-api vendor-meos-api-from-prs
+
+# Regenerate vendored MEOS-API artefacts from MEOS-API + MobilityDB headers.
+#
+# `output/*.json` is .gitignore'd in MEOS-API (generated by `python3 run.py
+# <path-to-meos-include>`), so we have to:
+#   1. clone MEOS-API at the requested ref,
+#   2. clone MobilityDB at the requested ref so MEOS-API's parser can read its
+#      headers (`meos/include/`),
+#   3. install libclang,
+#   4. run `python3 run.py <MobilityDB-headers-path>` to produce output/*.json,
+#   5. copy the JSON artefacts into $(VENDOR_DIR).
+vendor-meos-api:
+	@echo "[vendor] regenerating meos-api artefacts from"
+	@echo "          MEOS-API:   $(MEOS_API_REPO)@$(MEOS_API_REF)"
+	@echo "          MobilityDB: $(MOBILITYDB_REPO)@$(MOBILITYDB_REF) (headers source)"
+	@mkdir -p $(VENDOR_DIR)
+	@tmpdir=$$(mktemp -d) && \
+	  git clone --depth 1 --branch $(MEOS_API_REF)   $(MEOS_API_REPO)   $$tmpdir/meos-api && \
+	  git clone --depth 1 --branch $(MOBILITYDB_REF) $(MOBILITYDB_REPO) $$tmpdir/mobilitydb && \
+	  cd $$tmpdir/meos-api && \
+	  pip install --quiet --user -r requirements.txt && \
+	  python3 run.py $$tmpdir/mobilitydb/meos/include && \
+	  if [ -f report.py ]; then python3 report.py $$tmpdir/mobilitydb/meos/include || true; fi && \
+	  if [ -f object_model_parity.py ]; then python3 object_model_parity.py || true; fi && \
+	  cp -v output/meos-idl.json                 $(CURDIR)/$(VENDOR_DIR)/ && \
+	  ( [ -f output/meos-coverage.json ]            && cp -v output/meos-coverage.json            $(CURDIR)/$(VENDOR_DIR)/ || true ) && \
+	  ( [ -f output/meos-object-model-parity.json ] && cp -v output/meos-object-model-parity.json $(CURDIR)/$(VENDOR_DIR)/ || true ) && \
+	  cd $(CURDIR) && rm -rf $$tmpdir
+	@echo "[vendor] done — $(VENDOR_DIR) refreshed"
+
+# Fetch the enriched catalog + OpenAPI projection from the open PR branches
+# (PR #4 ships parser/enrich.py, PR #5 ships generate_openapi.py).
+vendor-meos-api-from-prs:
+	@echo "[vendor] fetching from open PR branches (#4 enrichment + #5 OpenAPI)"
+	@mkdir -p $(VENDOR_DIR)
+	@tmpdir=$$(mktemp -d) && \
+	  git clone $(MEOS_API_REPO) $$tmpdir/meos-api && \
+	  git clone --depth 1 --branch $(MOBILITYDB_REF) $(MOBILITYDB_REPO) $$tmpdir/mobilitydb && \
+	  cd $$tmpdir/meos-api && \
+	  git fetch origin $(MEOS_API_PR4):pr4 $(MEOS_API_PR5):pr5 && \
+	  git checkout pr5 && \
+	  git merge --no-edit pr4 || true && \
+	  pip install --quiet --user -r requirements.txt && \
+	  python3 run.py $$tmpdir/mobilitydb/meos/include && \
+	  python3 generate_openapi.py && \
+	  cp -v output/meos-idl.json                 $(CURDIR)/$(VENDOR_DIR)/ && \
+	  ( [ -f output/meos-coverage.json ]            && cp -v output/meos-coverage.json            $(CURDIR)/$(VENDOR_DIR)/ || true ) && \
+	  ( [ -f output/meos-object-model-parity.json ] && cp -v output/meos-object-model-parity.json $(CURDIR)/$(VENDOR_DIR)/ || true ) && \
+	  ( [ -f output/meos-openapi.json ]             && cp -v output/meos-openapi.json             $(CURDIR)/$(VENDOR_DIR)/ || true ) && \
+	  cd $(CURDIR) && rm -rf $$tmpdir
+	@echo "[vendor] done — $(VENDOR_DIR) refreshed from PRs #4 + #5"
diff --git a/vendor/meos-api/PROVENANCE.json b/vendor/meos-api/PROVENANCE.json
@@ -0,0 +1,43 @@
+{
+  "$comment": "Vendored MEOS-API artefacts. Sources, regenerate with `make vendor-meos-api`.",
+  "fetched_at": "2026-05-20",
+  "artefacts": {
+    "meos-idl.json": {
+      "source_repo": "MobilityDB/MEOS-API",
+      "source_branch": "master",
+      "source_path": "output/meos-idl.json (generated, not committed)",
+      "regenerate": "python3 run.py <path-to-MobilityDB/meos/include>",
+      "describes": "MEOS catalog: 3546 functions, 70 structs, 16 enums (simple parse over MobilityDB master headers). Enriched form (with `network`/`wire`/`api` fields) is delivered by open PR #4; once that PR's content reaches master, this artefact picks up the enriched form via the standard `make vendor-meos-api` fetch."
+    },
+    "meos-coverage.json": {
+      "source_repo": "MobilityDB/MEOS-API",
+      "source_branch": "feat/service-enrichment (PR #4) — `report.py` is not yet on master",
+      "source_path": "output/meos-coverage.json (generated, not committed)",
+      "regenerate": "python3 report.py <path-to-MobilityDB/meos/include>",
+      "describes": "Structural worklist of non-exposable functions, ranked by `byClass`.",
+      "status": "FROM_OPEN_PR4"
+    },
+    "meos-object-model-parity.json": {
+      "source_repo": "MobilityDB/MEOS-API",
+      "source_branch": "feat/object-model (PR #10) — `object_model_parity.py` is not yet on master",
+      "source_path": "output/meos-object-model-parity.json (generated, not committed)",
+      "regenerate": "python3 object_model_parity.py",
+      "describes": "Object-model dispatch / portable bare-name parity (29-pair contract verbatim).",
+      "status": "FROM_OPEN_PR10"
+    },
+    "meos-openapi.json": {
+      "source_repo": "MobilityDB/MEOS-API",
+      "source_branch": "feat/openapi (PR #5)",
+      "source_path": "output/meos-openapi.json (regenerated; not committed on the PR branch)",
+      "regenerate": "python3 generate_openapi.py",
+      "describes": "OpenAPI 3.1 projection: 1790 operations over 14 component schemas, every path a single POST with `x-meos-*` extensions. NOT YET vendored here — open PR #5's generator requires the enriched catalog from open PR #4. When both land on master, this artefact appears.",
+      "status": "PENDING_PR4_PLUS_PR5"
+    },
+    "meos-movfeat-openapi.json": {
+      "source_repo": "MobilityDB/MEOS-API",
+      "source_branch": "MISSING — natural follow-up named in PR #5's body",
+      "describes": "OGC API – Moving Features OpenAPI projection. The immediate dependency for MobilityAPI per `docs/MEOS_API_INGESTION_PLAN.md`.",
+      "status": "MISSING_UPSTREAM"
+    }
+  }
+}
diff --git a/vendor/meos-api/README.md b/vendor/meos-api/README.md
@@ -0,0 +1,48 @@
+# Vendored MEOS-API artefacts
+
+This directory contains snapshots of the published catalog and projections
+from [`MobilityDB/MEOS-API`](https://github.com/MobilityDB/MEOS-API).
+MobilityAPI's [`docs/MEOS_API_INGESTION_PLAN.md`](../../docs/MEOS_API_INGESTION_PLAN.md)
+describes how these artefacts drive the ingestion pipeline; this file
+documents which artefact is fresh from where.
+
+## Refresh
+
+```bash
+# Current state — copies from MEOS-API master:
+make vendor-meos-api
+
+# Once the open PR branches land — pulls from PR #4 + PR #5 and regenerates:
+make vendor-meos-api-from-prs
+```
+
+The `Makefile` targets are idempotent; commit the resulting JSON files
+verbatim so a downstream contributor doesn't need libclang installed to
+run MobilityAPI.
+
+## What lives here today
+
+| File | Source | Size | Describes |
+|---|---|---:|---|
+| `meos-idl.json` | MEOS-API master, `output/` | ~1.2 MB | Catalog: 2699 functions, 47 structs, 6 enums (**simple parse**; enrichment via PR #4 not yet on master) |
+| `meos-coverage.json` | MEOS-API master, `output/` | ~37 KB | Worklist of non-exposable functions ranked by class |
+| `meos-object-model-parity.json` | MEOS-API master, `output/` | ~13 KB | 29-pair portable-bare-name parity (object-model dispatch) |
+| **`PROVENANCE.json`** | this file's companion | ~2 KB | Machine-readable source map + status of pending artefacts |
+
+## What's NOT here yet (pending upstream)
+
+| File | Pending | Why |
+|---|---|---|
+| `meos-idl.json` (enriched form, with `network` / `wire` / `api` fields) | MEOS-API PR #4 | The enrichment pass adds the projectability metadata MobilityAPI's dispatcher layer needs. Once #4's content reaches master, `make vendor-meos-api` picks it up automatically. |
+| `meos-openapi.json` | MEOS-API PR #5 | OpenAPI 3.1 projection: 1790 operations + `x-meos-*` extensions. Consumed by MobilityAPI's dispatcher generator (step 4 of the ingestion plan). |
+| `meos-movfeat-openapi.json` | MEOS-API session's natural-follow-up | OGC API – Moving Features resource projection. The immediate dependency for MobilityAPI step 5; until it lands, MobilityAPI's hand-written OGC endpoints stay. |
+
+## Why we vendor instead of fetching at runtime
+
+Three reasons:
+
+1. **Reproducible builds** — a MobilityAPI checkout pinned to commit `X` always builds against the same MEOS-API artefact tree, not whatever MEOS-API's master happens to be at build time.
+2. **No libclang dependency at install time** — running MEOS-API's `run.py` (the enrichment pass) requires libclang and a checked-out MEOS source tree. Most MobilityAPI users don't need that.
+3. **Diff-able drift signal** — a `make vendor-meos-api` followed by `git status` immediately shows what changed upstream, surfacing breaking-changes as reviewable diffs.
+
+See [`docs/MEOS_API_INGESTION_PLAN.md`](../../docs/MEOS_API_INGESTION_PLAN.md) for the full ingestion roadmap (steps 1–5).