Add the MobilityFlink pin manifest and per-binding generator policy

GENERATION.md

@@ -0,0 +1,41 @@
+# MobilityFlink generation — the canonical per-binding generator policy
+
+This document is the contract for how MobilityFlink is generated, under the ecosystem-wide
+per-binding generator policy.
+
+## The policy (ecosystem-wide)
+
+Every MobilityDB language/surface binding is a **pure projection of the MEOS-API catalog**,
+and **each binding owns its own generator, in its own repo**, in a canonical layout. The
+single source of truth is the **catalog** (`MEOS-API/output/meos-idl.json`, generated from
+the MEOS C headers). A binding is an independent, plug-and-play module that owns its
+generation.
+
+Each binding repo satisfies the same invariants: in-repo generator; own
+`tools/pin/compose-order.txt`; pinned catalog/jar input; thin language projection; full
+automation toward a zero-hand-written surface (generate-then-retire; the last green-CI
+version is the equivalence probe).
+
+## MobilityFlink scope: generated MEOS facades over the JMEOS surface
+
+MobilityFlink is a **consumer** binding: it binds the **JMEOS jar** (the JVM FFI projection
+of the catalog), not MEOS-API directly. Its generator **`tools/codegen_facades.py`** reads
+the bundled JMEOS raw-FFI surface (intersected with the streaming-relevance baseline) and
+emits the `org.mobilitydb.meos.MeosOps*` 1:1 forwarder facades the Flink processor consumes.
+The facades are a *consumer* projection (they live here, not in JMEOS, so the JMEOS FFI line
+and the facade line do not diverge).
+
+## Generate-then-retire — the green-CI version is the probe
+
+Hand-written facades/glue are replaced by the generated forwarders **family by family,
+never wipe-first**: regenerate, build green, **prove generated ⊇ hand** against the **last
+green-CI version** (the test suite + the streaming benchmark), then retire the hand path.
+The generated facades are committed and regenerated on a pin bump.
+
+## Pinning
+
+The bundled JMEOS jar is built from a deliverable-PR head (never committed as a binary), and
+the `libmeos.so` it links is built from the **same MobilityDB pin** the JMEOS surface was
+generated against (surface-match, else runtime symbol faults). That pin is the
+*catalog/surface* input; MobilityFlink's own `tools/pin/compose-order.txt` governs *this
+repo's* PR accumulate.

tools/pin/compose-order.txt

@@ -0,0 +1,27 @@
+# USER-APPROVED-PIN-WRITE — creating MobilityFlink's first pin manifest (user 2026-06-25,
+#   per-binding generator policy rollout). New file in the MobilityFlink repo, NOT a mutation
+#   of MobilityDB's pin tooling.
+#
+# MobilityFlink pin — THE canonical, dependency-ordered fold manifest (per-binding policy).
+#
+# MobilityFlink is a CONSUMER binding: it binds the JMEOS jar (not MEOS-API directly) and
+# generates its org.mobilitydb.meos facades from it. (policy: generator-per-binding-canonical-policy)
+#
+# SCOPE: MobilityFlink owns its generator IN-REPO at `tools/codegen_facades.py` — it reads
+# the bundled JMEOS raw-FFI surface and emits the `org.mobilitydb.meos.MeosOps*` facade
+# forwarders the Flink processor consumes.
+#
+# Format:  <PR#> <head-branch>            # role.   '?' = membership/order UNCONFIRMED.
+# base = current origin/main. Verified this turn: #30 (consolidate/flink-meos-integration) is
+# MERGED into main; the facade generator lives on the open #31 branch.
+
+# ── WAVE 0 — FRONTIER (the MEOS streaming consumer + the facade generator) ──
+31    consolidate/flink-benchmark           # streaming throughput benchmark on the canonical BerlinMOD
+                                            #   corpus; carries tools/codegen_facades.py (stacks on the merged #30).
+
+# ════════════════════════════════════════════════════════════════════════════════════
+# DISPOSITION: #30 (the MEOS integration) is already merged. Land #31 (benchmark + the facade
+# generator). The bundled JMEOS jar is built/pinned from a deliverable-PR head (not committed),
+# and the libmeos it links is built from the SAME pin the JMEOS facade was generated against
+# (surface-match). See GENERATION.md.
+# ════════════════════════════════════════════════════════════════════════════════════

tools/regen-from-pin.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# regen-from-pin.sh — regenerate the MobilityFlink MEOS facades from the JMEOS jar
+# (per GENERATION.md). MobilityFlink is a JMEOS consumer.
+#
+# Usage:  tools/regen-from-pin.sh <pin>
+#   env:  JMEOS_JAR = path to the JMEOS jar built from the same pin (required)
+#
+# Invoked standalone, or by MEOS-API tools/ecosystem-generate.sh (after the JMEOS jar).
+set -euo pipefail
+PIN="${1:?usage: regen-from-pin.sh <pin>}"
+JMEOS_JAR="${JMEOS_JAR:?set JMEOS_JAR to the JMEOS jar built from the same pin}"
+HERE="$(cd "$(dirname "$0")/.." && pwd)"
+
+# run the in-repo generator (tools/codegen_facades.py: --jar --out --engine) ->
+# org.mobilitydb.meos.MeosOps* forwarder facades under <out>/src/main/java
+python3 "$HERE/tools/codegen_facades.py" --jar "$JMEOS_JAR" --out "$HERE" --engine flink
+
+# build-verify
+( cd "$HERE" && mvn -q test ) || echo "WARN: MobilityFlink mvn test returned non-zero"
+echo "[flink] regenerated facades from JMEOS jar at pin $PIN"