From 59c4525d8792a23ab8f777a9ff7ec0d6cca419f3 Mon Sep 17 00:00:00 2001
From: Esteban Zimanyi <estebanzimanyi@gmail.com>
Date: Tue, 1 Sep 2026 00:17:55 +0200
Subject: [PATCH] Say the generator is staged, because it is
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`GENERATION.md` calls `codegen_jvm.py` "the single generator vendored identically
by every JVM binding", and the `pom.xml` comment calls the catalog "vendored".
Neither is: `.gitignore` lists `tools/meos-idl.json`, `tools/codegen_jvm.py` and
`tools/codegen_spark_udfs.py`, and `maven.yml` copies all three in — the catalog
from the provision-meos action, the two generator files from a JMEOS checkout. The
workflow says as much in its own comment two files away.

The distinction is the point rather than a nicety. Every symbol the generator
emits is a call into the `functions.GeneratedFunctions` the jar carries, so the
generator and the surface it binds are one unit, and JMEOS owns it. A copy in this
tree goes stale the moment that surface folds an out-parameter or widens a return,
which is what three copies did before JMEOS took ownership: they drifted by 202
lines.
---
 GENERATION.md | 15 ++++++++++-----
 pom.xml       | 11 +++++++----
 2 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/GENERATION.md b/GENERATION.md
index a56f8aad..60188c9e 100644
--- a/GENERATION.md
+++ b/GENERATION.md
@@ -11,15 +11,20 @@ binding owns its generator in its own repo. The source of truth is the catalog
 ## MobilitySpark is a consumer binding
 
 MobilitySpark binds the **JMEOS jar** (the JVM FFI projection of the catalog), not MEOS-API
-directly. Its generator is the shared **`tools/codegen_jvm.py --engine spark`**, the single
-generator vendored identically by every JVM binding (MobilitySpark, MobilityFlink,
-MobilityKafka). The `spark` engine delegates verbatim to the sibling
+directly. Its generator is the shared **`tools/codegen_jvm.py --engine spark`**, which **JMEOS
+owns** and this repository STAGES: `tools/codegen_jvm.py` and `tools/codegen_spark_udfs.py` are
+gitignored here, copied in by the refresh chain and by CI from the JMEOS checkout, exactly as the
+catalog is. Every symbol the generator emits is a call into the `functions.GeneratedFunctions`
+that jar carries, so the generator and the surface it binds are one unit: a copy left in this tree
+goes stale the moment that surface folds an out-parameter or widens a return. MobilityFlink and
+MobilityKafka stage the same two files from the same place. The `spark` engine delegates verbatim
+to the sibling
 **`tools/codegen_spark_udfs.py`** (which mirrors the JMEOS `FunctionsGenerator`): it reads the
 JMEOS surface and the catalog's `@sqlfn` names and emits the Spark UDF registration layer,
 organized **by `@ingroup` group** (one unit per group, the same structure as the reference
 manual). Every emitted `register()` is preceded by the per-thread MEOS-init guard, enforced at
-build time. Sharing one generator across the JVM bindings is what keeps the surface from
-drifting between engines.
+build time. One generator with one home is what keeps the surface from drifting between engines;
+three copies of it drifted by 202 lines before JMEOS took ownership.
 
 ## Inputs
 
diff --git a/pom.xml b/pom.xml
index 5abc21cc..260e8331 100644
--- a/pom.xml
+++ b/pom.xml
@@ -47,10 +47,13 @@
 
     <build>
         <plugins>
-            <!-- Generate the whole UDF surface from the vendored MEOS-API catalog at
-                 build time (North Star: bindings are GENERATED from MEOS, never hand
-                 written). codegen_jvm.py is the single generator shared by every JVM
-                 binding; the spark engine delegates to codegen_spark_udfs.py so the
+            <!-- Generate the whole UDF surface from the MEOS-API catalog at build
+                 time (North Star: bindings are GENERATED from MEOS, never hand
+                 written). Both the catalog and the generator are STAGED into tools/
+                 and gitignored, never committed: the catalog is derived from
+                 MobilityDB master by the provision-meos action, and codegen_jvm.py
+                 with its codegen_spark_udfs.py sibling is copied in from JMEOS, which
+                 owns them. The spark engine delegates to codegen_spark_udfs.py so the
                  emitted surface is identical to that generator's. It reads the
                  org.jmeos:meos jar's actual symbols so it never emits a call to an
                  absent/mismatched JMEOS method. -->