fix(telemetry): synchronous send + version-alignment CI (#1706) (#136)

Java SDK had the same telemetry-delivery bug as Python (#1692) and Go
(#1693): CompletableFuture.runAsync(lambda) without an explicit executor
submits to ForkJoinPool.commonPool(), whose threads are daemon by
default since Java 8. When the JVM's main thread exits, those daemon
threads are killed mid-flight — the OkHttpClient.newCall().execute()
inside the lambda is abandoned. CLI Java binaries, AWS Lambda Java
handlers, serverless cold-starts, and quickstart scripts silently drop
telemetry pings with no error visible to the caller. Per the 2026-04-24
SDK-telemetry investigation, this is a likely major contributor to the
0 external-confirmed Java records we've observed to date.

## Fix (TelemetryReporter.java)

- Replaced CompletableFuture.runAsync(...) with synchronous execution.
  Blocks the caller briefly: ~350ms warm / ~1.3s cold on a reachable
  checkpoint, bounded at TIMEOUT_SECONDS on an unreachable one.
  Acceptable for a control-plane SDK's construction path, matching the
  Go SDK pattern shipped in #1693.
- Shared monotonic deadline across /health probe and checkpoint POST.
  Previously detectPlatformVersion (2s timeout) and the checkpoint POST
  (3s timeout) had independent timeouts that could stack to ~5s.
  detectPlatformVersion now takes a budgetMs parameter derived from the
  shared deadline; POST uses whatever is left.
- Both operations skip when remaining budget is below MIN_BUDGET_MS
  (100ms) to avoid issuing calls that are guaranteed to time out.

## Regression test (TelemetryReporterShortLivedTest.java)

Verifies the core invariant: when sendPing returns, the HTTP round-trip
has already completed (not still-pending on a dying daemon thread). Uses
a WireMock server with a fixed-delay response; measures elapsed time to
confirm sendPing actually blocked. Verified:

- FAIL at 0.070s when reverted to CompletableFuture.runAsync
- PASS at 0.971s with the fix

So a future regression to fire-and-forget is caught by CI, not by
missing telemetry in production.

## CHANGELOG

Added [Unreleased] section with terse one-line entries per the
telemetry-CHANGELOG-minimal rule: delivery fix + shared-deadline bound
+ the alignment-check addition below.

## Version alignment CI (.github/scripts + .github/workflows)

Mirrors the pattern just added in axonflow-sdk-go PR #130 and already
present in the platform repo. Script compares pom.xml <version> against
the first released '## [X.Y.Z]' section in CHANGELOG.md; CI runs on any
PR or push to main that touches either file. Prevents the drift pattern
where a release ships to Maven Central but the repo's pom stays behind
(and the inverse: pom bumped but CHANGELOG still shows the prior
version as latest released).

Verified the script locally: PASS on current state (pom 5.7.0 ==
CHANGELOG 5.7.0); FAIL when pom is manually mismatched to 5.8.0.

Full test suite: 1,200 tests, 0 failures.

Closes getaxonflow/axonflow-enterprise#1706.

Author: saurabhjain1592

.github/scripts/validate-version-alignment.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Validates that the Java SDK's declared version (pom.xml) matches the
+# latest released version in CHANGELOG.md. Patterned on the AxonFlow
+# platform's and Go SDK's script of the same name.
+#
+# Purpose: keep the repo's manifest (pom.xml) in lock-step with the
+# CHANGELOG so the state on `main` always matches the most recent
+# published tag. Prevents two drift patterns:
+#   - repo says 5.7.0 but 5.7.1 has already shipped to Maven Central
+#   - repo says 5.7.1 but CHANGELOG still shows 5.7.0 as latest released
+#
+# Run locally:
+#   ./.github/scripts/validate-version-alignment.sh
+#
+# CI: runs on every PR and push to main that touches CHANGELOG.md or
+# pom.xml (see .github/workflows/validate-version-alignment.yml).
+
+set -euo pipefail
+
+ERRORS=0
+
+# Latest RELEASED version = first `## [x.y.z]` line that isn't the
+# Keep-a-Changelog "[Unreleased]" placeholder. The Unreleased section
+# accumulates in-flight changes between tags and must not be used as
+# the expected-version target — the manifest only gets bumped when we
+# actually cut a tag.
+LATEST_VERSION=$(grep -m1 -E '^## \[[0-9]' CHANGELOG.md | sed 's/## \[\(.*\)\].*/\1/' | sed 's/^v//')
+
+if [ -z "${LATEST_VERSION:-}" ]; then
+    echo "❌ Could not extract a released version (## [X.Y.Z]) from CHANGELOG.md"
+    exit 1
+fi
+
+echo "📋 Latest CHANGELOG version: $LATEST_VERSION"
+echo ""
+
+# Check pom.xml <version>. We match the first top-level <version> (the
+# project's own declaration), not any <version> inside <dependencies>
+# or <plugins>. The project version is the first match in Maven's
+# standard layout.
+echo "🔧 Checking pom.xml..."
+POM_VERSION=$(grep -m1 -E '^\s*<version>[0-9]+\.[0-9]+\.[0-9]+.*</version>' pom.xml \
+    | sed -E 's|.*<version>(.*)</version>.*|\1|' || true)
+
+if [ -z "${POM_VERSION:-}" ]; then
+    echo "  ❌ pom.xml — could not extract <version> element"
+    ERRORS=$((ERRORS + 1))
+elif [ "$POM_VERSION" != "$LATEST_VERSION" ]; then
+    echo "  ❌ pom.xml — <version> is \"$POM_VERSION\", expected \"$LATEST_VERSION\""
+    ERRORS=$((ERRORS + 1))
+else
+    echo "  ✅ pom.xml — $POM_VERSION"
+fi
+
+echo ""
+
+if [ "$ERRORS" -gt 0 ]; then
+    echo "❌ Found $ERRORS version misalignment(s)."
+    echo ""
+    echo "Fix: bump the stale file to match CHANGELOG v$LATEST_VERSION."
+    echo "Or, if CHANGELOG is behind a tag you already pushed, add the"
+    echo "missing '## [${POM_VERSION:-X.Y.Z}] - YYYY-MM-DD' section."
+    exit 1
+fi
+
+echo "✅ All version declarations match CHANGELOG v$LATEST_VERSION."

.github/workflows/validate-version-alignment.yml

@@ -0,0 +1,41 @@
+name: Version Alignment Check
+
+# Blocks merges that would leave pom.xml's <version> out of sync with
+# CHANGELOG.md's most recent released section. The invariant on main:
+#   <version> in pom.xml  ==  first `## [X.Y.Z]` section in CHANGELOG
+# When it's time to release, a single release-prep PR renames
+# `[Unreleased]` → `[X.Y.Z] - YYYY-MM-DD` AND bumps pom.xml in the
+# same commit, so this gate always sees them together.
+#
+# See .github/scripts/validate-version-alignment.sh for the script.
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'CHANGELOG.md'
+      - 'pom.xml'
+      - '.github/scripts/validate-version-alignment.sh'
+      - '.github/workflows/validate-version-alignment.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'CHANGELOG.md'
+      - 'pom.xml'
+      - '.github/scripts/validate-version-alignment.sh'
+      - '.github/workflows/validate-version-alignment.yml'
+
+permissions:
+  contents: read
+
+env:
+  DO_NOT_TRACK: '1'
+
+jobs:
+  validate-versions:
+    name: Validate Version Alignment
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check version alignment
+        run: ./.github/scripts/validate-version-alignment.sh

CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to the AxonFlow Java SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Fixed
+
+- Telemetry pings now deliver reliably from short-lived JVMs (CLI, serverless, cold-starts). `AxonFlow` construction blocks briefly while the ping is sent synchronously (bounded by the telemetry timeout).
+- Telemetry path is bounded at `TIMEOUT_SECONDS` (3s) total; the `/health` probe and checkpoint POST share a single monotonic deadline instead of stacking independent timeouts.
+
+### Added
+
+- **Version alignment check** (`.github/workflows/validate-version-alignment.yml`). CI now fails any PR or push to `main` where `pom.xml`'s `<version>` drifts from the first released `## [X.Y.Z]` section in `CHANGELOG.md`. Matches the pattern in the platform repo and the Go SDK.
+
 ## [5.7.0] - 2026-04-22
 
 ### Added

src/main/java/com/getaxonflow/sdk/telemetry/TelemetryReporter.java

@@ -23,7 +23,6 @@
 import java.net.URI;
 import java.net.URISyntaxException;
 import java.util.UUID;
-import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.TimeUnit;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
@@ -58,6 +57,14 @@ public class TelemetryReporter {
 
   static final String DEFAULT_ENDPOINT = "https://checkpoint.getaxonflow.com/v1/ping";
   private static final int TIMEOUT_SECONDS = 3;
+  /**
+   * Minimum remaining HTTP budget (milliseconds). Below this, skip the operation rather than issue
+   * a request that is almost guaranteed to time out before any useful work completes. Keeps the
+   * telemetry path from making "essentially zero budget" calls when the shared deadline is nearly
+   * spent.
+   */
+  private static final long MIN_BUDGET_MS = 100L;
+
   private static final MediaType JSON = MediaType.get("application/json; charset=utf-8");
 
   /**
@@ -108,36 +115,62 @@ static void sendPing(
     String endpoint =
         (checkpointUrl != null && !checkpointUrl.isEmpty()) ? checkpointUrl : DEFAULT_ENDPOINT;
 
-    final String finalSdkEndpoint = sdkEndpoint;
-    final String endpointType = classifyEndpoint(finalSdkEndpoint);
-    CompletableFuture.runAsync(
-        () -> {
-          try {
-            String platformVersion = detectPlatformVersion(finalSdkEndpoint);
-            String payload = buildPayload(mode, platformVersion, endpointType);
-
-            OkHttpClient client =
-                new OkHttpClient.Builder()
-                    .connectTimeout(TIMEOUT_SECONDS, TimeUnit.SECONDS)
-                    .readTimeout(TIMEOUT_SECONDS, TimeUnit.SECONDS)
-                    .writeTimeout(TIMEOUT_SECONDS, TimeUnit.SECONDS)
-                    .build();
-
-            RequestBody body = RequestBody.create(payload, JSON);
-            Request request = new Request.Builder().url(endpoint).post(body).build();
-
-            try (Response response = client.newCall(request).execute()) {
-              if (debug) {
-                logger.debug("Telemetry ping sent, status={}", response.code());
-              }
-            }
-          } catch (Exception e) {
-            // Silent failure - telemetry must never disrupt SDK operation
-            if (debug) {
-              logger.debug("Telemetry ping failed (silent): {}", e.getMessage());
-            }
-          }
-        });
+    String endpointType = classifyEndpoint(sdkEndpoint);
+
+    // Send synchronously with a single bounded deadline shared across the
+    // /health probe and the checkpoint POST. A CompletableFuture.runAsync
+    // here would default to ForkJoinPool.commonPool (daemon threads) which
+    // die at JVM exit, silently dropping the ping for short-lived JVMs (CLI
+    // binaries, Lambda handlers, serverless cold-starts, quickstart scripts).
+    // See axonflow-enterprise#1706.
+    //
+    // Blocks the caller briefly (~350ms warm / ~1.3s cold on a reachable
+    // checkpoint; bounded at TIMEOUT_SECONDS on an unreachable one). That is
+    // acceptable for a control-plane SDK's construction path, and matches
+    // the pattern shipped for the Go SDK in axonflow-enterprise#1693.
+    try {
+      long deadlineMs =
+          System.nanoTime() / 1_000_000L + TimeUnit.SECONDS.toMillis(TIMEOUT_SECONDS);
+
+      // Health probe gets up to 1s of the remaining budget, so the POST
+      // always has room even when the probe fully consumes its slice.
+      long healthBudgetMs =
+          Math.min(
+              TimeUnit.SECONDS.toMillis(1),
+              Math.max(0L, deadlineMs - System.nanoTime() / 1_000_000L));
+      String platformVersion =
+          (sdkEndpoint != null && !sdkEndpoint.isEmpty() && healthBudgetMs > MIN_BUDGET_MS)
+              ? detectPlatformVersion(sdkEndpoint, healthBudgetMs)
+              : null;
+
+      String payload = buildPayload(mode, platformVersion, endpointType);
+
+      long postBudgetMs = Math.max(0L, deadlineMs - System.nanoTime() / 1_000_000L);
+      if (postBudgetMs < MIN_BUDGET_MS) {
+        return;
+      }
+
+      OkHttpClient client =
+          new OkHttpClient.Builder()
+              .connectTimeout(postBudgetMs, TimeUnit.MILLISECONDS)
+              .readTimeout(postBudgetMs, TimeUnit.MILLISECONDS)
+              .writeTimeout(postBudgetMs, TimeUnit.MILLISECONDS)
+              .build();
+
+      RequestBody body = RequestBody.create(payload, JSON);
+      Request request = new Request.Builder().url(endpoint).post(body).build();
+
+      try (Response response = client.newCall(request).execute()) {
+        if (debug) {
+          logger.debug("Telemetry ping sent, status={}", response.code());
+        }
+      }
+    } catch (Exception e) {
+      // Silent failure - telemetry must never disrupt SDK operation
+      if (debug) {
+        logger.debug("Telemetry ping failed (silent): {}", e.getMessage());
+      }
+    }
   }
 
   /**
@@ -418,16 +451,20 @@ private static String padHextet(String h) {
 
   /**
    * Detect platform version by calling the agent's /health endpoint. Returns null on any failure.
+   *
+   * <p>The {@code budgetMs} parameter is derived from the shared telemetry deadline so the health
+   * probe and the checkpoint POST don't stack into a larger combined budget. See
+   * axonflow-enterprise#1706.
    */
-  static String detectPlatformVersion(String sdkEndpoint) {
+  static String detectPlatformVersion(String sdkEndpoint, long budgetMs) {
     if (sdkEndpoint == null || sdkEndpoint.isEmpty()) {
       return null;
     }
     try {
       OkHttpClient client =
           new OkHttpClient.Builder()
-              .connectTimeout(2, TimeUnit.SECONDS)
-              .readTimeout(2, TimeUnit.SECONDS)
+              .connectTimeout(budgetMs, TimeUnit.MILLISECONDS)
+              .readTimeout(budgetMs, TimeUnit.MILLISECONDS)
               .build();
 
       Request request = new Request.Builder().url(sdkEndpoint + "/health").get().build();

src/test/java/com/getaxonflow/sdk/telemetry/TelemetryReporterShortLivedTest.java

@@ -0,0 +1,90 @@
+/*
+ * Copyright 2026 AxonFlow
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.getaxonflow.sdk.telemetry;
+
+import static com.github.tomakehurst.wiremock.client.WireMock.aResponse;
+import static com.github.tomakehurst.wiremock.client.WireMock.post;
+import static com.github.tomakehurst.wiremock.client.WireMock.postRequestedFor;
+import static com.github.tomakehurst.wiremock.client.WireMock.urlEqualTo;
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.github.tomakehurst.wiremock.junit5.WireMockRuntimeInfo;
+import com.github.tomakehurst.wiremock.junit5.WireMockTest;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Regression test for axonflow-enterprise#1706: the telemetry ping must be delivered synchronously
+ * before {@code sendPing} returns, so that short-lived JVMs (CLI binaries, AWS Lambda handlers,
+ * serverless cold-starts, quickstart scripts) don't drop the ping on JVM exit.
+ *
+ * <p>Root cause of the original bug: {@code CompletableFuture.runAsync(lambda)} submits to {@code
+ * ForkJoinPool.commonPool()}, whose threads are daemon by default since Java 8. When the main
+ * thread exits, the daemon pool is killed mid-flight and the in-flight HTTP POST is abandoned —
+ * silently, with no error visible to the caller.
+ *
+ * <p>The key invariant: once {@code sendPing} returns, the HTTP round-trip must have already
+ * completed (or timed out cleanly). We verify this by pointing the reporter at a WireMock server
+ * that responds with a fixed delay; if {@code sendPing} is synchronous, it blocks until the
+ * response, and elapsed time reflects the delay. If anyone regresses the code back to {@code
+ * runAsync}, the call returns immediately and this test fails.
+ */
+@WireMockTest
+@DisplayName("TelemetryReporter — short-lived-process regression")
+class TelemetryReporterShortLivedTest {
+
+  @Test
+  @DisplayName("sendPing blocks until the HTTP round-trip completes (no fire-and-forget drop)")
+  void sendPingBlocksUntilRoundTripCompletes(WireMockRuntimeInfo info) {
+    // Mock checkpoint returns 200 only after a 200ms delay. If sendPing is
+    // synchronous, the caller blocks for at least that long. If sendPing
+    // regresses to fire-and-forget (daemon-thread), the caller returns
+    // almost immediately (<50ms) and the assertion below fails.
+    info.getWireMock()
+        .register(
+            post(urlEqualTo("/v1/ping"))
+                .willReturn(aResponse().withStatus(200).withFixedDelay(200).withBody("{}")));
+
+    String checkpointUrl = info.getHttpBaseUrl() + "/v1/ping";
+
+    long startNs = System.nanoTime();
+    TelemetryReporter.sendPing(
+        "production",
+        "", // empty SDK endpoint: skip /health probe so we measure only the POST
+        Boolean.TRUE,
+        false,
+        false,
+        null, // DO_NOT_TRACK
+        null, // AXONFLOW_TELEMETRY
+        checkpointUrl);
+    long elapsedMs = (System.nanoTime() - startNs) / 1_000_000L;
+
+    // The fixed-delay mock forces a ~200ms round-trip. A synchronous implementation
+    // must have waited for it; a fire-and-forget implementation would have returned
+    // in well under 50ms. 150ms is the floor: generous slack for JVM scheduling /
+    // network setup on slow CI machines without losing the regression signal.
+    assertThat(elapsedMs)
+        .as(
+            "sendPing should have blocked long enough for the 200ms fixed-delay response "
+                + "to complete. An elapsed time under ~150ms strongly suggests a regression "
+                + "to the CompletableFuture.runAsync fire-and-forget pattern, which would "
+                + "drop the ping on JVM exit in short-lived processes (see #1706).")
+        .isGreaterThanOrEqualTo(150L);
+
+    // And: the ping actually landed on the mock.
+    info.getWireMock().verifyThat(postRequestedFor(urlEqualTo("/v1/ping")));
+  }
+}