Merge remote-tracking branch 'origin/main' into release/2026-04-29

# Conflicts:
#	CHANGELOG.md

Author: saurabhjain1592

.github/workflows/heartbeat-real-stack.yml

@@ -0,0 +1,73 @@
+name: heartbeat-real-stack
+
+# Real-stack heartbeat E2E across Linux + Windows + macOS. Stands up a
+# localhost fake checkpoint server, constructs the SDK through its
+# public API, verifies (a) the OS-native stamp file appears, (b) the
+# checkpoint endpoint received exactly one ping, (c) a second
+# invocation does NOT re-fire (warm-cache regression).
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  AXONFLOW_TELEMETRY: 'off'
+
+jobs:
+  real-stack:
+    name: real-stack ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '21'
+          cache: 'maven'
+
+      - name: Set up Python (for harness driver)
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Build SDK jar
+        # bash on every OS — PowerShell on Windows mangles -D... arguments,
+        # splitting `-Dmaven.javadoc.skip=true` into ".javadoc.skip=true" as
+        # a phase. The bash shell on Windows runners (Git Bash) handles -D
+        # quoting consistently with Linux/macOS.
+        shell: bash
+        run: mvn -B -DskipTests package -Dmaven.javadoc.skip=true
+
+      # Compile smoke + run real-stack E2E in a single shell so the
+      # classpath separator (`:` on Linux/macOS, `;` on Windows) is
+      # native to the shell and consistent across javac + java steps.
+      - name: Compile + run real-stack heartbeat E2E (cold + warm)
+        shell: bash
+        run: |
+          set -e
+          SDK_JAR=$(ls target/axonflow-sdk-*.jar | grep -v sources | head -1)
+          mvn -B dependency:build-classpath -Dmdep.outputFile=cp.txt -Dmdep.includeScope=runtime
+          DEPS=$(cat cp.txt)
+          # bash on Windows runners (Git Bash) handles ':' as the path
+          # separator inside the shell process, but `java` and `javac`
+          # are native Windows binaries that need ';'. Detect and rewrite.
+          if [[ "$RUNNER_OS" == "Windows" ]]; then
+            CP_SEP=';'
+          else
+            CP_SEP=':'
+          fi
+          mkdir -p tests/heartbeat-real-stack/build
+          javac -d tests/heartbeat-real-stack/build \
+            -cp "${SDK_JAR}${CP_SEP}${DEPS}" \
+            tests/heartbeat-real-stack/SmokeJava.java
+          CP="tests/heartbeat-real-stack/build${CP_SEP}${SDK_JAR}${CP_SEP}${DEPS}"
+          python tests/heartbeat-real-stack/run_real_stack.py java -cp "$CP" SmokeJava

.gitignore

@@ -99,3 +99,7 @@ local.properties
 
 .codex/
 .claude
+
+# Heartbeat real-stack smoke build dir
+tests/heartbeat-real-stack/build/
+tests/heartbeat-real-stack/cp.txt

CHANGELOG.md

@@ -5,21 +5,24 @@ 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).
 
-## [7.0.0] - 2026-04-29 — DO_NOT_TRACK removal
+## [7.0.0] - 2026-04-29 — DO_NOT_TRACK removal + 7-day delivered heartbeat
 
-Major release. The breaking change is the removal of `DO_NOT_TRACK` as an AxonFlow telemetry opt-out — `AXONFLOW_TELEMETRY=off` is now the canonical and only opt-out signal. Companion releases on the same day: TypeScript v7.0.0 / Python v7.0.0 / Go v7.0.0 (with `/v7` module path migration).
+Major release. Two headline changes: removal of `DO_NOT_TRACK` as an AxonFlow telemetry opt-out (`AXONFLOW_TELEMETRY=off` is now the canonical and only opt-out signal), and a move from "one ping per `new AxonFlow()`" to a 7-day delivered-heartbeat contract that better matches active-customer signal across both long-running services and short-lived CLI tools / Lambdas. Companion releases on the same day: TypeScript v7.0.0 / Python v7.0.0 / Go v7.0.0 (with `/v7` module path migration).
 
 ### BREAKING
 
 - **`DO_NOT_TRACK` is no longer honored as an AxonFlow telemetry opt-out.** Use `AXONFLOW_TELEMETRY=off` instead. `DO_NOT_TRACK` was deprecated because it is commonly inherited from host tools and developer environments (CLIs like Codex and Claude Code inject it unconditionally), which makes it an unreliable expression of user intent for AxonFlow telemetry.
 
 - **(Test API)** Package-private `TelemetryReporter.isEnabled` and `TelemetryReporter.sendPing` overloads no longer accept a `String doNotTrack` parameter. The remaining `String axonflowTelemetry` parameter is the sole opt-out signal accepted by the testability surface.
 
+### Changed
+
+- **Telemetry now follows the 7-day delivered-heartbeat contract** instead of firing on every `new AxonFlow()` construction. The SDK emits at most one anonymous heartbeat per environment every 7 days during SDK activity. A stamp file at the OS-native user cache dir tracks last successful delivery; mtime is the source of truth across process restarts. Failed POSTs do NOT advance the stamp — a transient network error does not silence telemetry for 7 days. An in-memory 1-hour cache caps `Files.getLastModifiedTime` calls on hot request paths; a `ReentrantLock`-guarded in-flight flag coalesces concurrent threads so only one ping fires under load. `AXONFLOW_TELEMETRY=off` is re-evaluated on every gate run. Restricted environments where no cache dir is available (e.g. AWS Lambda with no `HOME` / `LOCALAPPDATA`) fall back transparently to the previous "one ping per construction" behavior.
+
 ### Fixed
 
 - The one-line `DO_NOT_TRACK=1 is deprecated...` `logger.warn` is no longer emitted. Removing the warning eliminates log noise that previously appeared on every telemetry decision when `DO_NOT_TRACK=1` was set.
 
-
 ## [6.2.0] - 2026-04-28 — listLLMProviders() + LLMProvider source-compat
 
 Minor release. New LLM-provider listing API closes the parity gap with the Python + Go SDKs; the rest of the cycle restores `LLMProvider` source-compatibility for callers using the 7-arg primitive shape. Coordinated cycle: TypeScript v6.2.0 / Python v6.9.0 / Go v6.0.0 (major: see SDKCompatibility breaking type change in that release) ship same day.