Skip to content

chore(vendor): vendor MEOS-API artefacts (step 2 of the ingestion plan)#4

Open
estebanzimanyi wants to merge 1 commit into
MobilityDB:masterfrom
estebanzimanyi:feat/vendor-meos-api-artefacts
Open

chore(vendor): vendor MEOS-API artefacts (step 2 of the ingestion plan)#4
estebanzimanyi wants to merge 1 commit into
MobilityDB:masterfrom
estebanzimanyi:feat/vendor-meos-api-artefacts

Conversation

@estebanzimanyi
Copy link
Copy Markdown
Member

@estebanzimanyi estebanzimanyi commented May 20, 2026 •
edited
Loading

Step 2 of docs/MEOS_API_INGESTION_PLAN.md (planned in #3). Brings the published MEOS-API catalog + parity artefacts into vendor/meos-api/ with a regenerate Makefile target.

What's vendored

File Source Notes
vendor/meos-api/meos-idl.json MEOS-API master + MobilityDB master headers 3546 functions / 70 structs / 16 enums, generated by python3 run.py <MobilityDB/meos/include>
vendor/meos-api/meos-coverage.json MEOS-API PR #4 (feat/service-enrichment) structural worklist of non-exposable functions, ranked by byClass
vendor/meos-api/meos-object-model-parity.json MEOS-API PR #10 (feat/object-model) 29-pair portable-bare-name parity contract
vendor/meos-api/PROVENANCE.json this PR machine-readable source + regenerate command for each artefact
vendor/meos-api/README.md this PR per-artefact docs + refresh procedure

meos-coverage.json and meos-object-model-parity.json source from open MEOS-API PR branches (report.py and object_model_parity.py are not yet on master); PROVENANCE.json records that explicitly. The Makefile gracefully skips files the upstream branch does not produce.

Makefile targets

make vendor-meos-api            # from MEOS-API master + MobilityDB master
make vendor-meos-api-from-prs   # from open MEOS-API PRs #4 + #5, regenerated

Both targets clone MEOS-API and MobilityDB shallowly, install libclang==18.1.1, run python3 run.py <MobilityDB-headers>, and copy the produced JSON artefacts into vendor/meos-api/. MEOS_API_REPO / MEOS_API_REF / MOBILITYDB_REPO / MOBILITYDB_REF are make variables so each can be pinned.

CI gate

The drift gate (step 3) lands as #5, stacked on this PR.

@estebanzimanyi
chore(vendor): vendor MEOS-API artefacts (step 2 of the ingestion plan)
4d5098f 
Vendor MobilityAPI's read-only copy of MEOS-API's published catalog +
projection artefacts under `vendor/meos-api/`, plus a Makefile target
`make vendor-meos-api` that regenerates them from upstream.

Files added:

  vendor/meos-api/
    PROVENANCE.json              -- per-artefact source URLs + regenerate cmd
    README.md                    -- refresh procedure
    meos-idl.json                -- 3546 fns / 70 structs / 16 enums
                                    (generated by MEOS-API run.py over
                                    MobilityDB master meos/include headers)
    meos-coverage.json           -- structural worklist (from open PR MobilityDB#4)
    meos-object-model-parity.json -- 29-pair portable-parity (from open PR #10)

The Makefile target clones MEOS-API + MobilityDB shallowly, installs
libclang, runs MEOS-API's `run.py` against MobilityDB's MEOS headers,
and copies the produced JSON artefacts into `vendor/meos-api/`.

Two of the four artefacts (`meos-coverage.json`,
`meos-object-model-parity.json`) currently come from open MEOS-API PR
branches because their generators are not yet on master; PROVENANCE.json
makes that explicit. The Makefile gracefully skips them if absent.

Step 2 of `docs/MEOS_API_INGESTION_PLAN.md`. The drift gate workflow
that fails on stale artefacts is step 3 (separate stacked PR).
@estebanzimanyi estebanzimanyi force-pushed the feat/vendor-meos-api-artefacts branch from 58bbc39 to 4d5098f Compare May 20, 2026 15:07
@estebanzimanyi estebanzimanyi mentioned this pull request May 20, 2026
Open
estebanzimanyi added a commit to estebanzimanyi/MobilityAPI that referenced this pull request May 20, 2026
@estebanzimanyi
ci(vendor): add vendor-drift workflow (step 3 of ingestion plan)
6d58be2 
Adds `.github/workflows/vendor-drift.yml` which regenerates the
vendored MEOS-API artefacts (`make vendor-meos-api`) on every PR
touching `vendor/meos-api/`, the Makefile, or the workflow itself,
plus on push to master and on a daily 06:00 UTC cron. On drift it
fails with an actionable message:

  ::error::vendor/meos-api/ is stale. Run `make vendor-meos-api`
  locally and open a refresh PR.

This is step 3 of `docs/MEOS_API_INGESTION_PLAN.md` ("CI gate that
regenerates the vendored artefacts and fails the PR if they drift").

Stacks on PR MobilityDB#4 (vendoring + Makefile).
estebanzimanyi added a commit to estebanzimanyi/MobilityAPI that referenced this pull request May 20, 2026
@estebanzimanyi
ci(vendor): add vendor-drift workflow (step 3 of ingestion plan)
efcad95 
Adds `.github/workflows/vendor-drift.yml` which regenerates the
vendored MEOS-API artefacts (`make vendor-meos-api`) on every PR
touching `vendor/meos-api/`, the Makefile, or the workflow itself,
plus on push to master and on a daily 06:00 UTC cron. On drift it
fails with an actionable message:

  ::error::vendor/meos-api/ is stale. Run `make vendor-meos-api`
  locally and open a refresh PR.

This is step 3 of `docs/MEOS_API_INGESTION_PLAN.md` ("CI gate that
regenerates the vendored artefacts and fails the PR if they drift").

Stacks on PR MobilityDB#4 (vendoring + Makefile).
estebanzimanyi added a commit to estebanzimanyi/MobilityAPI that referenced this pull request May 20, 2026
@estebanzimanyi
ci(vendor): add vendor-drift workflow (step 3 of ingestion plan)
254c8a9 
Adds `.github/workflows/vendor-drift.yml` which regenerates the
vendored MEOS-API artefacts (`make vendor-meos-api`) on every PR
touching `vendor/meos-api/`, the Makefile, or the workflow itself,
plus on push to master and on a daily 06:00 UTC cron. On drift it
fails with an actionable message:

  ::error::vendor/meos-api/ is stale. Run `make vendor-meos-api`
  locally and open a refresh PR.

This is step 3 of `docs/MEOS_API_INGESTION_PLAN.md` ("CI gate that
regenerates the vendored artefacts and fails the PR if they drift").

Stacks on PR MobilityDB#4 (vendoring + Makefile).
estebanzimanyi added a commit to estebanzimanyi/MobilityAPI that referenced this pull request May 20, 2026
@estebanzimanyi
ci(vendor): add vendor-drift workflow (step 3 of ingestion plan)
ca4c130 
Adds `.github/workflows/vendor-drift.yml` which regenerates the
vendored MEOS-API artefacts (`make vendor-meos-api`) on every PR
touching `vendor/meos-api/`, the Makefile, or the workflow itself,
plus on push to master and on a daily 06:00 UTC cron. On drift it
fails with an actionable message:

  ::error::vendor/meos-api/ is stale. Run `make vendor-meos-api`
  locally and open a refresh PR.

This is step 3 of `docs/MEOS_API_INGESTION_PLAN.md` ("CI gate that
regenerates the vendored artefacts and fails the PR if they drift").

Stacks on PR MobilityDB#4 (vendoring + Makefile).
@estebanzimanyi estebanzimanyi mentioned this pull request May 20, 2026
Open
estebanzimanyi added a commit to estebanzimanyi/MobilityAPI that referenced this pull request May 20, 2026
@estebanzimanyi
feat(dispatcher): catalog-driven MEOS-function dispatcher (step 4 fou…
6bf5621 
…ndation)

Step 4 of docs/MEOS_API_INGESTION_PLAN.md — the catalog-driven
dispatcher that the 5 'REPLACE' resource modules will delegate to in
follow-up PRs.

mobilityapi/dispatcher.py:

- Loads vendor/meos-api/meos-idl.json at construction; honours an
  explicit catalog_path= for tests.
- Filters to network.exposable functions only when enrichment fields
  are present; otherwise treats every function as exposable.
- FunctionSignature dataclass: name / category / params / return_type
  / decode_per_param / encode_return / description, all populated
  from the catalog (enriched or bare).
- dispatch(function_name, params) -> Any:
  * validates the parameter set against the catalog signature
    (missing or unexpected names raise TypeError)
  * resolves the MEOS function via an injected resolver callable
    (production: getattr(pymeos.functions, name); tests: stub
    registry)
  * invokes it with the validated keyword args
  * returns the result; the caller owns encoding to JSON / WKB

tests/test_dispatcher.py (12 tests, all passing locally):

- catalog load (default path, explicit path, FileNotFoundError)
- FunctionSignature.from_catalog_entry (basic fields, enriched wire
  metadata, fallback when wire absent, non-exposable filtering)
- dispatch contract (resolver invocation, unknown function, missing
  param, unexpected param, default stub resolver)
- integration sanity (the 5 MovFeat dispatch candidates named in the
  ingestion plan are present in the vendored catalog)

What this PR does NOT change:

- Existing hand-written endpoint modules in resource/* remain
  unchanged. The plan's 5 REPLACE candidates migrate to the
  dispatcher module-by-module in follow-up PRs:
  temporal_geom_seq/, temporal_geom_query/{velocity,acceleration,
  distance}, temporal_properties/.
- PyMEOS is not yet a dependency (the dispatcher is resolver-
  agnostic; the production resolver lands when the first endpoint
  migrates).

Stacks on MobilityDB#4 (vendor MEOS-API artefacts) so vendor/meos-api/meos-idl.json
is in the tree.
@estebanzimanyi estebanzimanyi mentioned this pull request May 21, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@estebanzimanyi