codegen(meos): generate tier-aware MEOS facade for the full JMEOS 1.4 surface (stacks on #4)

[estebanzimanyi]

Add a generated, tier-aware Java facade over the full MEOS public API surface, so downstream Flink-side parity work can stop hand-wiring per-operator JMEOS calls and instead consume one mechanical facade per MEOS object-model class (or per public header for free functions).

What is generated

Layer	Java class shape	Files	Methods	Source
OO-classified	MeosOps<Class> — one per MEOS object-model class	50	751	tools/codegen/codegen-oo.py
Free fns	MeosOpsFree<Header> — one per public MEOS header for fns not assigned to any OO class	6	1,346	tools/codegen/codegen-free.py
Shared runtime	MeosOpsRuntime (singleton MEOS_AVAILABLE static init across all 56 facades)	1	—	hand-written, ~30 LOC
Total		57	2,097	77.7% of JMEOS PR #19's full 2,699-method surface

Each emitted method forwards verbatim to functions.GeneratedFunctions.<name>(...) after probing MeosOpsRuntime.MEOS_AVAILABLE (set once per JVM). Each method carries a Javadoc tier marker:

Tier	Meaning	Flink wiring shape
stateless	Pure per-event, no state	ScalarFunction / direct call in MapFunction
bounded-state	Per-event with bounded per-key state (MEOS handle)	ScalarFunction (state in MEOS handle)
windowed	Output cardinality changes; needs window	AggregateFunction over TUMBLE/HOP
cross-stream	Pairwise across streams; needs interval-overlap join	CoProcessFunction / IntervalJoin
io-meta	I/O, catalog, lifecycle helpers	Helper / format clause

Tier breakdown of the 2,097 emitted methods: 804 stateless · 797 bounded-state · 161 windowed · 140 cross-stream · 195 io-meta.

What's not emitted (honest gap)

• 50 baseline-target methods absent from JMEOS — type-catalog helpers JMEOS deliberately omits (*_basetype, *_type, *_spantype, …)
• 14 functions in the streaming-relevance baseline's sequence-only tier — inherently non-streamable, marked as honest "cannot satisfy" pending an emission-shape decision
• 59 ambiguous functions where the mechanical classifier couldn't decide between two defensible tiers — resolution drafted separately as the streamingSemantics facet RFC for MEOS-API

Coexistence with berlinmod.MEOSBridge

MEOSBridge.java (hand-written, BerlinMOD-scoped, introduced on this branch's parent feat/jmeos-bridge-swap) and the generated MeosOps* facades coexist by design:

• MEOSBridge keeps the per-BerlinMOD-query intent (Haversine fallback, dwithinSegmentMetres, etc.) — high-level, query-shaped.
• MeosOps* exposes the raw MEOS surface tier-by-tier — low-level, catalog-shaped.

Both share the same MEOS_AVAILABLE discipline (via MeosOpsRuntime) and the same functions.GeneratedFunctions delegation.

How to regenerate

# 1. Regenerate the MEOS-API catalog from MobilityDB headers
git clone --branch feat/object-model https://github.com/MobilityDB/MEOS-API.git
cd MEOS-API && pip install -r requirements.txt
python run.py /path/to/MobilityDB/meos/include /path/to/MobilityDB/mobilitydb/src
# → output/meos-idl.json

# 2. Produce the streaming-relevance baseline (v4 classifier)
# → streaming-relevance-baseline.json

# 3. Extract JMEOS method signatures
jar xf flink-processor/jar/JMEOS.jar functions/GeneratedFunctions.class
javap -p functions.GeneratedFunctions > jmeos_signatures.txt

# 4. Run both generators
python flink-processor/tools/codegen/codegen-oo.py
python flink-processor/tools/codegen/codegen-free.py

Both generators are ~250 LOC, deterministic, audit-by-regeneration. Manifests under tools/codegen/ record per-class / per-header / per-tier breakdowns + absent-from-JMEOS audit.

Stacking

This PR stacks on feat/jmeos-bridge-swap. Additive-only: 57 new Java files + 5 files under tools/codegen/. No existing file is touched (no diff to MEOSBridge.java, Main.java, TrajectoryWindowFunction.java, pom.xml, or jar/JMEOS.jar).

Note on the base branch's current compile state

feat/jmeos-bridge-swap's MEOSBridge.java:116 imports utils.spatial.PointToSegment from JMEOS PR #18's feat/spatial-haversine branch. The recent bundled-jar refresh on this branch (commit 0a57c07, JMEOS PR #19's jmeos-core jar) brought in the 2,699-method functions.GeneratedFunctions surface but did not include PR #18's utils.spatial.* wrappers. As a result, the base-branch mvn compile currently fails on MEOSBridge.java.

This PR's own diff is green in isolation (javac of just org.mobilitydb.flink.meos.* succeeds against the refreshed jar) and green in the full module when the bundled jar is the union of JMEOS PR #19's jmeos-core + PR #18's utils.spatial.* (locally verified: 123 .class files compile clean, including all 57 new MeosOps*).

Recipe to produce the union jar (~2 minutes):

git clone --depth 1 --branch feat/spatial-haversine https://github.com/estebanzimanyi/JMEOS.git /tmp/pr18
javac -cp flink-processor/jar/JMEOS.jar:$(find ~/.m2 -name 'jnr-ffi-2.2.14.jar' | head -1) \
      -d /tmp/pr18-classes \
      /tmp/pr18/jmeos-core/src/main/java/utils/spatial/Haversine.java \
      /tmp/pr18/jmeos-core/src/main/java/utils/spatial/PointToSegment.java
mkdir /tmp/union && cd /tmp/union
jar xf /path/to/refreshed/JMEOS.jar
cp -r /tmp/pr18-classes/utils .
jar cf /path/to/flink-processor/jar/JMEOS.jar .

Once the bundled jar is refreshed with the union, the base branch + this PR compile together cleanly.

[estebanzimanyi]

Coordination confirmation: rebased onto the post-union-jar refresh (6676bbb on Flink / fa70867 on Kafka — the JMEOS PR #19 + PR #18 union jar with utils.spatial.{Haversine,PointToSegment}).

Local verification:

$ mvn -q -DskipTests compile
# Flink: 123 .class files total, of which 57 MeosOps*
# Kafka:  94 .class files total, of which 57 MeosOps*

Full module now compiles green — the codegen wedge sits on top of MEOSBridge.java's utils.spatial.* imports without any inherited compile-red. mergeStateStatus = CLEAN. Ready for review/merge whenever.

Coordination item resolved. Thanks for the union-jar refresh.

[estebanzimanyi]

Superseded by the Path-B consolidation: the former 18-deep stack is collapsed into two reviewable topical PRs on top of the merged scaffold — MEOS integration #30 → benchmark #31 — each one clean squashed commit with the generated-facade bulk, dead family-flag profiles, committed target/ artifacts, and invented synthetic corpus removed. Closing as folded into #30/#31.