fix(inkless-sync): use trunk merge base for --before-version

inkless-sync/README.md

@@ -56,13 +56,19 @@ Context for the agent:
 ./inkless-sync/main-sync.sh
 ```
 
-### Sync Before New Kafka Version
+### Pin main to a release-branch cut
 
 ```bash
-# Sync to the commit just before a version tag (e.g., before 4.3)
+# Last trunk commit that is also on apache/4.3 (4.3.0-SNAPSHOT).
+# Use this to cut inkless-4.3; do not pass 4.4.
 ./inkless-sync/main-sync.sh --before-version 4.3
 ```
 
+`--before-version 4.3` is the merge base of `apache/trunk` and `apache/4.3`, not a
+tag parent. Trunk commits after that cut never landed on `apache/4.3` (or landed
+later as cherry-picks with different SHAs). Merging them into main would put them
+on `inkless-4.3`.
+
 ### Dry Run (Preview)
 
 ```bash
@@ -147,7 +153,8 @@ For detailed cherry-pick workflow, conflict resolution patterns, and session tra
 
 ### Phase 1: Preparation
 1. Fetches upstream apache/kafka
-2. Determines sync target (trunk HEAD or before-version)
+2. Determines sync target (trunk HEAD, or trunk's merge base with the
+   `--before-version` release branch)
 3. Generates "inkless manifest" - list of files we've modified
 4. Creates sync branch: `sync/upstream-YYYYMMDD`
 

inkless-sync/lib/common.sh

@@ -105,10 +105,17 @@ get_base_version() {
     echo "$version"
 }
 
-# Check if a tag exists
+# Check if a tag (not a branch) exists
 tag_exists() {
     local tag="$1"
-    git rev-parse "$tag" &> /dev/null
+    git rev-parse --verify --quiet "refs/tags/${tag}" &> /dev/null
+}
+
+# Check if a branch exists, local or remote-tracking (not a tag)
+branch_exists() {
+    local branch="$1"
+    git rev-parse --verify --quiet "refs/heads/${branch}" &> /dev/null \
+        || git rev-parse --verify --quiet "refs/remotes/${branch}" &> /dev/null
 }
 
 # Get commit hash for a tag (dereference annotated tags)

inkless-sync/main-sync.sh

@@ -11,7 +11,8 @@
 #
 # Options:
 #   --target <ref>       Git ref to sync to (default: apache/trunk HEAD)
-#   --before-version <v> Find last commit before version tag (e.g., "4.3")
+#   --before-version <v> Sync to the trunk commit where release branch "v"
+#                        (e.g., "4.3") diverged from apache/trunk
 #   --dry-run           Show what would be done without making changes
 #   --help              Show this help message
 #
@@ -161,15 +162,16 @@ phase_prepare() {
 
     # Determine sync target
     if [[ -n "$BEFORE_VERSION" ]]; then
-        log_info "Finding last commit before version ${BEFORE_VERSION}..."
-        # Find the commit just before the version tag
-        if ! tag_exists "${BEFORE_VERSION}"; then
-            log_error "Tag ${BEFORE_VERSION} not found"
+        log_info "Finding merge base of ${APACHE_REMOTE}/trunk and ${APACHE_REMOTE}/${BEFORE_VERSION}..."
+        # The release branch (apache/$BEFORE_VERSION) can carry commits that
+        # never land on trunk. Use the merge base with trunk so the sync only
+        # picks up commits that are actually part of trunk history.
+        if ! branch_exists "${APACHE_REMOTE}/${BEFORE_VERSION}"; then
+            log_error "Branch ${APACHE_REMOTE}/${BEFORE_VERSION} not found"
             exit 1
         fi
-        # Get parent of the version tag
-        TARGET=$(git rev-parse "${BEFORE_VERSION}^")
-        log_info "Target: ${TARGET} (parent of ${BEFORE_VERSION})"
+        TARGET=$(git merge-base "${APACHE_REMOTE}/trunk" "${APACHE_REMOTE}/${BEFORE_VERSION}")
+        log_info "Target: ${TARGET} (merge base of ${APACHE_REMOTE}/trunk and ${APACHE_REMOTE}/${BEFORE_VERSION})"
     elif [[ -z "$TARGET" ]]; then
         TARGET="${APACHE_REMOTE}/trunk"
         log_info "Target: ${TARGET} (trunk HEAD)"
@@ -306,7 +308,7 @@ phase_merge() {
     # Attempt merge
     MERGE_MSG="merge: apache/kafka trunk"
     if [[ -n "$BEFORE_VERSION" ]]; then
-        MERGE_MSG="merge: apache/kafka trunk before ${BEFORE_VERSION}"
+        MERGE_MSG="merge: apache/kafka trunk before ${APACHE_REMOTE}/${BEFORE_VERSION} diverged"
     fi
 
     if git merge "$TARGET_COMMIT" -m "$MERGE_MSG" --no-edit --no-ff; then