From 6fb82bc3dd103c3395687cd919d83afdaa7d6f0f Mon Sep 17 00:00:00 2001 From: Esteban Zimanyi Date: Thu, 25 Jun 2026 21:17:23 +0200 Subject: [PATCH] Add the MobilityFlink pin manifest and per-binding generator policy doc Add tools/pin/compose-order.txt (the canonical fold manifest; #30 merged, #31 carries the facade generator + benchmark) and GENERATION.md (the per-binding generator policy: MobilityFlink binds the JMEOS jar and generates the org.mobilitydb.meos facades via tools/codegen_facades.py). --- GENERATION.md | 41 +++++++++++++++++++++++++++++++++++++ tools/pin/compose-order.txt | 27 ++++++++++++++++++++++++ tools/regen-from-pin.sh | 20 ++++++++++++++++++ 3 files changed, 88 insertions(+) create mode 100644 GENERATION.md create mode 100644 tools/pin/compose-order.txt create mode 100755 tools/regen-from-pin.sh diff --git a/GENERATION.md b/GENERATION.md new file mode 100644 index 0000000..ce3f154 --- /dev/null +++ b/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. diff --git a/tools/pin/compose-order.txt b/tools/pin/compose-order.txt new file mode 100644 index 0000000..48d78be --- /dev/null +++ b/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: # 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. +# ════════════════════════════════════════════════════════════════════════════════════ diff --git a/tools/regen-from-pin.sh b/tools/regen-from-pin.sh new file mode 100755 index 0000000..4af0923 --- /dev/null +++ b/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 +# 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 }" +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 /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"