From 80ddac1766820e320bc71fdf98e13d94c603253a Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sat, 17 Oct 2026 19:11:33 -1000
Subject: [PATCH 01/42] CI modernization: stage modernized build.yml at repo
 root (connector cannot write .github/workflows/ - to be renamed into place)

---
 build.yml | 203 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 203 insertions(+)
 create mode 100644 build.yml

diff --git a/build.yml b/build.yml
new file mode 100644
index 0000000..551806b
--- /dev/null
+++ b/build.yml
@@ -0,0 +1,203 @@
+name: build
+on: [push, pull_request]
+
+env:
+  APT_DEPS: libzstd-dev samtools tabix libhts-dev pigz python3-pip libcurl4-openssl-dev
+  BREW_DEPS: zstd samtools pigz coreutils sqlite
+  PIP_DEPS: pytest pytest-xdist
+
+jobs:
+
+  lint:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: deps
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y clang-format cppcheck python3-pip
+        sudo pip3 install --system --break-system-packages pre-commit $PIP_DEPS black flake8 pylint
+    - name: pre-commit
+      run: pre-commit run --all-files
+    - name: mvn spotless:check
+      run: mvn spotless:check -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+      with:
+        components: rustfmt, clippy
+    - name: rust lint
+      run: |
+        cd bindings/rust
+        ./cargo check --no-default-features
+        ./cargo fmt -- --check
+
+  test:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        BUILD_TYPE: [Debug, Release]
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: deps
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y $APT_DEPS
+        sudo pip3 install --system --break-system-packages $PIP_DEPS
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: build
+      run: cmake -DCMAKE_BUILD_TYPE=${{ matrix.BUILD_TYPE }} -B build . && cmake --build build -j $(nproc)
+    - name: test
+      run: env -C build SQLITE_WEB_LOG=99 ctest -V
+
+  linux-x86-64-so:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: build loaders
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y $APT_DEPS
+        sudo pip3 install --system --break-system-packages $PIP_DEPS
+        cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS='-D_GLIBCXX_USE_CXX11_ABI=0' -B build . && cmake --build build -j $(nproc)
+        rm build/libgenomicsqlite.so
+        sudo apt-get remove -y libzstd-dev  # should be linked into libgenomicsqlite.so
+    - name: build portable .so in docker
+      run: docker build -t genomicsqlite . && docker run -v $(pwd):/mnt --rm genomicsqlite cp /usr/local/lib/{libgenomicsqlite.so,libsqlite3.so.0} /mnt/build/
+    - name: symbols & digests
+      run: |
+        readelf -d build/libgenomicsqlite.so
+        ldd -r build/libgenomicsqlite.so
+        echo "----"
+        echo "libgenomicsqlite.so GLIBC version requirements:"
+        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBC_.*' | sort -Vr | head -n1
+        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBCXX_.*' | sort -Vr | head -n1
+        echo "libsqlite3.so.0 GLIBC version requirements:"
+        objdump -t build/libsqlite3.so.0 | grep -o 'GLIBC_.*' | sort -Vr | head -n1
+        echo "----"
+        sha256sum build/libgenomicsqlite.so build/libsqlite3.so.0
+        sudo cp build/libsqlite3.so.0 /usr/local/lib
+        sudo ldconfig
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: test portable .so
+      run: env -C build SQLITE_WEB_LOG=99 ctest -V
+    - name: test rust crate
+      run: |
+        set -e
+        cp build/libgenomicsqlite.so bindings/rust
+        SQLITE_WEB_LOG=99 bindings/rust/cargo test --release
+        bindings/rust/cargo package --list | grep libgenomicsqlite.so
+    - name: prepare artifacts
+      run: cp build/{libgenomicsqlite.so,libsqlite3.so.0} .
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libgenomicsqlite.so
+        path: libgenomicsqlite.so
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libsqlite3.so.0
+        path: libsqlite3.so.0
+
+  macOS-arm64-dylib:
+    runs-on: macos-15
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-python@v7
+      with:
+        python-version: '3.12'
+    - name: dependencies
+      run: |
+        rm -f $(brew --prefix)/bin/2to3  # https://github.com/pypa/pipenv/issues/3831
+        brew update || (sleep 2; brew update)
+        for dep in $BREW_DEPS ; do
+          brew install $dep || brew upgrade $dep
+        done
+
+        pip install $PIP_DEPS
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: build environment
+      run: |
+        echo "PATH=$(brew --prefix)/bin:$(brew --prefix)/opt/sqlite/bin:${PATH}" >> $GITHUB_ENV
+        echo "CFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "CXXFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "LDFLAGS=-L$(brew --prefix)/lib -L$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
+        # used by rusqlite:
+        echo "SQLITE3_INCLUDE_DIR=$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "SQLITE3_LIB_DIR=$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
+    - name: build
+      run: |
+        cmake -DCMAKE_BUILD_TYPE=Release \
+              -DCMAKE_PREFIX_PATH=$(brew --prefix)/opt/sqlite \
+              -B build .
+        cmake --build build -j 4
+    - name: symbols & digests
+      run: |
+        otool -L build/libgenomicsqlite.dylib
+        sha256sum build/libgenomicsqlite.dylib
+    - name: ctest
+      run: |
+        cd build
+        otool -L test/capi_smoke_test
+        SQLITE_WEB_LOG=99 ctest -V
+    - name: test rust crate
+      run: |
+        set -e
+        cp build/libgenomicsqlite.dylib bindings/rust
+        SQLITE_WEB_LOG=99 bindings/rust/cargo test --release
+        bindings/rust/cargo package --list | grep libgenomicsqlite.dylib
+    - name: prepare artifacts
+      run: cp build/libgenomicsqlite.dylib include/genomicsqlite.h .
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libgenomicsqlite.dylib
+        path: libgenomicsqlite.dylib
+
+  artifacts:
+    runs-on: ubuntu-24.04
+    needs: [linux-x86-64-so, macOS-arm64-dylib]
+    steps:
+    - uses: actions/checkout@v7
+    - name: fetch libgenomicsqlite.so
+      uses: actions/download-artifact@v8
+      with:
+        name: libgenomicsqlite.so
+    - name: fetch libsqlite3.so.0
+      uses: actions/download-artifact@v8
+      with:
+        name: libsqlite3.so.0
+    - name: fetch libgenomicsqlite.dylib
+      uses: actions/download-artifact@v8
+      with:
+        name: libgenomicsqlite.dylib
+    - name: detect GIT_REVISION
+      run: |
+        cp include/genomicsqlite.h .
+        echo "GIT_REVISION=$(git describe --tags --always)" >> $GITHUB_ENV
+    - uses: actions/upload-artifact@v7
+      with:
+        name: GenomicSQLite-${{ env.GIT_REVISION }}
+        path: |
+          LICENSE
+          genomicsqlite.h
+          libgenomicsqlite.so
+          libgenomicsqlite.dylib
+    - name: build jar
+      run: |
+        cp libgenomicsqlite.so libgenomicsqlite.dylib bindings/jdbc/genomicsqlite-jdbc/src/main/resources/
+        mvn deploy -Drevision=${{ env.GIT_REVISION }} -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
+    - name: digests
+      run: sha256sum *genomicsqlite* bindings/jdbc/genomicsqlite-jdbc/target/genomicsqlite*.jar libsqlite3.so.0
+    - uses: actions/upload-artifact@v7
+      with:
+        name: genomicsqlite-jdbc-${{ env.GIT_REVISION }}
+        path: bindings/jdbc/genomicsqlite-jdbc/target/mvn-repo

From b3ed1d804dee4cffc07ccc74d19e0a4b0b1e3e4d Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sat, 17 Oct 2026 19:14:52 -1000
Subject: [PATCH 02/42] CI modernization: remove old build.yml so the staged
 modernized file can be renamed into place

---
 .github/workflows/build.yml | 214 ------------------------------------
 1 file changed, 214 deletions(-)
 delete mode 100644 .github/workflows/build.yml

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
deleted file mode 100644
index c41822c..0000000
--- a/.github/workflows/build.yml
+++ /dev/null
@@ -1,214 +0,0 @@
-name: build
-on: [push, pull_request]
-
-env:
-  APT_DEPS: libzstd-dev samtools tabix libhts-dev pigz python3-pip libcurl4-openssl-dev
-  BREW_DEPS: zstd samtools pigz coreutils sqlite
-  PIP_DEPS: pytest pytest-xdist
-
-jobs:
-
-  lint:
-    runs-on: ubuntu-20.04
-    steps:
-    - uses: actions/checkout@v2
-      with:
-        fetch-depth: 0
-    - name: deps
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y clang-format cppcheck python3-pip
-        sudo pip3 install --system pre-commit $PIP_DEPS black flake8 pylint
-    - name: pre-commit
-      run: pre-commit run --all-files
-    - name: mvn spotless:check
-      run: mvn spotless:check -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
-    - name: rust toolchain
-      uses: actions-rs/toolchain@v1
-      with:
-        components: rustfmt, clippy
-        toolchain: stable
-        default: true
-    - name: rust lint
-      run: |
-        cd bindings/rust
-        ./cargo check --no-default-features
-        ./cargo fmt -- --check
-
-  test:
-    runs-on: ubuntu-20.04
-    strategy:
-      matrix:
-        BUILD_TYPE: [Debug, Release]
-    steps:
-    - uses: actions/checkout@v2
-      with:
-        fetch-depth: 0
-    - name: deps
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y $APT_DEPS
-        sudo pip3 install --system $PIP_DEPS
-    - name: rust toolchain
-      uses: actions-rs/toolchain@v1
-      with:
-        toolchain: stable
-        default: true
-    - name: build
-      run: cmake -DCMAKE_BUILD_TYPE=${{ matrix.BUILD_TYPE }} -B build . && cmake --build build -j $(nproc)
-    - name: test
-      run: env -C build SQLITE_WEB_LOG=99 ctest -V
-
-  linux-x86-64-so:
-    runs-on: ubuntu-20.04
-    steps:
-    - uses: actions/checkout@v2
-      with:
-        fetch-depth: 0
-    - name: build loaders
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y $APT_DEPS
-        sudo pip3 install --system $PIP_DEPS
-        cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS='-D_GLIBCXX_USE_CXX11_ABI=0' -B build . && cmake --build build -j $(nproc)
-        rm build/libgenomicsqlite.so
-        sudo apt-get remove -y libzstd-dev  # should be linked into libgenomicsqlite.so
-    - name: build portable .so in docker
-      run: docker build -t genomicsqlite . && docker run -v $(pwd):/mnt --rm genomicsqlite cp /usr/local/lib/{libgenomicsqlite.so,libsqlite3.so.0} /mnt/build/
-    - name: symbols & digests
-      run: |
-        readelf -d build/libgenomicsqlite.so
-        ldd -r build/libgenomicsqlite.so
-        echo "----"
-        echo "libgenomicsqlite.so GLIBC version requirements:"
-        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBC_.*' | sort -Vr | head -n1
-        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBCXX_.*' | sort -Vr | head -n1
-        echo "libsqlite3.so.0 GLIBC version requirements:"
-        objdump -t build/libsqlite3.so.0 | grep -o 'GLIBC_.*' | sort -Vr | head -n1
-        echo "----"
-        sha256sum build/libgenomicsqlite.so build/libsqlite3.so.0
-        sudo cp build/libsqlite3.so.0 /usr/local/lib
-        sudo ldconfig
-    - name: rust toolchain
-      uses: actions-rs/toolchain@v1
-      with:
-        toolchain: stable
-        default: true
-    - name: test portable .so
-      run: env -C build SQLITE_WEB_LOG=99 ctest -V
-    - name: test rust crate
-      run: |
-        set -e
-        cp build/libgenomicsqlite.so bindings/rust
-        SQLITE_WEB_LOG=99 bindings/rust/cargo test --release
-        bindings/rust/cargo package --list | grep libgenomicsqlite.so
-    - name: prepare artifacts
-      run: cp build/{libgenomicsqlite.so,libsqlite3.so.0} .
-    - uses: actions/upload-artifact@v2
-      with:
-        name: libgenomicsqlite.so
-        path: libgenomicsqlite.so
-    - uses: actions/upload-artifact@v2
-      with:
-        name: libsqlite3.so.0
-        path: libsqlite3.so.0
-
-  macOS-x86-64-dylib:
-    runs-on: macOS-11
-    steps:
-    - uses: actions/checkout@v2
-      with:
-        fetch-depth: 0
-    - uses: actions/setup-python@v4
-      with:
-        python-version: '3.8'
-    - name: dependencies
-      run: |
-        rm -f /usr/local/bin/2to3  # https://github.com/pypa/pipenv/issues/3831
-        brew update || (sleep 2; brew update)
-        for dep in $BREW_DEPS ; do
-          brew install $dep || brew upgrade $dep
-        done
-
-        pip install $PIP_DEPS
-    - name: rust toolchain
-      uses: actions-rs/toolchain@v1
-      with:
-        toolchain: stable
-        default: true
-    - name: build environment
-      run: |
-        echo "PATH=$(brew --prefix)/bin:$(brew --prefix)/opt/sqlite/bin:${PATH}" >> $GITHUB_ENV
-        echo "CFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include -march=ivybridge" >> $GITHUB_ENV
-        echo "CXXFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include -march=ivybridge" >> $GITHUB_ENV
-        echo "LDFLAGS=-L$(brew --prefix)/lib -L$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
-        # used by rusqlite:
-        echo "SQLITE3_INCLUDE_DIR=$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "SQLITE3_LIB_DIR=$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
-    - name: build
-      run: |
-        cmake -DCMAKE_BUILD_TYPE=Release \
-              -DCMAKE_PREFIX_PATH=$(brew --prefix)/opt/sqlite \
-              -B build .
-        cmake --build build -j 4
-    - name: symbols & digests
-      run: |
-        otool -L build/libgenomicsqlite.dylib
-        sha256sum build/libgenomicsqlite.dylib
-    - name: ctest
-      run: |
-        cd build
-        otool -L test/capi_smoke_test
-        SQLITE_WEB_LOG=99 ctest -V
-    - name: test rust crate
-      run: |
-        set -e
-        cp build/libgenomicsqlite.dylib bindings/rust
-        SQLITE_WEB_LOG=99 bindings/rust/cargo test --release
-        bindings/rust/cargo package --list | grep libgenomicsqlite.dylib
-    - name: prepare artifacts
-      run: cp build/libgenomicsqlite.dylib include/genomicsqlite.h .
-    - uses: actions/upload-artifact@v2
-      with:
-        name: libgenomicsqlite.dylib
-        path: libgenomicsqlite.dylib
-
-  artifacts:
-    runs-on: ubuntu-20.04
-    needs: [linux-x86-64-so, macOS-x86-64-dylib]
-    steps:
-    - uses: actions/checkout@v2
-    - name: fetch libgenomicsqlite.so
-      uses: actions/download-artifact@v2
-      with:
-        name: libgenomicsqlite.so
-    - name: fetch libsqlite3.so.0
-      uses: actions/download-artifact@v2
-      with:
-        name: libsqlite3.so.0
-    - name: fetch libgenomicsqlite.dylib
-      uses: actions/download-artifact@v2
-      with:
-        name: libgenomicsqlite.dylib
-    - name: detect GIT_REVISION
-      run: |
-        cp include/genomicsqlite.h .
-        echo "GIT_REVISION=$(git describe --tags --always)" >> $GITHUB_ENV
-    - uses: actions/upload-artifact@v2
-      with:
-        name: GenomicSQLite-${{ env.GIT_REVISION }}
-        path: |
-          LICENSE
-          genomicsqlite.h
-          libgenomicsqlite.so
-          libgenomicsqlite.dylib
-    - name: build jar
-      run: |
-        cp libgenomicsqlite.so libgenomicsqlite.dylib bindings/jdbc/genomicsqlite-jdbc/src/main/resources/
-        mvn deploy -Drevision=${{ env.GIT_REVISION }} -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
-    - name: digests
-      run: sha256sum *genomicsqlite* bindings/jdbc/genomicsqlite-jdbc/target/genomicsqlite*.jar libsqlite3.so.0
-    - uses: actions/upload-artifact@v2
-      with:
-        name: genomicsqlite-jdbc-${{ env.GIT_REVISION }}
-        path: bindings/jdbc/genomicsqlite-jdbc/target/mvn-repo

From 62f1957f89060ccbda1a85a610b5863c7dbe2665 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 05:16:40 +0000
Subject: [PATCH 03/42] Rename build.yml to .github/workflows/build.yml

---
 build.yml => .github/workflows/build.yml | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename build.yml => .github/workflows/build.yml (100%)

diff --git a/build.yml b/.github/workflows/build.yml
similarity index 100%
rename from build.yml
rename to .github/workflows/build.yml

From 2fef35f64e849450bc1d2c9aca2769d586592e41 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sat, 17 Oct 2026 19:39:14 -1000
Subject: [PATCH 04/42] bindings: fix Rust load_extension E0283; JDBC pom Java
 1.7 -> 1.8

rusqlite's load_extension gained a generic entry-point parameter
(bound: Name), so passing a bare None no longer infers (E0283 at
lib.rs:128 with rusqlite 0.40.2). Annotate None::<&str>; behavior
unchanged (default entry point). Verified locally: cargo test
--no-default-features passes in full against rusqlite 0.40.2
(2 integration tests + doc-test, 2026-10-17).

The JDBC pom targeted Java 1.7, which modern JDKs refuse
(javac 12+ dropped source/target 7). Bump maven.compiler.source/target
to 1.8, the modern minimum. Local Maven verification is blocked by
the sandbox JVM/proxy issue (runbook); CI will verify.
---
 bindings/jdbc/genomicsqlite-jdbc/pom.xml | 4 ++--
 bindings/rust/src/lib.rs                 | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/bindings/jdbc/genomicsqlite-jdbc/pom.xml b/bindings/jdbc/genomicsqlite-jdbc/pom.xml
index 5b1cdac..4dd64b4 100644
--- a/bindings/jdbc/genomicsqlite-jdbc/pom.xml
+++ b/bindings/jdbc/genomicsqlite-jdbc/pom.xml
@@ -44,8 +44,8 @@
 
   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <maven.compiler.source>1.7</maven.compiler.source>
-    <maven.compiler.target>1.7</maven.compiler.target>
+    <maven.compiler.source>1.8</maven.compiler.source>
+    <maven.compiler.target>1.8</maven.compiler.target>
   </properties>
 
   <dependencies>
diff --git a/bindings/rust/src/lib.rs b/bindings/rust/src/lib.rs
index 96d41cf..f999172 100644
--- a/bindings/rust/src/lib.rs
+++ b/bindings/rust/src/lib.rs
@@ -125,7 +125,7 @@ pub fn open<P: AsRef<Path>>(path: P, flags: OpenFlags, config: &Object) -> Resul
         let memconn = Connection::open_in_memory().unwrap();
         unsafe {
             let _guard = LoadExtensionGuard::new(&memconn).unwrap();
-            match memconn.load_extension(libgenomicsqlite.clone(), None) {
+            match memconn.load_extension(libgenomicsqlite.clone(), None::<&str>) {
                 Err(err) => panic!(
                     "genomicsqlite failed to load_extension(\"{}\"): {}",
                     libgenomicsqlite, err

From c6c60bd634d6526bffb1401be8dfc75d7030597a Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sat, 17 Oct 2026 19:39:28 -1000
Subject: [PATCH 05/42] CI fix STAGED at repo root (rename to
 .github/workflows/build.yml)

Drop libcurl4-openssl-dev from APT_DEPS (conflicts with libhts-dev's
libcurl4-gnutls-dev on Ubuntu 24.04; apt exit 100, conflict verified
against noble package metadata) and drop the invalid pip --system
flag from the lint/test/linux-x86-64-so installs (pip: no such
option, exit 2; verified with Ubuntu 24.04's pip 24.0).

Staged at the root because the connector cannot write workflow
paths; takes effect when renamed over .github/workflows/build.yml.
---
 build.yml | 203 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 203 insertions(+)
 create mode 100644 build.yml

diff --git a/build.yml b/build.yml
new file mode 100644
index 0000000..77cccd4
--- /dev/null
+++ b/build.yml
@@ -0,0 +1,203 @@
+name: build
+on: [push, pull_request]
+
+env:
+  APT_DEPS: libzstd-dev samtools tabix libhts-dev pigz python3-pip
+  BREW_DEPS: zstd samtools pigz coreutils sqlite
+  PIP_DEPS: pytest pytest-xdist
+
+jobs:
+
+  lint:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: deps
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y clang-format cppcheck python3-pip
+        sudo pip3 install --break-system-packages pre-commit $PIP_DEPS black flake8 pylint
+    - name: pre-commit
+      run: pre-commit run --all-files
+    - name: mvn spotless:check
+      run: mvn spotless:check -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+      with:
+        components: rustfmt, clippy
+    - name: rust lint
+      run: |
+        cd bindings/rust
+        ./cargo check --no-default-features
+        ./cargo fmt -- --check
+
+  test:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        BUILD_TYPE: [Debug, Release]
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: deps
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y $APT_DEPS
+        sudo pip3 install --break-system-packages $PIP_DEPS
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: build
+      run: cmake -DCMAKE_BUILD_TYPE=${{ matrix.BUILD_TYPE }} -B build . && cmake --build build -j $(nproc)
+    - name: test
+      run: env -C build SQLITE_WEB_LOG=99 ctest -V
+
+  linux-x86-64-so:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: build loaders
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y $APT_DEPS
+        sudo pip3 install --break-system-packages $PIP_DEPS
+        cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS='-D_GLIBCXX_USE_CXX11_ABI=0' -B build . && cmake --build build -j $(nproc)
+        rm build/libgenomicsqlite.so
+        sudo apt-get remove -y libzstd-dev  # should be linked into libgenomicsqlite.so
+    - name: build portable .so in docker
+      run: docker build -t genomicsqlite . && docker run -v $(pwd):/mnt --rm genomicsqlite cp /usr/local/lib/{libgenomicsqlite.so,libsqlite3.so.0} /mnt/build/
+    - name: symbols & digests
+      run: |
+        readelf -d build/libgenomicsqlite.so
+        ldd -r build/libgenomicsqlite.so
+        echo "----"
+        echo "libgenomicsqlite.so GLIBC version requirements:"
+        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBC_.*' | sort -Vr | head -n1
+        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBCXX_.*' | sort -Vr | head -n1
+        echo "libsqlite3.so.0 GLIBC version requirements:"
+        objdump -t build/libsqlite3.so.0 | grep -o 'GLIBC_.*' | sort -Vr | head -n1
+        echo "----"
+        sha256sum build/libgenomicsqlite.so build/libsqlite3.so.0
+        sudo cp build/libsqlite3.so.0 /usr/local/lib
+        sudo ldconfig
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: test portable .so
+      run: env -C build SQLITE_WEB_LOG=99 ctest -V
+    - name: test rust crate
+      run: |
+        set -e
+        cp build/libgenomicsqlite.so bindings/rust
+        SQLITE_WEB_LOG=99 bindings/rust/cargo test --release
+        bindings/rust/cargo package --list | grep libgenomicsqlite.so
+    - name: prepare artifacts
+      run: cp build/{libgenomicsqlite.so,libsqlite3.so.0} .
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libgenomicsqlite.so
+        path: libgenomicsqlite.so
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libsqlite3.so.0
+        path: libsqlite3.so.0
+
+  macOS-arm64-dylib:
+    runs-on: macos-15
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-python@v7
+      with:
+        python-version: '3.12'
+    - name: dependencies
+      run: |
+        rm -f $(brew --prefix)/bin/2to3  # https://github.com/pypa/pipenv/issues/3831
+        brew update || (sleep 2; brew update)
+        for dep in $BREW_DEPS ; do
+          brew install $dep || brew upgrade $dep
+        done
+
+        pip install $PIP_DEPS
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: build environment
+      run: |
+        echo "PATH=$(brew --prefix)/bin:$(brew --prefix)/opt/sqlite/bin:${PATH}" >> $GITHUB_ENV
+        echo "CFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "CXXFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "LDFLAGS=-L$(brew --prefix)/lib -L$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
+        # used by rusqlite:
+        echo "SQLITE3_INCLUDE_DIR=$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "SQLITE3_LIB_DIR=$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
+    - name: build
+      run: |
+        cmake -DCMAKE_BUILD_TYPE=Release \
+              -DCMAKE_PREFIX_PATH=$(brew --prefix)/opt/sqlite \
+              -B build .
+        cmake --build build -j 4
+    - name: symbols & digests
+      run: |
+        otool -L build/libgenomicsqlite.dylib
+        sha256sum build/libgenomicsqlite.dylib
+    - name: ctest
+      run: |
+        cd build
+        otool -L test/capi_smoke_test
+        SQLITE_WEB_LOG=99 ctest -V
+    - name: test rust crate
+      run: |
+        set -e
+        cp build/libgenomicsqlite.dylib bindings/rust
+        SQLITE_WEB_LOG=99 bindings/rust/cargo test --release
+        bindings/rust/cargo package --list | grep libgenomicsqlite.dylib
+    - name: prepare artifacts
+      run: cp build/libgenomicsqlite.dylib include/genomicsqlite.h .
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libgenomicsqlite.dylib
+        path: libgenomicsqlite.dylib
+
+  artifacts:
+    runs-on: ubuntu-24.04
+    needs: [linux-x86-64-so, macOS-arm64-dylib]
+    steps:
+    - uses: actions/checkout@v7
+    - name: fetch libgenomicsqlite.so
+      uses: actions/download-artifact@v8
+      with:
+        name: libgenomicsqlite.so
+    - name: fetch libsqlite3.so.0
+      uses: actions/download-artifact@v8
+      with:
+        name: libsqlite3.so.0
+    - name: fetch libgenomicsqlite.dylib
+      uses: actions/download-artifact@v8
+      with:
+        name: libgenomicsqlite.dylib
+    - name: detect GIT_REVISION
+      run: |
+        cp include/genomicsqlite.h .
+        echo "GIT_REVISION=$(git describe --tags --always)" >> $GITHUB_ENV
+    - uses: actions/upload-artifact@v7
+      with:
+        name: GenomicSQLite-${{ env.GIT_REVISION }}
+        path: |
+          LICENSE
+          genomicsqlite.h
+          libgenomicsqlite.so
+          libgenomicsqlite.dylib
+    - name: build jar
+      run: |
+        cp libgenomicsqlite.so libgenomicsqlite.dylib bindings/jdbc/genomicsqlite-jdbc/src/main/resources/
+        mvn deploy -Drevision=${{ env.GIT_REVISION }} -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
+    - name: digests
+      run: sha256sum *genomicsqlite* bindings/jdbc/genomicsqlite-jdbc/target/genomicsqlite*.jar libsqlite3.so.0
+    - uses: actions/upload-artifact@v7
+      with:
+        name: genomicsqlite-jdbc-${{ env.GIT_REVISION }}
+        path: bindings/jdbc/genomicsqlite-jdbc/target/mvn-repo

From ab84b015da07371c813a941e8cc3a6a2c9ad3b07 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sat, 17 Oct 2026 19:40:23 -1000
Subject: [PATCH 06/42] CI fix: remove current workflow file so the staged fix
 (repo root) can be renamed into place

---
 .github/workflows/build.yml | 203 ------------------------------------
 1 file changed, 203 deletions(-)
 delete mode 100644 .github/workflows/build.yml

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
deleted file mode 100644
index 551806b..0000000
--- a/.github/workflows/build.yml
+++ /dev/null
@@ -1,203 +0,0 @@
-name: build
-on: [push, pull_request]
-
-env:
-  APT_DEPS: libzstd-dev samtools tabix libhts-dev pigz python3-pip libcurl4-openssl-dev
-  BREW_DEPS: zstd samtools pigz coreutils sqlite
-  PIP_DEPS: pytest pytest-xdist
-
-jobs:
-
-  lint:
-    runs-on: ubuntu-24.04
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: deps
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y clang-format cppcheck python3-pip
-        sudo pip3 install --system --break-system-packages pre-commit $PIP_DEPS black flake8 pylint
-    - name: pre-commit
-      run: pre-commit run --all-files
-    - name: mvn spotless:check
-      run: mvn spotless:check -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-      with:
-        components: rustfmt, clippy
-    - name: rust lint
-      run: |
-        cd bindings/rust
-        ./cargo check --no-default-features
-        ./cargo fmt -- --check
-
-  test:
-    runs-on: ubuntu-24.04
-    strategy:
-      matrix:
-        BUILD_TYPE: [Debug, Release]
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: deps
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y $APT_DEPS
-        sudo pip3 install --system --break-system-packages $PIP_DEPS
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: build
-      run: cmake -DCMAKE_BUILD_TYPE=${{ matrix.BUILD_TYPE }} -B build . && cmake --build build -j $(nproc)
-    - name: test
-      run: env -C build SQLITE_WEB_LOG=99 ctest -V
-
-  linux-x86-64-so:
-    runs-on: ubuntu-24.04
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: build loaders
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y $APT_DEPS
-        sudo pip3 install --system --break-system-packages $PIP_DEPS
-        cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS='-D_GLIBCXX_USE_CXX11_ABI=0' -B build . && cmake --build build -j $(nproc)
-        rm build/libgenomicsqlite.so
-        sudo apt-get remove -y libzstd-dev  # should be linked into libgenomicsqlite.so
-    - name: build portable .so in docker
-      run: docker build -t genomicsqlite . && docker run -v $(pwd):/mnt --rm genomicsqlite cp /usr/local/lib/{libgenomicsqlite.so,libsqlite3.so.0} /mnt/build/
-    - name: symbols & digests
-      run: |
-        readelf -d build/libgenomicsqlite.so
-        ldd -r build/libgenomicsqlite.so
-        echo "----"
-        echo "libgenomicsqlite.so GLIBC version requirements:"
-        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBC_.*' | sort -Vr | head -n1
-        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBCXX_.*' | sort -Vr | head -n1
-        echo "libsqlite3.so.0 GLIBC version requirements:"
-        objdump -t build/libsqlite3.so.0 | grep -o 'GLIBC_.*' | sort -Vr | head -n1
-        echo "----"
-        sha256sum build/libgenomicsqlite.so build/libsqlite3.so.0
-        sudo cp build/libsqlite3.so.0 /usr/local/lib
-        sudo ldconfig
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: test portable .so
-      run: env -C build SQLITE_WEB_LOG=99 ctest -V
-    - name: test rust crate
-      run: |
-        set -e
-        cp build/libgenomicsqlite.so bindings/rust
-        SQLITE_WEB_LOG=99 bindings/rust/cargo test --release
-        bindings/rust/cargo package --list | grep libgenomicsqlite.so
-    - name: prepare artifacts
-      run: cp build/{libgenomicsqlite.so,libsqlite3.so.0} .
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libgenomicsqlite.so
-        path: libgenomicsqlite.so
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libsqlite3.so.0
-        path: libsqlite3.so.0
-
-  macOS-arm64-dylib:
-    runs-on: macos-15
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - uses: actions/setup-python@v7
-      with:
-        python-version: '3.12'
-    - name: dependencies
-      run: |
-        rm -f $(brew --prefix)/bin/2to3  # https://github.com/pypa/pipenv/issues/3831
-        brew update || (sleep 2; brew update)
-        for dep in $BREW_DEPS ; do
-          brew install $dep || brew upgrade $dep
-        done
-
-        pip install $PIP_DEPS
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: build environment
-      run: |
-        echo "PATH=$(brew --prefix)/bin:$(brew --prefix)/opt/sqlite/bin:${PATH}" >> $GITHUB_ENV
-        echo "CFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "CXXFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "LDFLAGS=-L$(brew --prefix)/lib -L$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
-        # used by rusqlite:
-        echo "SQLITE3_INCLUDE_DIR=$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "SQLITE3_LIB_DIR=$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
-    - name: build
-      run: |
-        cmake -DCMAKE_BUILD_TYPE=Release \
-              -DCMAKE_PREFIX_PATH=$(brew --prefix)/opt/sqlite \
-              -B build .
-        cmake --build build -j 4
-    - name: symbols & digests
-      run: |
-        otool -L build/libgenomicsqlite.dylib
-        sha256sum build/libgenomicsqlite.dylib
-    - name: ctest
-      run: |
-        cd build
-        otool -L test/capi_smoke_test
-        SQLITE_WEB_LOG=99 ctest -V
-    - name: test rust crate
-      run: |
-        set -e
-        cp build/libgenomicsqlite.dylib bindings/rust
-        SQLITE_WEB_LOG=99 bindings/rust/cargo test --release
-        bindings/rust/cargo package --list | grep libgenomicsqlite.dylib
-    - name: prepare artifacts
-      run: cp build/libgenomicsqlite.dylib include/genomicsqlite.h .
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libgenomicsqlite.dylib
-        path: libgenomicsqlite.dylib
-
-  artifacts:
-    runs-on: ubuntu-24.04
-    needs: [linux-x86-64-so, macOS-arm64-dylib]
-    steps:
-    - uses: actions/checkout@v7
-    - name: fetch libgenomicsqlite.so
-      uses: actions/download-artifact@v8
-      with:
-        name: libgenomicsqlite.so
-    - name: fetch libsqlite3.so.0
-      uses: actions/download-artifact@v8
-      with:
-        name: libsqlite3.so.0
-    - name: fetch libgenomicsqlite.dylib
-      uses: actions/download-artifact@v8
-      with:
-        name: libgenomicsqlite.dylib
-    - name: detect GIT_REVISION
-      run: |
-        cp include/genomicsqlite.h .
-        echo "GIT_REVISION=$(git describe --tags --always)" >> $GITHUB_ENV
-    - uses: actions/upload-artifact@v7
-      with:
-        name: GenomicSQLite-${{ env.GIT_REVISION }}
-        path: |
-          LICENSE
-          genomicsqlite.h
-          libgenomicsqlite.so
-          libgenomicsqlite.dylib
-    - name: build jar
-      run: |
-        cp libgenomicsqlite.so libgenomicsqlite.dylib bindings/jdbc/genomicsqlite-jdbc/src/main/resources/
-        mvn deploy -Drevision=${{ env.GIT_REVISION }} -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
-    - name: digests
-      run: sha256sum *genomicsqlite* bindings/jdbc/genomicsqlite-jdbc/target/genomicsqlite*.jar libsqlite3.so.0
-    - uses: actions/upload-artifact@v7
-      with:
-        name: genomicsqlite-jdbc-${{ env.GIT_REVISION }}
-        path: bindings/jdbc/genomicsqlite-jdbc/target/mvn-repo

From 22cc3f559aae5c0b5776e2ab160d479de2fbb738 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sat, 17 Oct 2026 19:58:52 -1000
Subject: [PATCH 07/42] Rename build.yml to .github/workflows/build.yml

---
 build.yml => .github/workflows/build.yml | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename build.yml => .github/workflows/build.yml (100%)

diff --git a/build.yml b/.github/workflows/build.yml
similarity index 100%
rename from build.yml
rename to .github/workflows/build.yml

From e8d911952d3a1aed2a1ca3984136f5a3f5906235 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sat, 17 Oct 2026 20:29:56 -1000
Subject: [PATCH 08/42] build: raise CMAKE_POLICY_VERSION_MINIMUM to 3.5 for
 CMake 4

CMake 4 removed compatibility with projects declaring cmake_minimum_required() below 3.5; the pinned SQLiteCpp fetched via FetchContent declares 3.1, so configure fails outright under CMake 4 (e.g. the macos-15 runner image, CMake 4.4.4) in a matter of seconds. Setting CMAKE_POLICY_VERSION_MINIMUM=3.5 before FetchContent raises the policy-version floor for the fetched subprojects. Verified locally: CMake 4.4.4 configure+build green with the change (and the failure reproduced without it); CMake 3.28 configure unaffected.
---
 CMakeLists.txt | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 1bc5852..6878daf 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -3,6 +3,13 @@ if(${CMAKE_VERSION} VERSION_LESS 3.12)
     cmake_policy(VERSION ${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION})
 endif()
 
+# CMake 4 removed compatibility with projects declaring
+# cmake_minimum_required() below 3.5; the pinned SQLiteCpp fetched
+# below declares 3.1, which makes configure fail outright under
+# CMake 4 (e.g. the macos-15 runner image). Raise the policy-version
+# floor for fetched subprojects; harmless under older CMake.
+set(CMAKE_POLICY_VERSION_MINIMUM 3.5)
+
 include(FetchContent)
 
 if(${CMAKE_VERSION} VERSION_LESS 3.14)

From 8d80b1fd5d982917a5c9941213f34043973a56a5 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sat, 17 Oct 2026 20:40:06 -1000
Subject: [PATCH 09/42] CI: install lint tools into a dedicated venv

The lint deps step's system-wide pip install fails on the current ubuntu-24.04 runner image (exit 1 in ~15s, both repos, while the identical commands succeed on a stock Ubuntu 24.04 image and the test jobs' smaller pip installs succeed on the runner). Install the lint toolchain (pre-commit, black, flake8, pylint, test deps) into an isolated venv instead of fighting the runner image's system-python state, and put it on PATH for the later steps via GITHUB_PATH. Adds python3-venv to the apt line so the venv can be created. Verified in a stock ubuntu:24.04 container: apt, venv creation, pip install, and pre-commit all succeed.
---
 build.yml | 205 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 205 insertions(+)
 create mode 100644 build.yml

diff --git a/build.yml b/build.yml
new file mode 100644
index 0000000..d189a1b
--- /dev/null
+++ b/build.yml
@@ -0,0 +1,205 @@
+name: build
+on: [push, pull_request]
+
+env:
+  APT_DEPS: libzstd-dev samtools tabix libhts-dev pigz python3-pip
+  BREW_DEPS: zstd samtools pigz coreutils sqlite
+  PIP_DEPS: pytest pytest-xdist
+
+jobs:
+
+  lint:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: deps
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y clang-format cppcheck python3-pip python3-venv
+        python3 -m venv "$HOME/.lint-venv"
+        "$HOME/.lint-venv/bin/pip" install pre-commit $PIP_DEPS black flake8 pylint
+        echo "$HOME/.lint-venv/bin" >> "$GITHUB_PATH"
+    - name: pre-commit
+      run: pre-commit run --all-files
+    - name: mvn spotless:check
+      run: mvn spotless:check -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+      with:
+        components: rustfmt, clippy
+    - name: rust lint
+      run: |
+        cd bindings/rust
+        ./cargo check --no-default-features
+        ./cargo fmt -- --check
+
+  test:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        BUILD_TYPE: [Debug, Release]
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: deps
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y $APT_DEPS
+        sudo pip3 install --break-system-packages $PIP_DEPS
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: build
+      run: cmake -DCMAKE_BUILD_TYPE=${{ matrix.BUILD_TYPE }} -B build . && cmake --build build -j $(nproc)
+    - name: test
+      run: env -C build SQLITE_WEB_LOG=99 ctest -V
+
+  linux-x86-64-so:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: build loaders
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y $APT_DEPS
+        sudo pip3 install --break-system-packages $PIP_DEPS
+        cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS='-D_GLIBCXX_USE_CXX11_ABI=0' -B build . && cmake --build build -j $(nproc)
+        rm build/libgenomicsqlite.so
+        sudo apt-get remove -y libzstd-dev  # should be linked into libgenomicsqlite.so
+    - name: build portable .so in docker
+      run: docker build -t genomicsqlite . && docker run -v $(pwd):/mnt --rm genomicsqlite cp /usr/local/lib/{libgenomicsqlite.so,libsqlite3.so.0} /mnt/build/
+    - name: symbols & digests
+      run: |
+        readelf -d build/libgenomicsqlite.so
+        ldd -r build/libgenomicsqlite.so
+        echo "----"
+        echo "libgenomicsqlite.so GLIBC version requirements:"
+        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBC_.*' | sort -Vr | head -n1
+        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBCXX_.*' | sort -Vr | head -n1
+        echo "libsqlite3.so.0 GLIBC version requirements:"
+        objdump -t build/libsqlite3.so.0 | grep -o 'GLIBC_.*' | sort -Vr | head -n1
+        echo "----"
+        sha256sum build/libgenomicsqlite.so build/libsqlite3.so.0
+        sudo cp build/libsqlite3.so.0 /usr/local/lib
+        sudo ldconfig
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: test portable .so
+      run: env -C build SQLITE_WEB_LOG=99 ctest -V
+    - name: test rust crate
+      run: |
+        set -e
+        cp build/libgenomicsqlite.so bindings/rust
+        SQLITE_WEB_LOG=99 bindings/rust/cargo test --release
+        bindings/rust/cargo package --list | grep libgenomicsqlite.so
+    - name: prepare artifacts
+      run: cp build/{libgenomicsqlite.so,libsqlite3.so.0} .
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libgenomicsqlite.so
+        path: libgenomicsqlite.so
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libsqlite3.so.0
+        path: libsqlite3.so.0
+
+  macOS-arm64-dylib:
+    runs-on: macos-15
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-python@v7
+      with:
+        python-version: '3.12'
+    - name: dependencies
+      run: |
+        rm -f $(brew --prefix)/bin/2to3  # https://github.com/pypa/pipenv/issues/3831
+        brew update || (sleep 2; brew update)
+        for dep in $BREW_DEPS ; do
+          brew install $dep || brew upgrade $dep
+        done
+
+        pip install $PIP_DEPS
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: build environment
+      run: |
+        echo "PATH=$(brew --prefix)/bin:$(brew --prefix)/opt/sqlite/bin:${PATH}" >> $GITHUB_ENV
+        echo "CFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "CXXFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "LDFLAGS=-L$(brew --prefix)/lib -L$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
+        # used by rusqlite:
+        echo "SQLITE3_INCLUDE_DIR=$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "SQLITE3_LIB_DIR=$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
+    - name: build
+      run: |
+        cmake -DCMAKE_BUILD_TYPE=Release \
+              -DCMAKE_PREFIX_PATH=$(brew --prefix)/opt/sqlite \
+              -B build .
+        cmake --build build -j 4
+    - name: symbols & digests
+      run: |
+        otool -L build/libgenomicsqlite.dylib
+        sha256sum build/libgenomicsqlite.dylib
+    - name: ctest
+      run: |
+        cd build
+        otool -L test/capi_smoke_test
+        SQLITE_WEB_LOG=99 ctest -V
+    - name: test rust crate
+      run: |
+        set -e
+        cp build/libgenomicsqlite.dylib bindings/rust
+        SQLITE_WEB_LOG=99 bindings/rust/cargo test --release
+        bindings/rust/cargo package --list | grep libgenomicsqlite.dylib
+    - name: prepare artifacts
+      run: cp build/libgenomicsqlite.dylib include/genomicsqlite.h .
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libgenomicsqlite.dylib
+        path: libgenomicsqlite.dylib
+
+  artifacts:
+    runs-on: ubuntu-24.04
+    needs: [linux-x86-64-so, macOS-arm64-dylib]
+    steps:
+    - uses: actions/checkout@v7
+    - name: fetch libgenomicsqlite.so
+      uses: actions/download-artifact@v8
+      with:
+        name: libgenomicsqlite.so
+    - name: fetch libsqlite3.so.0
+      uses: actions/download-artifact@v8
+      with:
+        name: libsqlite3.so.0
+    - name: fetch libgenomicsqlite.dylib
+      uses: actions/download-artifact@v8
+      with:
+        name: libgenomicsqlite.dylib
+    - name: detect GIT_REVISION
+      run: |
+        cp include/genomicsqlite.h .
+        echo "GIT_REVISION=$(git describe --tags --always)" >> $GITHUB_ENV
+    - uses: actions/upload-artifact@v7
+      with:
+        name: GenomicSQLite-${{ env.GIT_REVISION }}
+        path: |
+          LICENSE
+          genomicsqlite.h
+          libgenomicsqlite.so
+          libgenomicsqlite.dylib
+    - name: build jar
+      run: |
+        cp libgenomicsqlite.so libgenomicsqlite.dylib bindings/jdbc/genomicsqlite-jdbc/src/main/resources/
+        mvn deploy -Drevision=${{ env.GIT_REVISION }} -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
+    - name: digests
+      run: sha256sum *genomicsqlite* bindings/jdbc/genomicsqlite-jdbc/target/genomicsqlite*.jar libsqlite3.so.0
+    - uses: actions/upload-artifact@v7
+      with:
+        name: genomicsqlite-jdbc-${{ env.GIT_REVISION }}
+        path: bindings/jdbc/genomicsqlite-jdbc/target/mvn-repo

From aded5d1061cc412a93d646c221edeec649552869 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sat, 17 Oct 2026 20:40:13 -1000
Subject: [PATCH 10/42] CI: remove live workflow so the staged venv-lint update
 can be renamed into place

---
 .github/workflows/build.yml | 203 ------------------------------------
 1 file changed, 203 deletions(-)
 delete mode 100644 .github/workflows/build.yml

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
deleted file mode 100644
index 77cccd4..0000000
--- a/.github/workflows/build.yml
+++ /dev/null
@@ -1,203 +0,0 @@
-name: build
-on: [push, pull_request]
-
-env:
-  APT_DEPS: libzstd-dev samtools tabix libhts-dev pigz python3-pip
-  BREW_DEPS: zstd samtools pigz coreutils sqlite
-  PIP_DEPS: pytest pytest-xdist
-
-jobs:
-
-  lint:
-    runs-on: ubuntu-24.04
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: deps
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y clang-format cppcheck python3-pip
-        sudo pip3 install --break-system-packages pre-commit $PIP_DEPS black flake8 pylint
-    - name: pre-commit
-      run: pre-commit run --all-files
-    - name: mvn spotless:check
-      run: mvn spotless:check -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-      with:
-        components: rustfmt, clippy
-    - name: rust lint
-      run: |
-        cd bindings/rust
-        ./cargo check --no-default-features
-        ./cargo fmt -- --check
-
-  test:
-    runs-on: ubuntu-24.04
-    strategy:
-      matrix:
-        BUILD_TYPE: [Debug, Release]
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: deps
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y $APT_DEPS
-        sudo pip3 install --break-system-packages $PIP_DEPS
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: build
-      run: cmake -DCMAKE_BUILD_TYPE=${{ matrix.BUILD_TYPE }} -B build . && cmake --build build -j $(nproc)
-    - name: test
-      run: env -C build SQLITE_WEB_LOG=99 ctest -V
-
-  linux-x86-64-so:
-    runs-on: ubuntu-24.04
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: build loaders
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y $APT_DEPS
-        sudo pip3 install --break-system-packages $PIP_DEPS
-        cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS='-D_GLIBCXX_USE_CXX11_ABI=0' -B build . && cmake --build build -j $(nproc)
-        rm build/libgenomicsqlite.so
-        sudo apt-get remove -y libzstd-dev  # should be linked into libgenomicsqlite.so
-    - name: build portable .so in docker
-      run: docker build -t genomicsqlite . && docker run -v $(pwd):/mnt --rm genomicsqlite cp /usr/local/lib/{libgenomicsqlite.so,libsqlite3.so.0} /mnt/build/
-    - name: symbols & digests
-      run: |
-        readelf -d build/libgenomicsqlite.so
-        ldd -r build/libgenomicsqlite.so
-        echo "----"
-        echo "libgenomicsqlite.so GLIBC version requirements:"
-        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBC_.*' | sort -Vr | head -n1
-        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBCXX_.*' | sort -Vr | head -n1
-        echo "libsqlite3.so.0 GLIBC version requirements:"
-        objdump -t build/libsqlite3.so.0 | grep -o 'GLIBC_.*' | sort -Vr | head -n1
-        echo "----"
-        sha256sum build/libgenomicsqlite.so build/libsqlite3.so.0
-        sudo cp build/libsqlite3.so.0 /usr/local/lib
-        sudo ldconfig
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: test portable .so
-      run: env -C build SQLITE_WEB_LOG=99 ctest -V
-    - name: test rust crate
-      run: |
-        set -e
-        cp build/libgenomicsqlite.so bindings/rust
-        SQLITE_WEB_LOG=99 bindings/rust/cargo test --release
-        bindings/rust/cargo package --list | grep libgenomicsqlite.so
-    - name: prepare artifacts
-      run: cp build/{libgenomicsqlite.so,libsqlite3.so.0} .
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libgenomicsqlite.so
-        path: libgenomicsqlite.so
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libsqlite3.so.0
-        path: libsqlite3.so.0
-
-  macOS-arm64-dylib:
-    runs-on: macos-15
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - uses: actions/setup-python@v7
-      with:
-        python-version: '3.12'
-    - name: dependencies
-      run: |
-        rm -f $(brew --prefix)/bin/2to3  # https://github.com/pypa/pipenv/issues/3831
-        brew update || (sleep 2; brew update)
-        for dep in $BREW_DEPS ; do
-          brew install $dep || brew upgrade $dep
-        done
-
-        pip install $PIP_DEPS
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: build environment
-      run: |
-        echo "PATH=$(brew --prefix)/bin:$(brew --prefix)/opt/sqlite/bin:${PATH}" >> $GITHUB_ENV
-        echo "CFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "CXXFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "LDFLAGS=-L$(brew --prefix)/lib -L$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
-        # used by rusqlite:
-        echo "SQLITE3_INCLUDE_DIR=$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "SQLITE3_LIB_DIR=$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
-    - name: build
-      run: |
-        cmake -DCMAKE_BUILD_TYPE=Release \
-              -DCMAKE_PREFIX_PATH=$(brew --prefix)/opt/sqlite \
-              -B build .
-        cmake --build build -j 4
-    - name: symbols & digests
-      run: |
-        otool -L build/libgenomicsqlite.dylib
-        sha256sum build/libgenomicsqlite.dylib
-    - name: ctest
-      run: |
-        cd build
-        otool -L test/capi_smoke_test
-        SQLITE_WEB_LOG=99 ctest -V
-    - name: test rust crate
-      run: |
-        set -e
-        cp build/libgenomicsqlite.dylib bindings/rust
-        SQLITE_WEB_LOG=99 bindings/rust/cargo test --release
-        bindings/rust/cargo package --list | grep libgenomicsqlite.dylib
-    - name: prepare artifacts
-      run: cp build/libgenomicsqlite.dylib include/genomicsqlite.h .
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libgenomicsqlite.dylib
-        path: libgenomicsqlite.dylib
-
-  artifacts:
-    runs-on: ubuntu-24.04
-    needs: [linux-x86-64-so, macOS-arm64-dylib]
-    steps:
-    - uses: actions/checkout@v7
-    - name: fetch libgenomicsqlite.so
-      uses: actions/download-artifact@v8
-      with:
-        name: libgenomicsqlite.so
-    - name: fetch libsqlite3.so.0
-      uses: actions/download-artifact@v8
-      with:
-        name: libsqlite3.so.0
-    - name: fetch libgenomicsqlite.dylib
-      uses: actions/download-artifact@v8
-      with:
-        name: libgenomicsqlite.dylib
-    - name: detect GIT_REVISION
-      run: |
-        cp include/genomicsqlite.h .
-        echo "GIT_REVISION=$(git describe --tags --always)" >> $GITHUB_ENV
-    - uses: actions/upload-artifact@v7
-      with:
-        name: GenomicSQLite-${{ env.GIT_REVISION }}
-        path: |
-          LICENSE
-          genomicsqlite.h
-          libgenomicsqlite.so
-          libgenomicsqlite.dylib
-    - name: build jar
-      run: |
-        cp libgenomicsqlite.so libgenomicsqlite.dylib bindings/jdbc/genomicsqlite-jdbc/src/main/resources/
-        mvn deploy -Drevision=${{ env.GIT_REVISION }} -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
-    - name: digests
-      run: sha256sum *genomicsqlite* bindings/jdbc/genomicsqlite-jdbc/target/genomicsqlite*.jar libsqlite3.so.0
-    - uses: actions/upload-artifact@v7
-      with:
-        name: genomicsqlite-jdbc-${{ env.GIT_REVISION }}
-        path: bindings/jdbc/genomicsqlite-jdbc/target/mvn-repo

From b409a7713442933ad37ef157bc54d7264aabd544 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 06:45:12 +0000
Subject: [PATCH 11/42] Rename build.yml to .github/workflows/build.yml

---
 build.yml => .github/workflows/build.yml | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename build.yml => .github/workflows/build.yml (100%)

diff --git a/build.yml b/.github/workflows/build.yml
similarity index 100%
rename from build.yml
rename to .github/workflows/build.yml

From a497f42d33ca6a97f0f21892645274141f3d7391 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sat, 17 Oct 2026 20:55:43 -1000
Subject: [PATCH 12/42] Fix JdbcTests POM ${revision} default and cargo wrapper
 tag-less checkout failure

- pom.xml: define a default <revision> property (0.9.4-SNAPSHOT). Maven >= 3.9.10 (the ubuntu-24.04 runner's 3.9.11) refuses to read the POM at all when ${revision} is undefined; -Drevision override still works. Exact CI error reproduced locally pre-fix with Maven 3.9.11; POM parses post-fix.
- bindings/rust/cargo + test/cargo_smoke_test/cargo (identical wrappers): git describe --tags dies under set -e in tag-less checkouts (actions/checkout fetches no tags), failing cargo_test in 0.00s. Fall back to the latest release version with the short SHA as prerelease suffix (valid semver) when no tag is found. Verified in a tag-less shallow clone: full cargo test passes; tagged-checkout behavior unchanged.
---
 bindings/jdbc/genomicsqlite-jdbc/pom.xml | 4 ++++
 bindings/rust/cargo                      | 9 ++++++++-
 test/cargo_smoke_test/cargo              | 9 ++++++++-
 3 files changed, 20 insertions(+), 2 deletions(-)
 mode change 100755 => 100644 bindings/rust/cargo
 mode change 100755 => 100644 test/cargo_smoke_test/cargo

diff --git a/bindings/jdbc/genomicsqlite-jdbc/pom.xml b/bindings/jdbc/genomicsqlite-jdbc/pom.xml
index 4dd64b4..efab490 100644
--- a/bindings/jdbc/genomicsqlite-jdbc/pom.xml
+++ b/bindings/jdbc/genomicsqlite-jdbc/pom.xml
@@ -43,6 +43,10 @@
   </distributionManagement>
 
   <properties>
+    <!-- default for the CI-friendly ${revision} version placeholder above;
+         release builds may override with -Drevision=... (Maven >= 3.9.10
+         refuses to even read the POM when the property is undefined) -->
+    <revision>0.9.4-SNAPSHOT</revision>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <maven.compiler.source>1.8</maven.compiler.source>
     <maven.compiler.target>1.8</maven.compiler.target>
diff --git a/bindings/rust/cargo b/bindings/rust/cargo
old mode 100755
new mode 100644
index 0aaa6bf..9056fd3
--- a/bindings/rust/cargo
+++ b/bindings/rust/cargo
@@ -4,7 +4,14 @@
 set -e
 cd `dirname $0`
 
-revision="$(git describe --tags --dirty)"
+revision="$(git describe --tags --dirty 2>/dev/null || true)"
+if [ -z "$revision" ]; then
+    # Tag-less checkout (e.g. actions/checkout fetches no tags): fall back to the
+    # latest release version with the short commit SHA as a prerelease suffix,
+    # keeping the generated crate version valid semver. (Update the release
+    # version here when cutting a new release.)
+    revision="0.9.4-$(git rev-parse --short HEAD)"
+fi
 revision="${revision#v}"  # strip 'v' prefix
 >&2 echo "$revision"
 
diff --git a/test/cargo_smoke_test/cargo b/test/cargo_smoke_test/cargo
old mode 100755
new mode 100644
index 0aaa6bf..9056fd3
--- a/test/cargo_smoke_test/cargo
+++ b/test/cargo_smoke_test/cargo
@@ -4,7 +4,14 @@
 set -e
 cd `dirname $0`
 
-revision="$(git describe --tags --dirty)"
+revision="$(git describe --tags --dirty 2>/dev/null || true)"
+if [ -z "$revision" ]; then
+    # Tag-less checkout (e.g. actions/checkout fetches no tags): fall back to the
+    # latest release version with the short commit SHA as a prerelease suffix,
+    # keeping the generated crate version valid semver. (Update the release
+    # version here when cutting a new release.)
+    revision="0.9.4-$(git rev-parse --short HEAD)"
+fi
 revision="${revision#v}"  # strip 'v' prefix
 >&2 echo "$revision"
 

From 22b060a47648e510d0b1200129c91c1ba4bd13e9 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sat, 17 Oct 2026 22:08:48 -1000
Subject: [PATCH 13/42] Reformat once with current tools; fix small lint
 findings

Mike's formatter ruling (2026-10-17): one-time reformat with current tools instead of pinning era formatter versions. Tool versions (the same unpinned installs the CI lint venv makes): clang-format 18.1.3, black 26.10.1, flake8 7.4.1, pylint 4.1.3, pre-commit 4.7.0.

- clang-format: src/genomicsqlite.cc, loaders/vcf_into_sqlite.cc
- black: bindings/python/genomicsqlite/__init__.py, bindings/python/version.py, test/genomicsqlite_smoke_test.py, test/test_bam.py, test/test_ext.py, test/test_gri.py, test/test_vcf_lines.py
- flake8 E226 (missing whitespace around arithmetic operator): test/test_txdb.py, test/test_gri.py
- pylint R0917 too-many-positional-arguments (new in pylint 3.3) flags three established public API functions in bindings/python/genomicsqlite/__init__.py; added to the existing -d list in .pre-commit-config.yaml next to the already-disabled sibling check too-many-arguments. No signature changes (positional callers must keep working).
- pylint E0401 in bindings/python/setup.py: line-targeted import-error disable; setuptools is present by construction when setup.py runs, but is not installed in the lint venv.

Verified locally in the CI lint-venv shape: pre-commit run --all-files green (all hooks pass); Release build + smoke/capi/pytest ctest entries 100% passed.
---
 .pre-commit-config.yaml                   |  2 +-
 bindings/python/genomicsqlite/__init__.py |  1 +
 bindings/python/setup.py                  |  2 +-
 bindings/python/version.py                |  1 -
 loaders/vcf_into_sqlite.cc                |  6 ++----
 src/genomicsqlite.cc                      | 13 ++++++------
 test/genomicsqlite_smoke_test.py          |  1 +
 test/test_bam.py                          |  8 ++-----
 test/test_ext.py                          |  6 ++----
 test/test_gri.py                          | 26 ++++++++---------------
 test/test_txdb.py                         |  2 +-
 test/test_vcf_lines.py                    |  1 -
 12 files changed, 26 insertions(+), 43 deletions(-)
 mode change 100755 => 100644 bindings/python/genomicsqlite/__init__.py
 mode change 100755 => 100644 bindings/python/setup.py
 mode change 100755 => 100644 test/genomicsqlite_smoke_test.py

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index c6a30e0..269465d 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -38,4 +38,4 @@ repos:
     exclude: version\.py
     verbose: true
     entry: env PYTHONPATH=bindings/python pylint
-    args: [-d, "global-statement,missing-docstring,missing-module-docstring,line-too-long,too-many-arguments,duplicate-code,redefined-outer-name,too-many-locals,bare-except,broad-except,import-outside-toplevel,protected-access,too-many-statements,too-many-branches,unspecified-encoding"]
+    args: [-d, "global-statement,missing-docstring,missing-module-docstring,line-too-long,too-many-arguments,too-many-positional-arguments,duplicate-code,redefined-outer-name,too-many-locals,bare-except,broad-except,import-outside-toplevel,protected-access,too-many-statements,too-many-branches,unspecified-encoding"]
diff --git a/bindings/python/genomicsqlite/__init__.py b/bindings/python/genomicsqlite/__init__.py
old mode 100755
new mode 100644
index ea9f3cf..ec9c82a
--- a/bindings/python/genomicsqlite/__init__.py
+++ b/bindings/python/genomicsqlite/__init__.py
@@ -2,6 +2,7 @@
 """
 GenomicSQLite Python binding
 """
+
 import os
 import sys
 import platform
diff --git a/bindings/python/setup.py b/bindings/python/setup.py
old mode 100755
new mode 100644
index 13b2af2..82dfa62
--- a/bindings/python/setup.py
+++ b/bindings/python/setup.py
@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 from os import path
-from setuptools import setup, find_packages
+from setuptools import setup, find_packages  # pylint: disable=import-error
 from version import get_version
 
 HERE = path.abspath(path.dirname(__file__))
diff --git a/bindings/python/version.py b/bindings/python/version.py
index ddd2328..5b7cfd8 100644
--- a/bindings/python/version.py
+++ b/bindings/python/version.py
@@ -48,7 +48,6 @@
 import subprocess
 import sys
 
-
 RELEASE_VERSION_FILE = "RELEASE-VERSION"
 
 # http://www.python.org/dev/peps/pep-0386/
diff --git a/loaders/vcf_into_sqlite.cc b/loaders/vcf_into_sqlite.cc
index f3b0eb8..359f469 100644
--- a/loaders/vcf_into_sqlite.cc
+++ b/loaders/vcf_into_sqlite.cc
@@ -67,8 +67,7 @@ string schemaDDL(const string &table_prefix, vector<map<string, string>> &info_h
         }
 
         // add SQL comment with original metadata
-        out << "  --  "
-            << "Number=" << hrec["Number"] << ",Type=" << hrec["Type"];
+        out << "  --  " << "Number=" << hrec["Number"] << ",Type=" << hrec["Type"];
         auto desc = hrec.find("Description");
         if (desc != hrec.end() && !desc->second.empty()) {
             out << ",Description=" << desc->second;
@@ -109,8 +108,7 @@ string schemaDDL(const string &table_prefix, vector<map<string, string>> &info_h
                 }
 
                 // add SQL comment with original metadata
-                out << "  --  "
-                    << "Number=" << hrec["Number"] << ",Type=" << hrec["Type"];
+                out << "  --  " << "Number=" << hrec["Number"] << ",Type=" << hrec["Type"];
                 auto desc = hrec.find("Description");
                 if (desc != hrec.end() && !desc->second.empty()) {
                     out << ",Description=" << desc->second;
diff --git a/src/genomicsqlite.cc b/src/genomicsqlite.cc
index f94c475..d5a8c07 100644
--- a/src/genomicsqlite.cc
+++ b/src/genomicsqlite.cc
@@ -639,10 +639,10 @@ string GenomicRangeRowidsSQL(sqlite3 *dbconn, const string &indexed_table, const
             lvq << "\n  UNION ALL\n  ";
         }
         const string &it = indexed_table;
-        lvq << "SELECT _rowid_ FROM " << it << " INDEXED BY " << table << "__gri WHERE"
-            << "\n   (" << it << "._gri_rid," << it << "._gri_lvl," << it << "._gri_beg) BETWEEN (("
-            << qrid << "),-" << lv << ",(" << qbeg << ")-0x1" << string(lv, '0') << ") AND (("
-            << qrid << "),-" << lv << ",(" << qend << ")-0)" // (*)
+        lvq << "SELECT _rowid_ FROM " << it << " INDEXED BY " << table << "__gri WHERE" << "\n   ("
+            << it << "._gri_rid," << it << "._gri_lvl," << it << "._gri_beg) BETWEEN ((" << qrid
+            << "),-" << lv << ",(" << qbeg << ")-0x1" << string(lv, '0') << ") AND ((" << qrid
+            << "),-" << lv << ",(" << qend << ")-0)" // (*)
             << "\n   AND (" << it << "._gri_beg+" << it << "._gri_len) >= (" << qbeg << ")";
         /*
          * (*) For some reason, we have to obfuscate qend a little (such as with unary *+*, or by
@@ -1023,9 +1023,8 @@ static string gri_refseq_ddl(const string &schema) {
     out << "CREATE TABLE IF NOT EXISTS " << schema_prefix << "_gri_refseq"
         << "(_gri_rid INTEGER NOT NULL PRIMARY KEY, gri_refseq_name TEXT NOT NULL, gri_assembly TEXT,"
         << " gri_refget_id TEXT UNIQUE, gri_refseq_length INTEGER NOT NULL, gri_refseq_meta_json TEXT NOT NULL DEFAULT '{}', "
-        << "UNIQUE(gri_assembly,gri_refseq_name))"
-        << ";\nCREATE INDEX IF NOT EXISTS " << schema_prefix << "_gri_refseq_name ON "
-        << "_gri_refseq(gri_refseq_name)";
+        << "UNIQUE(gri_assembly,gri_refseq_name))" << ";\nCREATE INDEX IF NOT EXISTS "
+        << schema_prefix << "_gri_refseq_name ON " << "_gri_refseq(gri_refseq_name)";
     return out.str();
 }
 
diff --git a/test/genomicsqlite_smoke_test.py b/test/genomicsqlite_smoke_test.py
old mode 100755
new mode 100644
index 9264fcf..9baf123
--- a/test/genomicsqlite_smoke_test.py
+++ b/test/genomicsqlite_smoke_test.py
@@ -3,6 +3,7 @@
 Display platform, environment, & version info for debugging GenomicSQLite installation. Load a
 small test database and check GRI query plan on it.
 """
+
 import sys
 import time
 import os
diff --git a/test/test_bam.py b/test/test_bam.py
index 81f0b99..0748485 100644
--- a/test/test_bam.py
+++ b/test/test_bam.py
@@ -55,14 +55,10 @@ def test_bam(tmp_path):
     count = next(con.execute("SELECT COUNT(DISTINCT qname) FROM NA12878_reads_seqs"))[0]
     assert count == 299205
 
-    mq_hist = dict(
-        con.execute(
-            """
+    mq_hist = dict(con.execute("""
             SELECT mq, COUNT(*) as count FROM
                 (SELECT ifnull(json_extract(tags_json, '$.MQ'),0) AS mq
                 FROM NA12878_reads NATURAL JOIN NA12878_reads_tags WHERE (flag & 3840) = 0)
             GROUP BY mq ORDER BY mq DESC
-            """
-        )
-    )
+            """))
     assert (mq_hist[0], mq_hist[60]) == (2734, 520522)
diff --git a/test/test_ext.py b/test/test_ext.py
index 79bc99c..29dcd55 100644
--- a/test/test_ext.py
+++ b/test/test_ext.py
@@ -4,14 +4,12 @@
 def test_bundled_extensions():
     con = genomicsqlite.connect(":memory:")
 
-    con.executescript(
-        """
+    con.executescript("""
         CREATE TABLE test(json TEXT);
         INSERT INTO test(json) VALUES('{"chrom":"chr10"}');
         INSERT INTO test(json) VALUES('{"chrom":"chr2"}');
         INSERT INTO test(json) VALUES('{"chrom":"chrMT"}');
-        """
-    )
+        """)
 
     results = con.execute(
         "SELECT json_extract(json,'$.chrom') AS chrom FROM test ORDER BY chrom COLLATE UINT"
diff --git a/test/test_gri.py b/test/test_gri.py
index d34c777..3ab2cda 100644
--- a/test/test_gri.py
+++ b/test/test_gri.py
@@ -104,7 +104,7 @@ def test_abutment():
     query = genomicsqlite.genomic_range_rowids_sql(
         con, "features", "42", str(pos0), str(pos0 + 123)
     )[1:-1]
-    control_query = f"SELECT _rowid_ FROM features NOT INDEXED WHERE rid = 42 AND NOT (end < {pos0} OR beg > {pos0+123}) ORDER BY _rowid_"
+    control_query = f"SELECT _rowid_ FROM features NOT INDEXED WHERE rid = 42 AND NOT (end < {pos0} OR beg > {pos0 + 123}) ORDER BY _rowid_"
     assert list(con.execute(query)) == list(con.execute(control_query))
 
 
@@ -148,12 +148,10 @@ def fanout(query):
 
     assert fanout(query) == 1
 
-    con.executescript(
-        """
+    con.executescript("""
         INSERT INTO features VALUES(44, 1048568, 1048584);
         INSERT INTO features VALUES(44, 0, 64000)
-        """
-    )
+        """)
     query = genomicsqlite.genomic_range_rowids_sql(con, "features")[1:-1]
     print("\n" + query)
     assert "-4," in query and "-0x10000)" in query
@@ -168,30 +166,24 @@ def fanout(query):
         == 4
     )
 
-    con.executescript(
-        """
+    con.executescript("""
         INSERT INTO features VALUES(43, NULL, 10000000000);
         INSERT INTO features VALUES(44, 0, NULL)
-        """
-    )
+        """)
     assert fanout(genomicsqlite.genomic_range_rowids_sql(con, "features")[1:-1]) == 4
 
-    con.executescript(
-        """
+    con.executescript("""
         INSERT INTO features VALUES(43, 0, 10000000000);
         INSERT INTO features VALUES(43, 32, 33)
-        """
-    )
+        """)
     query = genomicsqlite.genomic_range_rowids_sql(con, "features")[1:-1]
     print("\n" + query)
     assert fanout(query) == 10
 
-    con.executescript(
-        """
+    con.executescript("""
         INSERT INTO features VALUES(43, 0, 10000000000);
         INSERT INTO features VALUES(43, 32, 32)
-        """
-    )
+        """)
     query = genomicsqlite.genomic_range_rowids_sql(con, "features")[1:-1]
     assert fanout(query) == 10
     assert len(list(con.execute(query, (43, 32, 33)))) == 4
diff --git a/test/test_txdb.py b/test/test_txdb.py
index 3f7bd83..b96bb52 100644
--- a/test/test_txdb.py
+++ b/test/test_txdb.py
@@ -12,7 +12,7 @@
 def txdb(tmp_path):
     ans = str(tmp_path / "TxDb.Hsapiens.UCSC.hg38.knownGene.sqlite")
     subprocess.run(
-        f"pigz -dc {HERE+'/data/TxDb.Hsapiens.UCSC.hg38.knownGene.sqlite.gz'} > {ans}",
+        f"pigz -dc {HERE + '/data/TxDb.Hsapiens.UCSC.hg38.knownGene.sqlite.gz'} > {ans}",
         shell=True,
         check=True,
     )
diff --git a/test/test_vcf_lines.py b/test/test_vcf_lines.py
index dab3b59..7ebdb91 100644
--- a/test/test_vcf_lines.py
+++ b/test/test_vcf_lines.py
@@ -4,7 +4,6 @@
 import genomicsqlite
 import pytest
 
-
 HERE = os.path.dirname(__file__)
 BUILD = os.path.abspath(os.path.join(HERE, "..", "build"))
 

From 249d32d542085be6ef862b98c9c4670cb40d9403 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sat, 17 Oct 2026 22:30:21 -1000
Subject: [PATCH 14/42] JDBC: bump spotless-maven-plugin 2.3.1 -> 3.10.4
 (bundled google-java-format 1.9 cannot run on JDK >= 16); GJF reformat of
 GenomicSQLite.java + JdbcDriver.java (Mike ruling 2026-10-17)

---
 bindings/jdbc/genomicsqlite-jdbc/pom.xml                  | 2 +-
 .../main/java/net/mlin/genomicsqlite/GenomicSQLite.java   | 3 ++-
 .../src/main/java/net/mlin/genomicsqlite/JdbcDriver.java  | 8 ++++++--
 3 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/bindings/jdbc/genomicsqlite-jdbc/pom.xml b/bindings/jdbc/genomicsqlite-jdbc/pom.xml
index efab490..63b4894 100644
--- a/bindings/jdbc/genomicsqlite-jdbc/pom.xml
+++ b/bindings/jdbc/genomicsqlite-jdbc/pom.xml
@@ -114,7 +114,7 @@
         <plugin>
           <groupId>com.diffplug.spotless</groupId>
           <artifactId>spotless-maven-plugin</artifactId>
-          <version>2.3.1</version>
+          <version>3.10.4</version>
           <configuration>
             <java>
               <includes>
diff --git a/bindings/jdbc/genomicsqlite-jdbc/src/main/java/net/mlin/genomicsqlite/GenomicSQLite.java b/bindings/jdbc/genomicsqlite-jdbc/src/main/java/net/mlin/genomicsqlite/GenomicSQLite.java
index c7ae92c..cc353cf 100644
--- a/bindings/jdbc/genomicsqlite-jdbc/src/main/java/net/mlin/genomicsqlite/GenomicSQLite.java
+++ b/bindings/jdbc/genomicsqlite-jdbc/src/main/java/net/mlin/genomicsqlite/GenomicSQLite.java
@@ -156,7 +156,8 @@ public static String putReferenceSequenceSQL(Connection conn, String name, long
   public static HashMap<Long, ReferenceSequence> getReferenceSequencesByRid(
       Connection conn, String assembly, String schema) throws SQLException {
     String sql =
-        "SELECT _gri_rid, gri_refseq_name, gri_refseq_length, gri_assembly, gri_refget_id, gri_refseq_meta_json FROM ";
+        "SELECT _gri_rid, gri_refseq_name, gri_refseq_length, gri_assembly, gri_refget_id,"
+            + " gri_refseq_meta_json FROM ";
     if (schema != null && schema.length() > 0) {
       sql += schema + ".";
     }
diff --git a/bindings/jdbc/genomicsqlite-jdbc/src/main/java/net/mlin/genomicsqlite/JdbcDriver.java b/bindings/jdbc/genomicsqlite-jdbc/src/main/java/net/mlin/genomicsqlite/JdbcDriver.java
index 3fc605a..fcd501e 100644
--- a/bindings/jdbc/genomicsqlite-jdbc/src/main/java/net/mlin/genomicsqlite/JdbcDriver.java
+++ b/bindings/jdbc/genomicsqlite-jdbc/src/main/java/net/mlin/genomicsqlite/JdbcDriver.java
@@ -40,7 +40,9 @@ public class JdbcDriver extends org.sqlite.JDBC {
     }
   }
 
-  /** @see java.sql.Driver#acceptsURL(java.lang.String) */
+  /**
+   * @see java.sql.Driver#acceptsURL(java.lang.String)
+   */
   @Override
   public boolean acceptsURL(String url) {
     return isValidURL(url);
@@ -56,7 +58,9 @@ public static boolean isValidURL(String url) {
     return url != null && url.toLowerCase().startsWith(PREFIX);
   }
 
-  /** @see java.sql.Driver#connect(java.lang.String, java.util.Properties) */
+  /**
+   * @see java.sql.Driver#connect(java.lang.String, java.util.Properties)
+   */
   @Override
   public Connection connect(String url, Properties info) throws SQLException {
     return createConnection(url, info);

From e6f034123ff741125427381e735fa43e4e785c1b Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sat, 17 Oct 2026 22:39:34 -1000
Subject: [PATCH 15/42] Restore executable bit on bindings/rust/cargo (content
 unchanged; mode-only attempt via create_or_update_file)


From 2bc77c4bd7416307f9933b0673f8815b569b8df6 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sat, 17 Oct 2026 22:39:52 -1000
Subject: [PATCH 16/42] Restore executable bit on bindings/rust/cargo (content
 unchanged; mode-only attempt via push_files)


From efa86bdc0d9e3ff28cb41aef3f72455c58758db6 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sat, 17 Oct 2026 22:42:46 -1000
Subject: [PATCH 17/42] Work around stripped executable bit on
 bindings/rust/cargo

Connector content-writes reset file modes to 100644 (verified empirically:
both create_or_update_file and push_files leave the mode at 100644, and every
file the connector has rewritten on this branch lost its 100755 bit).
The cargo wrapper therefore cannot be executed by path (EACCES/exit 126).

- CMakeLists.txt: invoke the wrapper through bash in the cargo_test ctest
  registration (content of the wrapper unchanged).
- build.yml STAGED at repo root (rename into .github/workflows/ pending):
  all six by-path wrapper invocations (rust lint step, linux-x86-64-so and
  macOS-arm64-dylib 'test rust crate' steps) now go through bash.
---
 CMakeLists.txt |   2 +-
 build.yml      | 205 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 206 insertions(+), 1 deletion(-)
 create mode 100644 build.yml

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 6878daf..6d67d4d 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -80,6 +80,6 @@ if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
     add_test(NAME smoke_test COMMAND ${GENOMICSQLITE_TEST_ENV} python3 ${CMAKE_CURRENT_SOURCE_DIR}/test/genomicsqlite_smoke_test.py)
     add_test(NAME capi_smoke_test COMMAND ${GENOMICSQLITE_TEST_ENV} ${CMAKE_BINARY_DIR}/test/capi_smoke_test)
     add_test(NAME JdbcTests COMMAND ${GENOMICSQLITE_TEST_ENV} mvn test -B -f ${CMAKE_CURRENT_SOURCE_DIR}/bindings/jdbc/genomicsqlite-jdbc/pom.xml)
-    add_test(NAME cargo_test COMMAND ${GENOMICSQLITE_TEST_ENV} ${CMAKE_CURRENT_SOURCE_DIR}/bindings/rust/cargo test --no-default-features)
+    add_test(NAME cargo_test COMMAND ${GENOMICSQLITE_TEST_ENV} bash ${CMAKE_CURRENT_SOURCE_DIR}/bindings/rust/cargo test --no-default-features)
     add_test(NAME pytest COMMAND ${GENOMICSQLITE_TEST_ENV} python3 -m pytest -xv -n 4 --tb=short ${CMAKE_CURRENT_SOURCE_DIR}/test)
 endif()
diff --git a/build.yml b/build.yml
new file mode 100644
index 0000000..9e69bbe
--- /dev/null
+++ b/build.yml
@@ -0,0 +1,205 @@
+name: build
+on: [push, pull_request]
+
+env:
+  APT_DEPS: libzstd-dev samtools tabix libhts-dev pigz python3-pip
+  BREW_DEPS: zstd samtools pigz coreutils sqlite
+  PIP_DEPS: pytest pytest-xdist
+
+jobs:
+
+  lint:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: deps
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y clang-format cppcheck python3-pip python3-venv
+        python3 -m venv "$HOME/.lint-venv"
+        "$HOME/.lint-venv/bin/pip" install pre-commit $PIP_DEPS black flake8 pylint
+        echo "$HOME/.lint-venv/bin" >> "$GITHUB_PATH"
+    - name: pre-commit
+      run: pre-commit run --all-files
+    - name: mvn spotless:check
+      run: mvn spotless:check -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+      with:
+        components: rustfmt, clippy
+    - name: rust lint
+      run: |
+        cd bindings/rust
+        bash ./cargo check --no-default-features
+        bash ./cargo fmt -- --check
+
+  test:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        BUILD_TYPE: [Debug, Release]
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: deps
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y $APT_DEPS
+        sudo pip3 install --break-system-packages $PIP_DEPS
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: build
+      run: cmake -DCMAKE_BUILD_TYPE=${{ matrix.BUILD_TYPE }} -B build . && cmake --build build -j $(nproc)
+    - name: test
+      run: env -C build SQLITE_WEB_LOG=99 ctest -V
+
+  linux-x86-64-so:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: build loaders
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y $APT_DEPS
+        sudo pip3 install --break-system-packages $PIP_DEPS
+        cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS='-D_GLIBCXX_USE_CXX11_ABI=0' -B build . && cmake --build build -j $(nproc)
+        rm build/libgenomicsqlite.so
+        sudo apt-get remove -y libzstd-dev  # should be linked into libgenomicsqlite.so
+    - name: build portable .so in docker
+      run: docker build -t genomicsqlite . && docker run -v $(pwd):/mnt --rm genomicsqlite cp /usr/local/lib/{libgenomicsqlite.so,libsqlite3.so.0} /mnt/build/
+    - name: symbols & digests
+      run: |
+        readelf -d build/libgenomicsqlite.so
+        ldd -r build/libgenomicsqlite.so
+        echo "----"
+        echo "libgenomicsqlite.so GLIBC version requirements:"
+        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBC_.*' | sort -Vr | head -n1
+        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBCXX_.*' | sort -Vr | head -n1
+        echo "libsqlite3.so.0 GLIBC version requirements:"
+        objdump -t build/libsqlite3.so.0 | grep -o 'GLIBC_.*' | sort -Vr | head -n1
+        echo "----"
+        sha256sum build/libgenomicsqlite.so build/libsqlite3.so.0
+        sudo cp build/libsqlite3.so.0 /usr/local/lib
+        sudo ldconfig
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: test portable .so
+      run: env -C build SQLITE_WEB_LOG=99 ctest -V
+    - name: test rust crate
+      run: |
+        set -e
+        cp build/libgenomicsqlite.so bindings/rust
+        SQLITE_WEB_LOG=99 bash bindings/rust/cargo test --release
+        bash bindings/rust/cargo package --list | grep libgenomicsqlite.so
+    - name: prepare artifacts
+      run: cp build/{libgenomicsqlite.so,libsqlite3.so.0} .
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libgenomicsqlite.so
+        path: libgenomicsqlite.so
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libsqlite3.so.0
+        path: libsqlite3.so.0
+
+  macOS-arm64-dylib:
+    runs-on: macos-15
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-python@v7
+      with:
+        python-version: '3.12'
+    - name: dependencies
+      run: |
+        rm -f $(brew --prefix)/bin/2to3  # https://github.com/pypa/pipenv/issues/3831
+        brew update || (sleep 2; brew update)
+        for dep in $BREW_DEPS ; do
+          brew install $dep || brew upgrade $dep
+        done
+
+        pip install $PIP_DEPS
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: build environment
+      run: |
+        echo "PATH=$(brew --prefix)/bin:$(brew --prefix)/opt/sqlite/bin:${PATH}" >> $GITHUB_ENV
+        echo "CFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "CXXFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "LDFLAGS=-L$(brew --prefix)/lib -L$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
+        # used by rusqlite:
+        echo "SQLITE3_INCLUDE_DIR=$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "SQLITE3_LIB_DIR=$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
+    - name: build
+      run: |
+        cmake -DCMAKE_BUILD_TYPE=Release \
+              -DCMAKE_PREFIX_PATH=$(brew --prefix)/opt/sqlite \
+              -B build .
+        cmake --build build -j 4
+    - name: symbols & digests
+      run: |
+        otool -L build/libgenomicsqlite.dylib
+        sha256sum build/libgenomicsqlite.dylib
+    - name: ctest
+      run: |
+        cd build
+        otool -L test/capi_smoke_test
+        SQLITE_WEB_LOG=99 ctest -V
+    - name: test rust crate
+      run: |
+        set -e
+        cp build/libgenomicsqlite.dylib bindings/rust
+        SQLITE_WEB_LOG=99 bash bindings/rust/cargo test --release
+        bash bindings/rust/cargo package --list | grep libgenomicsqlite.dylib
+    - name: prepare artifacts
+      run: cp build/libgenomicsqlite.dylib include/genomicsqlite.h .
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libgenomicsqlite.dylib
+        path: libgenomicsqlite.dylib
+
+  artifacts:
+    runs-on: ubuntu-24.04
+    needs: [linux-x86-64-so, macOS-arm64-dylib]
+    steps:
+    - uses: actions/checkout@v7
+    - name: fetch libgenomicsqlite.so
+      uses: actions/download-artifact@v8
+      with:
+        name: libgenomicsqlite.so
+    - name: fetch libsqlite3.so.0
+      uses: actions/download-artifact@v8
+      with:
+        name: libsqlite3.so.0
+    - name: fetch libgenomicsqlite.dylib
+      uses: actions/download-artifact@v8
+      with:
+        name: libgenomicsqlite.dylib
+    - name: detect GIT_REVISION
+      run: |
+        cp include/genomicsqlite.h .
+        echo "GIT_REVISION=$(git describe --tags --always)" >> $GITHUB_ENV
+    - uses: actions/upload-artifact@v7
+      with:
+        name: GenomicSQLite-${{ env.GIT_REVISION }}
+        path: |
+          LICENSE
+          genomicsqlite.h
+          libgenomicsqlite.so
+          libgenomicsqlite.dylib
+    - name: build jar
+      run: |
+        cp libgenomicsqlite.so libgenomicsqlite.dylib bindings/jdbc/genomicsqlite-jdbc/src/main/resources/
+        mvn deploy -Drevision=${{ env.GIT_REVISION }} -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
+    - name: digests
+      run: sha256sum *genomicsqlite* bindings/jdbc/genomicsqlite-jdbc/target/genomicsqlite*.jar libsqlite3.so.0
+    - uses: actions/upload-artifact@v7
+      with:
+        name: genomicsqlite-jdbc-${{ env.GIT_REVISION }}
+        path: bindings/jdbc/genomicsqlite-jdbc/target/mvn-repo

From f3e4e3b44d3677c93d494678a3e9fdeb8194f385 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sat, 17 Oct 2026 22:48:56 -1000
Subject: [PATCH 18/42] CI: remove live workflow so the staged bash-invocation
 update (repo-root build.yml) can be renamed into place

---
 .github/workflows/build.yml | 205 ------------------------------------
 1 file changed, 205 deletions(-)
 delete mode 100644 .github/workflows/build.yml

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
deleted file mode 100644
index d189a1b..0000000
--- a/.github/workflows/build.yml
+++ /dev/null
@@ -1,205 +0,0 @@
-name: build
-on: [push, pull_request]
-
-env:
-  APT_DEPS: libzstd-dev samtools tabix libhts-dev pigz python3-pip
-  BREW_DEPS: zstd samtools pigz coreutils sqlite
-  PIP_DEPS: pytest pytest-xdist
-
-jobs:
-
-  lint:
-    runs-on: ubuntu-24.04
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: deps
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y clang-format cppcheck python3-pip python3-venv
-        python3 -m venv "$HOME/.lint-venv"
-        "$HOME/.lint-venv/bin/pip" install pre-commit $PIP_DEPS black flake8 pylint
-        echo "$HOME/.lint-venv/bin" >> "$GITHUB_PATH"
-    - name: pre-commit
-      run: pre-commit run --all-files
-    - name: mvn spotless:check
-      run: mvn spotless:check -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-      with:
-        components: rustfmt, clippy
-    - name: rust lint
-      run: |
-        cd bindings/rust
-        ./cargo check --no-default-features
-        ./cargo fmt -- --check
-
-  test:
-    runs-on: ubuntu-24.04
-    strategy:
-      matrix:
-        BUILD_TYPE: [Debug, Release]
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: deps
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y $APT_DEPS
-        sudo pip3 install --break-system-packages $PIP_DEPS
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: build
-      run: cmake -DCMAKE_BUILD_TYPE=${{ matrix.BUILD_TYPE }} -B build . && cmake --build build -j $(nproc)
-    - name: test
-      run: env -C build SQLITE_WEB_LOG=99 ctest -V
-
-  linux-x86-64-so:
-    runs-on: ubuntu-24.04
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: build loaders
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y $APT_DEPS
-        sudo pip3 install --break-system-packages $PIP_DEPS
-        cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS='-D_GLIBCXX_USE_CXX11_ABI=0' -B build . && cmake --build build -j $(nproc)
-        rm build/libgenomicsqlite.so
-        sudo apt-get remove -y libzstd-dev  # should be linked into libgenomicsqlite.so
-    - name: build portable .so in docker
-      run: docker build -t genomicsqlite . && docker run -v $(pwd):/mnt --rm genomicsqlite cp /usr/local/lib/{libgenomicsqlite.so,libsqlite3.so.0} /mnt/build/
-    - name: symbols & digests
-      run: |
-        readelf -d build/libgenomicsqlite.so
-        ldd -r build/libgenomicsqlite.so
-        echo "----"
-        echo "libgenomicsqlite.so GLIBC version requirements:"
-        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBC_.*' | sort -Vr | head -n1
-        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBCXX_.*' | sort -Vr | head -n1
-        echo "libsqlite3.so.0 GLIBC version requirements:"
-        objdump -t build/libsqlite3.so.0 | grep -o 'GLIBC_.*' | sort -Vr | head -n1
-        echo "----"
-        sha256sum build/libgenomicsqlite.so build/libsqlite3.so.0
-        sudo cp build/libsqlite3.so.0 /usr/local/lib
-        sudo ldconfig
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: test portable .so
-      run: env -C build SQLITE_WEB_LOG=99 ctest -V
-    - name: test rust crate
-      run: |
-        set -e
-        cp build/libgenomicsqlite.so bindings/rust
-        SQLITE_WEB_LOG=99 bindings/rust/cargo test --release
-        bindings/rust/cargo package --list | grep libgenomicsqlite.so
-    - name: prepare artifacts
-      run: cp build/{libgenomicsqlite.so,libsqlite3.so.0} .
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libgenomicsqlite.so
-        path: libgenomicsqlite.so
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libsqlite3.so.0
-        path: libsqlite3.so.0
-
-  macOS-arm64-dylib:
-    runs-on: macos-15
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - uses: actions/setup-python@v7
-      with:
-        python-version: '3.12'
-    - name: dependencies
-      run: |
-        rm -f $(brew --prefix)/bin/2to3  # https://github.com/pypa/pipenv/issues/3831
-        brew update || (sleep 2; brew update)
-        for dep in $BREW_DEPS ; do
-          brew install $dep || brew upgrade $dep
-        done
-
-        pip install $PIP_DEPS
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: build environment
-      run: |
-        echo "PATH=$(brew --prefix)/bin:$(brew --prefix)/opt/sqlite/bin:${PATH}" >> $GITHUB_ENV
-        echo "CFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "CXXFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "LDFLAGS=-L$(brew --prefix)/lib -L$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
-        # used by rusqlite:
-        echo "SQLITE3_INCLUDE_DIR=$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "SQLITE3_LIB_DIR=$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
-    - name: build
-      run: |
-        cmake -DCMAKE_BUILD_TYPE=Release \
-              -DCMAKE_PREFIX_PATH=$(brew --prefix)/opt/sqlite \
-              -B build .
-        cmake --build build -j 4
-    - name: symbols & digests
-      run: |
-        otool -L build/libgenomicsqlite.dylib
-        sha256sum build/libgenomicsqlite.dylib
-    - name: ctest
-      run: |
-        cd build
-        otool -L test/capi_smoke_test
-        SQLITE_WEB_LOG=99 ctest -V
-    - name: test rust crate
-      run: |
-        set -e
-        cp build/libgenomicsqlite.dylib bindings/rust
-        SQLITE_WEB_LOG=99 bindings/rust/cargo test --release
-        bindings/rust/cargo package --list | grep libgenomicsqlite.dylib
-    - name: prepare artifacts
-      run: cp build/libgenomicsqlite.dylib include/genomicsqlite.h .
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libgenomicsqlite.dylib
-        path: libgenomicsqlite.dylib
-
-  artifacts:
-    runs-on: ubuntu-24.04
-    needs: [linux-x86-64-so, macOS-arm64-dylib]
-    steps:
-    - uses: actions/checkout@v7
-    - name: fetch libgenomicsqlite.so
-      uses: actions/download-artifact@v8
-      with:
-        name: libgenomicsqlite.so
-    - name: fetch libsqlite3.so.0
-      uses: actions/download-artifact@v8
-      with:
-        name: libsqlite3.so.0
-    - name: fetch libgenomicsqlite.dylib
-      uses: actions/download-artifact@v8
-      with:
-        name: libgenomicsqlite.dylib
-    - name: detect GIT_REVISION
-      run: |
-        cp include/genomicsqlite.h .
-        echo "GIT_REVISION=$(git describe --tags --always)" >> $GITHUB_ENV
-    - uses: actions/upload-artifact@v7
-      with:
-        name: GenomicSQLite-${{ env.GIT_REVISION }}
-        path: |
-          LICENSE
-          genomicsqlite.h
-          libgenomicsqlite.so
-          libgenomicsqlite.dylib
-    - name: build jar
-      run: |
-        cp libgenomicsqlite.so libgenomicsqlite.dylib bindings/jdbc/genomicsqlite-jdbc/src/main/resources/
-        mvn deploy -Drevision=${{ env.GIT_REVISION }} -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
-    - name: digests
-      run: sha256sum *genomicsqlite* bindings/jdbc/genomicsqlite-jdbc/target/genomicsqlite*.jar libsqlite3.so.0
-    - uses: actions/upload-artifact@v7
-      with:
-        name: genomicsqlite-jdbc-${{ env.GIT_REVISION }}
-        path: bindings/jdbc/genomicsqlite-jdbc/target/mvn-repo

From 14128f604c9f8f690e825feb02b0cd9a85259ecb Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 08:54:11 +0000
Subject: [PATCH 19/42] Rename build.yml to .github/workflows/build.yml

---
 build.yml => .github/workflows/build.yml | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename build.yml => .github/workflows/build.yml (100%)

diff --git a/build.yml b/.github/workflows/build.yml
similarity index 100%
rename from build.yml
rename to .github/workflows/build.yml

From 60a09d7deeab54a107fa3a3ae4247e22507ed793 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 07:13:20 -1000
Subject: [PATCH 20/42] python CLI: route sqlite3 shell startup through a temp
 -init file

The genomicsqlite CLI wrapper passed its startup commands (.load,
.open, tuning PRAGMAs) to the sqlite3 shell as -cmd arguments,
including SQL -cmds, under -bail. Since SQLite 3.52 the shell exits
immediately -- successfully, without reading any input -- whenever
-bail is combined with an SQL -cmd, so on current shells (e.g.
Homebrew's) the wrapper silently did nothing.

Assemble the startup sequence (.load/.open/.once/tuning/.prompt,
plus the interactive version banner and .headers) into a temporary
-init file instead; no SQL remains in -cmd (there are no -cmd args
at all). The tuning SQL gains a terminating semicolon, which -init
file context requires. os.execvp replaces the process, so the temp
file is left for the OS reaper.

Verified: positional/stdin/interactive shapes behave identically
under sqlite 3.53.4 and 3.45.1 shells.
---
 bindings/python/genomicsqlite/__init__.py | 33 ++++++++++++++---------
 1 file changed, 20 insertions(+), 13 deletions(-)

diff --git a/bindings/python/genomicsqlite/__init__.py b/bindings/python/genomicsqlite/__init__.py
index ec9c82a..e91da64 100644
--- a/bindings/python/genomicsqlite/__init__.py
+++ b/bindings/python/genomicsqlite/__init__.py
@@ -253,6 +253,7 @@ def _cli(argv=None):
         sys.exit(1)
 
     import shutil
+    import tempfile
 
     if not shutil.which("sqlite3"):
         print(
@@ -272,30 +273,36 @@ def _cli(argv=None):
     uri = _execute1(_MEMCONN, "SELECT genomicsqlite_uri(?,?)", (argv[1], cfg))
     tuning_sql = _execute1(_MEMCONN, "SELECT genomicsqlite_tuning_sql(?)", (cfg,))
 
-    cmd = [
-        "sqlite3",
-        "-bail",
-        "-cmd",
+    # Assemble the shell startup commands into a temporary -init file, instead of passing them
+    # as -cmd arguments: since SQLite 3.52, the shell quits immediately (with a success exit
+    # code, without reading any input) whenever -bail is combined with an SQL -cmd argument,
+    # which silently disabled this wrapper. os.execvp() below replaces this process, so the
+    # file can't be unlinked afterwards; leave it for the OS temp reaper.
+    tuning_sql = tuning_sql.strip()
+    if not tuning_sql.endswith(";"):
+        # in -init file context, an unterminated statement would absorb the following line
+        tuning_sql += ";"
+    init_lines = [
         f".load {_DLL}",
-        "-cmd",
         f".open {uri}",
-        "-cmd",
         ".once /dev/null",
-        "-cmd",
         tuning_sql,
-        "-cmd",
         '.prompt "GenomicSQLite> "',
     ]
     if sys.stdout.isatty() and not next(
         (arg for arg in argv[2:] if not arg.startswith("-")), False
     ):
-        # interactive mode:
-        cmd += [
-            "-cmd",
-            "SELECT 'GenomicSQLite ' || genomicsqlite_version()",
-            "-cmd",
+        # interactive mode: print version banner, then turn on column headers
+        init_lines += [
+            "SELECT 'GenomicSQLite ' || genomicsqlite_version();",
             ".headers on",
         ]
+    with tempfile.NamedTemporaryFile(
+        "w", prefix="genomicsqlite-init-", suffix=".sql", delete=False
+    ) as init_file:
+        init_file.write("\n".join(init_lines) + "\n")
+
+    cmd = ["sqlite3", "-bail", "-init", init_file.name]
     cmd.append(":memory:")  # placeholder so remaining positional args are recognized as such
     cmd += argv[2:]
 

From 3a1eff8442afb1d83479e9c30f9083cb8a27219d Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 11:59:59 -1000
Subject: [PATCH 21/42] Remove live build.yml ahead of staged macOS Python
 workflow fix (rename round)

---
 .github/workflows/build.yml | 205 ------------------------------------
 1 file changed, 205 deletions(-)
 delete mode 100644 .github/workflows/build.yml

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
deleted file mode 100644
index 9e69bbe..0000000
--- a/.github/workflows/build.yml
+++ /dev/null
@@ -1,205 +0,0 @@
-name: build
-on: [push, pull_request]
-
-env:
-  APT_DEPS: libzstd-dev samtools tabix libhts-dev pigz python3-pip
-  BREW_DEPS: zstd samtools pigz coreutils sqlite
-  PIP_DEPS: pytest pytest-xdist
-
-jobs:
-
-  lint:
-    runs-on: ubuntu-24.04
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: deps
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y clang-format cppcheck python3-pip python3-venv
-        python3 -m venv "$HOME/.lint-venv"
-        "$HOME/.lint-venv/bin/pip" install pre-commit $PIP_DEPS black flake8 pylint
-        echo "$HOME/.lint-venv/bin" >> "$GITHUB_PATH"
-    - name: pre-commit
-      run: pre-commit run --all-files
-    - name: mvn spotless:check
-      run: mvn spotless:check -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-      with:
-        components: rustfmt, clippy
-    - name: rust lint
-      run: |
-        cd bindings/rust
-        bash ./cargo check --no-default-features
-        bash ./cargo fmt -- --check
-
-  test:
-    runs-on: ubuntu-24.04
-    strategy:
-      matrix:
-        BUILD_TYPE: [Debug, Release]
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: deps
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y $APT_DEPS
-        sudo pip3 install --break-system-packages $PIP_DEPS
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: build
-      run: cmake -DCMAKE_BUILD_TYPE=${{ matrix.BUILD_TYPE }} -B build . && cmake --build build -j $(nproc)
-    - name: test
-      run: env -C build SQLITE_WEB_LOG=99 ctest -V
-
-  linux-x86-64-so:
-    runs-on: ubuntu-24.04
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: build loaders
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y $APT_DEPS
-        sudo pip3 install --break-system-packages $PIP_DEPS
-        cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS='-D_GLIBCXX_USE_CXX11_ABI=0' -B build . && cmake --build build -j $(nproc)
-        rm build/libgenomicsqlite.so
-        sudo apt-get remove -y libzstd-dev  # should be linked into libgenomicsqlite.so
-    - name: build portable .so in docker
-      run: docker build -t genomicsqlite . && docker run -v $(pwd):/mnt --rm genomicsqlite cp /usr/local/lib/{libgenomicsqlite.so,libsqlite3.so.0} /mnt/build/
-    - name: symbols & digests
-      run: |
-        readelf -d build/libgenomicsqlite.so
-        ldd -r build/libgenomicsqlite.so
-        echo "----"
-        echo "libgenomicsqlite.so GLIBC version requirements:"
-        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBC_.*' | sort -Vr | head -n1
-        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBCXX_.*' | sort -Vr | head -n1
-        echo "libsqlite3.so.0 GLIBC version requirements:"
-        objdump -t build/libsqlite3.so.0 | grep -o 'GLIBC_.*' | sort -Vr | head -n1
-        echo "----"
-        sha256sum build/libgenomicsqlite.so build/libsqlite3.so.0
-        sudo cp build/libsqlite3.so.0 /usr/local/lib
-        sudo ldconfig
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: test portable .so
-      run: env -C build SQLITE_WEB_LOG=99 ctest -V
-    - name: test rust crate
-      run: |
-        set -e
-        cp build/libgenomicsqlite.so bindings/rust
-        SQLITE_WEB_LOG=99 bash bindings/rust/cargo test --release
-        bash bindings/rust/cargo package --list | grep libgenomicsqlite.so
-    - name: prepare artifacts
-      run: cp build/{libgenomicsqlite.so,libsqlite3.so.0} .
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libgenomicsqlite.so
-        path: libgenomicsqlite.so
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libsqlite3.so.0
-        path: libsqlite3.so.0
-
-  macOS-arm64-dylib:
-    runs-on: macos-15
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - uses: actions/setup-python@v7
-      with:
-        python-version: '3.12'
-    - name: dependencies
-      run: |
-        rm -f $(brew --prefix)/bin/2to3  # https://github.com/pypa/pipenv/issues/3831
-        brew update || (sleep 2; brew update)
-        for dep in $BREW_DEPS ; do
-          brew install $dep || brew upgrade $dep
-        done
-
-        pip install $PIP_DEPS
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: build environment
-      run: |
-        echo "PATH=$(brew --prefix)/bin:$(brew --prefix)/opt/sqlite/bin:${PATH}" >> $GITHUB_ENV
-        echo "CFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "CXXFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "LDFLAGS=-L$(brew --prefix)/lib -L$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
-        # used by rusqlite:
-        echo "SQLITE3_INCLUDE_DIR=$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "SQLITE3_LIB_DIR=$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
-    - name: build
-      run: |
-        cmake -DCMAKE_BUILD_TYPE=Release \
-              -DCMAKE_PREFIX_PATH=$(brew --prefix)/opt/sqlite \
-              -B build .
-        cmake --build build -j 4
-    - name: symbols & digests
-      run: |
-        otool -L build/libgenomicsqlite.dylib
-        sha256sum build/libgenomicsqlite.dylib
-    - name: ctest
-      run: |
-        cd build
-        otool -L test/capi_smoke_test
-        SQLITE_WEB_LOG=99 ctest -V
-    - name: test rust crate
-      run: |
-        set -e
-        cp build/libgenomicsqlite.dylib bindings/rust
-        SQLITE_WEB_LOG=99 bash bindings/rust/cargo test --release
-        bash bindings/rust/cargo package --list | grep libgenomicsqlite.dylib
-    - name: prepare artifacts
-      run: cp build/libgenomicsqlite.dylib include/genomicsqlite.h .
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libgenomicsqlite.dylib
-        path: libgenomicsqlite.dylib
-
-  artifacts:
-    runs-on: ubuntu-24.04
-    needs: [linux-x86-64-so, macOS-arm64-dylib]
-    steps:
-    - uses: actions/checkout@v7
-    - name: fetch libgenomicsqlite.so
-      uses: actions/download-artifact@v8
-      with:
-        name: libgenomicsqlite.so
-    - name: fetch libsqlite3.so.0
-      uses: actions/download-artifact@v8
-      with:
-        name: libsqlite3.so.0
-    - name: fetch libgenomicsqlite.dylib
-      uses: actions/download-artifact@v8
-      with:
-        name: libgenomicsqlite.dylib
-    - name: detect GIT_REVISION
-      run: |
-        cp include/genomicsqlite.h .
-        echo "GIT_REVISION=$(git describe --tags --always)" >> $GITHUB_ENV
-    - uses: actions/upload-artifact@v7
-      with:
-        name: GenomicSQLite-${{ env.GIT_REVISION }}
-        path: |
-          LICENSE
-          genomicsqlite.h
-          libgenomicsqlite.so
-          libgenomicsqlite.dylib
-    - name: build jar
-      run: |
-        cp libgenomicsqlite.so libgenomicsqlite.dylib bindings/jdbc/genomicsqlite-jdbc/src/main/resources/
-        mvn deploy -Drevision=${{ env.GIT_REVISION }} -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
-    - name: digests
-      run: sha256sum *genomicsqlite* bindings/jdbc/genomicsqlite-jdbc/target/genomicsqlite*.jar libsqlite3.so.0
-    - uses: actions/upload-artifact@v7
-      with:
-        name: genomicsqlite-jdbc-${{ env.GIT_REVISION }}
-        path: bindings/jdbc/genomicsqlite-jdbc/target/mvn-repo

From 1b62bd11dd5948857692db166ff1968e92df9723 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 12:00:22 -1000
Subject: [PATCH 22/42] Stage macOS Python workflow fix at repo root for rename
 into .github/workflows/

---
 build.yml | 209 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 209 insertions(+)
 create mode 100644 build.yml

diff --git a/build.yml b/build.yml
new file mode 100644
index 0000000..e4177fa
--- /dev/null
+++ b/build.yml
@@ -0,0 +1,209 @@
+name: build
+on: [push, pull_request]
+
+env:
+  APT_DEPS: libzstd-dev samtools tabix libhts-dev pigz python3-pip
+  BREW_DEPS: zstd samtools pigz coreutils sqlite python@3.12
+  PIP_DEPS: pytest pytest-xdist
+
+jobs:
+
+  lint:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: deps
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y clang-format cppcheck python3-pip python3-venv
+        python3 -m venv "$HOME/.lint-venv"
+        "$HOME/.lint-venv/bin/pip" install pre-commit $PIP_DEPS black flake8 pylint
+        echo "$HOME/.lint-venv/bin" >> "$GITHUB_PATH"
+    - name: pre-commit
+      run: pre-commit run --all-files
+    - name: mvn spotless:check
+      run: mvn spotless:check -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+      with:
+        components: rustfmt, clippy
+    - name: rust lint
+      run: |
+        cd bindings/rust
+        bash ./cargo check --no-default-features
+        bash ./cargo fmt -- --check
+
+  test:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        BUILD_TYPE: [Debug, Release]
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: deps
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y $APT_DEPS
+        sudo pip3 install --break-system-packages $PIP_DEPS
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: build
+      run: cmake -DCMAKE_BUILD_TYPE=${{ matrix.BUILD_TYPE }} -B build . && cmake --build build -j $(nproc)
+    - name: test
+      run: env -C build SQLITE_WEB_LOG=99 ctest -V
+
+  linux-x86-64-so:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: build loaders
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y $APT_DEPS
+        sudo pip3 install --break-system-packages $PIP_DEPS
+        cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS='-D_GLIBCXX_USE_CXX11_ABI=0' -B build . && cmake --build build -j $(nproc)
+        rm build/libgenomicsqlite.so
+        sudo apt-get remove -y libzstd-dev  # should be linked into libgenomicsqlite.so
+    - name: build portable .so in docker
+      run: docker build -t genomicsqlite . && docker run -v $(pwd):/mnt --rm genomicsqlite cp /usr/local/lib/{libgenomicsqlite.so,libsqlite3.so.0} /mnt/build/
+    - name: symbols & digests
+      run: |
+        readelf -d build/libgenomicsqlite.so
+        ldd -r build/libgenomicsqlite.so
+        echo "----"
+        echo "libgenomicsqlite.so GLIBC version requirements:"
+        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBC_.*' | sort -Vr | head -n1
+        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBCXX_.*' | sort -Vr | head -n1
+        echo "libsqlite3.so.0 GLIBC version requirements:"
+        objdump -t build/libsqlite3.so.0 | grep -o 'GLIBC_.*' | sort -Vr | head -n1
+        echo "----"
+        sha256sum build/libgenomicsqlite.so build/libsqlite3.so.0
+        sudo cp build/libsqlite3.so.0 /usr/local/lib
+        sudo ldconfig
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: test portable .so
+      run: env -C build SQLITE_WEB_LOG=99 ctest -V
+    - name: test rust crate
+      run: |
+        set -e
+        cp build/libgenomicsqlite.so bindings/rust
+        SQLITE_WEB_LOG=99 bash bindings/rust/cargo test --release
+        bash bindings/rust/cargo package --list | grep libgenomicsqlite.so
+    - name: prepare artifacts
+      run: cp build/{libgenomicsqlite.so,libsqlite3.so.0} .
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libgenomicsqlite.so
+        path: libgenomicsqlite.so
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libsqlite3.so.0
+        path: libsqlite3.so.0
+
+  macOS-arm64-dylib:
+    runs-on: macos-15
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: dependencies
+      run: |
+        rm -f $(brew --prefix)/bin/2to3  # https://github.com/pypa/pipenv/issues/3831
+        brew update || (sleep 2; brew update)
+        for dep in $BREW_DEPS ; do
+          brew install $dep || brew upgrade $dep
+        done
+
+        # The tests must run under Homebrew's Python: it is configured with
+        # --enable-loadable-sqlite-extensions (the binding cannot be imported
+        # without sqlite3.Connection.enable_load_extension), while the
+        # image's python.org framework Python is built without it.
+        echo "$(brew --prefix)/opt/python@3.12/bin" >> "$GITHUB_PATH"
+        export PATH="$(brew --prefix)/opt/python@3.12/bin:$PATH"
+        python3 -m pip install --break-system-packages $PIP_DEPS
+        python3 -c "import sqlite3; assert hasattr(sqlite3.Connection, 'enable_load_extension')"
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: build environment
+      run: |
+        echo "PATH=$(brew --prefix)/opt/python@3.12/bin:$(brew --prefix)/bin:$(brew --prefix)/opt/sqlite/bin:${PATH}" >> $GITHUB_ENV
+        echo "CFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "CXXFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "LDFLAGS=-L$(brew --prefix)/lib -L$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
+        # used by rusqlite:
+        echo "SQLITE3_INCLUDE_DIR=$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "SQLITE3_LIB_DIR=$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
+    - name: build
+      run: |
+        cmake -DCMAKE_BUILD_TYPE=Release \
+              -DCMAKE_PREFIX_PATH=$(brew --prefix)/opt/sqlite \
+              -B build .
+        cmake --build build -j 4
+    - name: symbols & digests
+      run: |
+        otool -L build/libgenomicsqlite.dylib
+        sha256sum build/libgenomicsqlite.dylib
+    - name: ctest
+      run: |
+        cd build
+        otool -L test/capi_smoke_test
+        SQLITE_WEB_LOG=99 ctest -V
+    - name: test rust crate
+      run: |
+        set -e
+        cp build/libgenomicsqlite.dylib bindings/rust
+        SQLITE_WEB_LOG=99 bash bindings/rust/cargo test --release
+        bash bindings/rust/cargo package --list | grep libgenomicsqlite.dylib
+    - name: prepare artifacts
+      run: cp build/libgenomicsqlite.dylib include/genomicsqlite.h .
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libgenomicsqlite.dylib
+        path: libgenomicsqlite.dylib
+
+  artifacts:
+    runs-on: ubuntu-24.04
+    needs: [linux-x86-64-so, macOS-arm64-dylib]
+    steps:
+    - uses: actions/checkout@v7
+    - name: fetch libgenomicsqlite.so
+      uses: actions/download-artifact@v8
+      with:
+        name: libgenomicsqlite.so
+    - name: fetch libsqlite3.so.0
+      uses: actions/download-artifact@v8
+      with:
+        name: libsqlite3.so.0
+    - name: fetch libgenomicsqlite.dylib
+      uses: actions/download-artifact@v8
+      with:
+        name: libgenomicsqlite.dylib
+    - name: detect GIT_REVISION
+      run: |
+        cp include/genomicsqlite.h .
+        echo "GIT_REVISION=$(git describe --tags --always)" >> $GITHUB_ENV
+    - uses: actions/upload-artifact@v7
+      with:
+        name: GenomicSQLite-${{ env.GIT_REVISION }}
+        path: |
+          LICENSE
+          genomicsqlite.h
+          libgenomicsqlite.so
+          libgenomicsqlite.dylib
+    - name: build jar
+      run: |
+        cp libgenomicsqlite.so libgenomicsqlite.dylib bindings/jdbc/genomicsqlite-jdbc/src/main/resources/
+        mvn deploy -Drevision=${{ env.GIT_REVISION }} -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
+    - name: digests
+      run: sha256sum *genomicsqlite* bindings/jdbc/genomicsqlite-jdbc/target/genomicsqlite*.jar libsqlite3.so.0
+    - uses: actions/upload-artifact@v7
+      with:
+        name: genomicsqlite-jdbc-${{ env.GIT_REVISION }}
+        path: bindings/jdbc/genomicsqlite-jdbc/target/mvn-repo

From 53562171906a1fd607a9451f181bb7769c37658b Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 12:32:42 -1000
Subject: [PATCH 23/42] Rename build.yml to .github/workflows/build.yml

---
 build.yml => .github/workflows/build.yml | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename build.yml => .github/workflows/build.yml (100%)

diff --git a/build.yml b/.github/workflows/build.yml
similarity index 100%
rename from build.yml
rename to .github/workflows/build.yml

From e005047875f5116828221abdde3109ea017add92 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 13:02:52 -1000
Subject: [PATCH 24/42] rust: bundle libgenomicsqlite by OS, not arch

bundle_libgenomicsqlite() was defined only for linux+x86_64 and
macos+x86_64, but open() calls it unconditionally under default
features, so the crate never compiled with default features on
Apple Silicon (E0425) or linux/aarch64. Drop the target_arch gates
so bundling is keyed by OS; the bundled bytes are the per-platform
lib placed beside the crate.
---
 bindings/rust/src/lib.rs | 12 ++----------
 1 file changed, 2 insertions(+), 10 deletions(-)

diff --git a/bindings/rust/src/lib.rs b/bindings/rust/src/lib.rs
index f999172..6114d7d 100644
--- a/bindings/rust/src/lib.rs
+++ b/bindings/rust/src/lib.rs
@@ -53,11 +53,7 @@ fn bundle_libgenomicsqlite() -> Option<(String, TempDir)> {
     None
 }
 
-#[cfg(all(
-    feature = "bundle_libgenomicsqlite",
-    target_os = "linux",
-    target_arch = "x86_64"
-))]
+#[cfg(all(feature = "bundle_libgenomicsqlite", target_os = "linux"))]
 fn bundle_libgenomicsqlite() -> Option<(String, TempDir)> {
     Some(extract_libgenomicsqlite(
         include_bytes!("../libgenomicsqlite.so"),
@@ -65,11 +61,7 @@ fn bundle_libgenomicsqlite() -> Option<(String, TempDir)> {
     ))
 }
 
-#[cfg(all(
-    feature = "bundle_libgenomicsqlite",
-    target_os = "macos",
-    target_arch = "x86_64"
-))]
+#[cfg(all(feature = "bundle_libgenomicsqlite", target_os = "macos"))]
 fn bundle_libgenomicsqlite() -> Option<(String, TempDir)> {
     Some(extract_libgenomicsqlite(
         include_bytes!("../libgenomicsqlite.dylib"),

From f439e5c7bae341420867472cef6b696c312a34a4 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 14:13:21 -1000
Subject: [PATCH 25/42] CI: portable Linux build on AlmaLinux 8
 (manylinux_2_28) instead of CentOS 7

---
 Dockerfile | 31 +++++++++++++++----------------
 1 file changed, 15 insertions(+), 16 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index 8f5d464..85acdc8 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,7 +1,7 @@
-# Builds libgenomicsqlite.so in CentOS 7 (+ devtoolset-8) to maximize compatibility. Bakes in
-# Zstandard, and also builds a compatible libsqlite3.so.0 for users unable/unwilling to upgrade
-# their host's.
-FROM centos:7 as builder
+# Builds libgenomicsqlite.so in AlmaLinux 8 (glibc 2.28, the manylinux_2_28 baseline) to
+# maximize compatibility. Bakes in Zstandard, and also builds a compatible libsqlite3.so.0
+# for users unable/unwilling to upgrade their host's.
+FROM almalinux:8 as builder
 
 ARG CMAKE_VERSION=3.17.3
 ARG SQLITE_VERSION=3410200
@@ -28,8 +28,7 @@ ENV SQLITE_CFLAGS="\
         -DSQLITE_ENABLE_SESSION \
 "
 
-RUN yum install -y -q wget unzip rsync git libcurl-devel centos-release-scl
-RUN yum install -y -q devtoolset-8-gcc devtoolset-8-gcc-c++ devtoolset-8-make
+RUN dnf install -y -q wget unzip rsync git libcurl-devel gcc gcc-c++ make
 
 RUN mkdir -p /work/GenomicSQLite
 
@@ -38,8 +37,8 @@ WORKDIR /work
 RUN wget -nv http://www.sqlite.org/2023/sqlite-amalgamation-${SQLITE_VERSION}.zip \
         && unzip -o sqlite-amalgamation-${SQLITE_VERSION}.zip
 WORKDIR /work/sqlite-amalgamation-${SQLITE_VERSION}
-RUN bash -c "scl enable devtoolset-8 'gcc -shared -o libsqlite3.so.0 -fPIC -shared -Wl,-soname,libsqlite3.so.0 -g ${CFLAGS} ${SQLITE_CFLAGS} sqlite3.c' & pid=$? \
-             scl enable devtoolset-8 'gcc -o sqlite3 -g ${CFLAGS} ${SQLITE_CFLAGS} sqlite3.c shell.c -lpthread -ldl -lm' && wait $pid"
+RUN bash -c "gcc -shared -o libsqlite3.so.0 -fPIC -shared -Wl,-soname,libsqlite3.so.0 -g ${CFLAGS} ${SQLITE_CFLAGS} sqlite3.c & pid=$? \
+             gcc -o sqlite3 -g ${CFLAGS} ${SQLITE_CFLAGS} sqlite3.c shell.c -lpthread -ldl -lm && wait $pid"
 RUN cp libsqlite3.so.0 /usr/local/lib && cp *.h /usr/local/include && cp sqlite3 /usr/local/bin
 RUN ln -s /usr/local/lib/libsqlite3.so.0 /usr/local/lib/libsqlite3.so
 
@@ -47,7 +46,7 @@ RUN ln -s /usr/local/lib/libsqlite3.so.0 /usr/local/lib/libsqlite3.so
 WORKDIR /work
 RUN wget -nv -O - https://github.com/facebook/zstd/releases/download/v${ZSTD_VERSION}/zstd-${ZSTD_VERSION}.tar.gz | tar zx
 WORKDIR /work/zstd-${ZSTD_VERSION}
-RUN scl enable devtoolset-8 "CFLAGS='${CFLAGS} -fPIC' make install -j $(nproc)"
+RUN CFLAGS="${CFLAGS} -fPIC" make install -j $(nproc)
 
 # CMake
 WORKDIR /work
@@ -61,21 +60,21 @@ RUN ldconfig
 ADD . /work/GenomicSQLite
 WORKDIR /work/GenomicSQLite
 RUN rm -rf build
-RUN scl enable devtoolset-8 "cmake -DCMAKE_BUILD_TYPE=Release -DZSTD_WHOLE_ARCHIVE=true -B build . && cmake --build build --target genomicsqlite -j $(nproc)"
+RUN cmake -DCMAKE_BUILD_TYPE=Release -DZSTD_WHOLE_ARCHIVE=true -B build . && cmake --build build --target genomicsqlite -j $(nproc)
 RUN sqlite3 -cmd '.load build/libgenomicsqlite.so' :memory: 'select sqlite_version(); select genomicsqlite_version()'
 
 
 
 
 ###################################################################################################
-# Run-up in fresh centos:7, to confirm no dependencies crept into the .so's
+# Run-up in fresh almalinux:8, to confirm no dependencies crept into the .so's
 
-FROM centos:7
+FROM almalinux:8
 
 COPY --from=builder /usr/local/bin/sqlite3 /usr/local/bin/
 COPY --from=builder /usr/local/include/sqlite3.h /usr/local/include/
 
-# NOTE: /usr/local/lib is NOT a default ld path in CentOS -- https://unix.stackexchange.com/q/356624
+# NOTE: /usr/local/lib is NOT a default ld path in AlmaLinux -- https://unix.stackexchange.com/q/356624
 RUN mkdir -p /work/lib
 WORKDIR /work
 COPY --from=builder /usr/local/lib/libsqlite3.so.0 ./lib/
@@ -98,7 +97,7 @@ RUN ./genomicsqlite_capi_smoke_test
         # ^ we didn't need LD_LIBRARY_PATH even though the .so's aren't at their linktime locations
 
 # test rust bindings too
-FROM centos:7
+FROM almalinux:8
 
 RUN yum install -y -q gcc git
 ADD https://sh.rustup.rs /usr/local/bin/rustup-init.sh
@@ -115,9 +114,9 @@ COPY --from=builder /work/GenomicSQLite/build/libgenomicsqlite.so ./rust/
 RUN SQLITE_WEB_LOG=99 LD_LIBRARY_PATH=$(pwd)/lib LIBRARY_PATH=$(pwd)/lib rust/cargo test --release
 
 ###################################################################################################
-# Run-up in ubuntu 16.04
+# Run-up in ubuntu 20.04
 
-FROM ubuntu:16.04
+FROM ubuntu:20.04
 
 COPY --from=builder /usr/local/bin/sqlite3 /usr/local/bin/
 COPY --from=builder /usr/local/include/sqlite3.h /usr/local/include/

From aa0c9a2912fc022061c889d52bce33c58ad7577c Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 14:13:58 -1000
Subject: [PATCH 26/42] CI: remove .github/workflows/build.yml ahead of staged
 replacement

---
 .github/workflows/build.yml | 209 ------------------------------------
 1 file changed, 209 deletions(-)
 delete mode 100644 .github/workflows/build.yml

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
deleted file mode 100644
index e4177fa..0000000
--- a/.github/workflows/build.yml
+++ /dev/null
@@ -1,209 +0,0 @@
-name: build
-on: [push, pull_request]
-
-env:
-  APT_DEPS: libzstd-dev samtools tabix libhts-dev pigz python3-pip
-  BREW_DEPS: zstd samtools pigz coreutils sqlite python@3.12
-  PIP_DEPS: pytest pytest-xdist
-
-jobs:
-
-  lint:
-    runs-on: ubuntu-24.04
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: deps
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y clang-format cppcheck python3-pip python3-venv
-        python3 -m venv "$HOME/.lint-venv"
-        "$HOME/.lint-venv/bin/pip" install pre-commit $PIP_DEPS black flake8 pylint
-        echo "$HOME/.lint-venv/bin" >> "$GITHUB_PATH"
-    - name: pre-commit
-      run: pre-commit run --all-files
-    - name: mvn spotless:check
-      run: mvn spotless:check -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-      with:
-        components: rustfmt, clippy
-    - name: rust lint
-      run: |
-        cd bindings/rust
-        bash ./cargo check --no-default-features
-        bash ./cargo fmt -- --check
-
-  test:
-    runs-on: ubuntu-24.04
-    strategy:
-      matrix:
-        BUILD_TYPE: [Debug, Release]
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: deps
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y $APT_DEPS
-        sudo pip3 install --break-system-packages $PIP_DEPS
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: build
-      run: cmake -DCMAKE_BUILD_TYPE=${{ matrix.BUILD_TYPE }} -B build . && cmake --build build -j $(nproc)
-    - name: test
-      run: env -C build SQLITE_WEB_LOG=99 ctest -V
-
-  linux-x86-64-so:
-    runs-on: ubuntu-24.04
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: build loaders
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y $APT_DEPS
-        sudo pip3 install --break-system-packages $PIP_DEPS
-        cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS='-D_GLIBCXX_USE_CXX11_ABI=0' -B build . && cmake --build build -j $(nproc)
-        rm build/libgenomicsqlite.so
-        sudo apt-get remove -y libzstd-dev  # should be linked into libgenomicsqlite.so
-    - name: build portable .so in docker
-      run: docker build -t genomicsqlite . && docker run -v $(pwd):/mnt --rm genomicsqlite cp /usr/local/lib/{libgenomicsqlite.so,libsqlite3.so.0} /mnt/build/
-    - name: symbols & digests
-      run: |
-        readelf -d build/libgenomicsqlite.so
-        ldd -r build/libgenomicsqlite.so
-        echo "----"
-        echo "libgenomicsqlite.so GLIBC version requirements:"
-        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBC_.*' | sort -Vr | head -n1
-        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBCXX_.*' | sort -Vr | head -n1
-        echo "libsqlite3.so.0 GLIBC version requirements:"
-        objdump -t build/libsqlite3.so.0 | grep -o 'GLIBC_.*' | sort -Vr | head -n1
-        echo "----"
-        sha256sum build/libgenomicsqlite.so build/libsqlite3.so.0
-        sudo cp build/libsqlite3.so.0 /usr/local/lib
-        sudo ldconfig
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: test portable .so
-      run: env -C build SQLITE_WEB_LOG=99 ctest -V
-    - name: test rust crate
-      run: |
-        set -e
-        cp build/libgenomicsqlite.so bindings/rust
-        SQLITE_WEB_LOG=99 bash bindings/rust/cargo test --release
-        bash bindings/rust/cargo package --list | grep libgenomicsqlite.so
-    - name: prepare artifacts
-      run: cp build/{libgenomicsqlite.so,libsqlite3.so.0} .
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libgenomicsqlite.so
-        path: libgenomicsqlite.so
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libsqlite3.so.0
-        path: libsqlite3.so.0
-
-  macOS-arm64-dylib:
-    runs-on: macos-15
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: dependencies
-      run: |
-        rm -f $(brew --prefix)/bin/2to3  # https://github.com/pypa/pipenv/issues/3831
-        brew update || (sleep 2; brew update)
-        for dep in $BREW_DEPS ; do
-          brew install $dep || brew upgrade $dep
-        done
-
-        # The tests must run under Homebrew's Python: it is configured with
-        # --enable-loadable-sqlite-extensions (the binding cannot be imported
-        # without sqlite3.Connection.enable_load_extension), while the
-        # image's python.org framework Python is built without it.
-        echo "$(brew --prefix)/opt/python@3.12/bin" >> "$GITHUB_PATH"
-        export PATH="$(brew --prefix)/opt/python@3.12/bin:$PATH"
-        python3 -m pip install --break-system-packages $PIP_DEPS
-        python3 -c "import sqlite3; assert hasattr(sqlite3.Connection, 'enable_load_extension')"
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: build environment
-      run: |
-        echo "PATH=$(brew --prefix)/opt/python@3.12/bin:$(brew --prefix)/bin:$(brew --prefix)/opt/sqlite/bin:${PATH}" >> $GITHUB_ENV
-        echo "CFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "CXXFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "LDFLAGS=-L$(brew --prefix)/lib -L$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
-        # used by rusqlite:
-        echo "SQLITE3_INCLUDE_DIR=$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "SQLITE3_LIB_DIR=$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
-    - name: build
-      run: |
-        cmake -DCMAKE_BUILD_TYPE=Release \
-              -DCMAKE_PREFIX_PATH=$(brew --prefix)/opt/sqlite \
-              -B build .
-        cmake --build build -j 4
-    - name: symbols & digests
-      run: |
-        otool -L build/libgenomicsqlite.dylib
-        sha256sum build/libgenomicsqlite.dylib
-    - name: ctest
-      run: |
-        cd build
-        otool -L test/capi_smoke_test
-        SQLITE_WEB_LOG=99 ctest -V
-    - name: test rust crate
-      run: |
-        set -e
-        cp build/libgenomicsqlite.dylib bindings/rust
-        SQLITE_WEB_LOG=99 bash bindings/rust/cargo test --release
-        bash bindings/rust/cargo package --list | grep libgenomicsqlite.dylib
-    - name: prepare artifacts
-      run: cp build/libgenomicsqlite.dylib include/genomicsqlite.h .
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libgenomicsqlite.dylib
-        path: libgenomicsqlite.dylib
-
-  artifacts:
-    runs-on: ubuntu-24.04
-    needs: [linux-x86-64-so, macOS-arm64-dylib]
-    steps:
-    - uses: actions/checkout@v7
-    - name: fetch libgenomicsqlite.so
-      uses: actions/download-artifact@v8
-      with:
-        name: libgenomicsqlite.so
-    - name: fetch libsqlite3.so.0
-      uses: actions/download-artifact@v8
-      with:
-        name: libsqlite3.so.0
-    - name: fetch libgenomicsqlite.dylib
-      uses: actions/download-artifact@v8
-      with:
-        name: libgenomicsqlite.dylib
-    - name: detect GIT_REVISION
-      run: |
-        cp include/genomicsqlite.h .
-        echo "GIT_REVISION=$(git describe --tags --always)" >> $GITHUB_ENV
-    - uses: actions/upload-artifact@v7
-      with:
-        name: GenomicSQLite-${{ env.GIT_REVISION }}
-        path: |
-          LICENSE
-          genomicsqlite.h
-          libgenomicsqlite.so
-          libgenomicsqlite.dylib
-    - name: build jar
-      run: |
-        cp libgenomicsqlite.so libgenomicsqlite.dylib bindings/jdbc/genomicsqlite-jdbc/src/main/resources/
-        mvn deploy -Drevision=${{ env.GIT_REVISION }} -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
-    - name: digests
-      run: sha256sum *genomicsqlite* bindings/jdbc/genomicsqlite-jdbc/target/genomicsqlite*.jar libsqlite3.so.0
-    - uses: actions/upload-artifact@v7
-      with:
-        name: genomicsqlite-jdbc-${{ env.GIT_REVISION }}
-        path: bindings/jdbc/genomicsqlite-jdbc/target/mvn-repo

From 6118fd1dd072d76fe1b5c3001bffcb9304700f38 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 14:14:36 -1000
Subject: [PATCH 27/42] CI: stage build.yml (glibc 2.28 floor assertion;
 per-arch rust bundle names) for rename to .github/workflows/build.yml

---
 build.yml | 224 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 224 insertions(+)
 create mode 100644 build.yml

diff --git a/build.yml b/build.yml
new file mode 100644
index 0000000..04b5568
--- /dev/null
+++ b/build.yml
@@ -0,0 +1,224 @@
+name: build
+on: [push, pull_request]
+
+env:
+  APT_DEPS: libzstd-dev samtools tabix libhts-dev pigz python3-pip
+  BREW_DEPS: zstd samtools pigz coreutils sqlite python@3.12
+  PIP_DEPS: pytest pytest-xdist
+
+jobs:
+
+  lint:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: deps
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y clang-format cppcheck python3-pip python3-venv
+        python3 -m venv "$HOME/.lint-venv"
+        "$HOME/.lint-venv/bin/pip" install pre-commit $PIP_DEPS black flake8 pylint
+        echo "$HOME/.lint-venv/bin" >> "$GITHUB_PATH"
+    - name: pre-commit
+      run: pre-commit run --all-files
+    - name: mvn spotless:check
+      run: mvn spotless:check -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+      with:
+        components: rustfmt, clippy
+    - name: rust lint
+      run: |
+        cd bindings/rust
+        bash ./cargo check --no-default-features
+        bash ./cargo fmt -- --check
+
+  test:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        BUILD_TYPE: [Debug, Release]
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: deps
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y $APT_DEPS
+        sudo pip3 install --break-system-packages $PIP_DEPS
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: build
+      run: cmake -DCMAKE_BUILD_TYPE=${{ matrix.BUILD_TYPE }} -B build . && cmake --build build -j $(nproc)
+    - name: test
+      run: env -C build SQLITE_WEB_LOG=99 ctest -V
+
+  linux-x86-64-so:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: build loaders
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y $APT_DEPS
+        sudo pip3 install --break-system-packages $PIP_DEPS
+        cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS='-D_GLIBCXX_USE_CXX11_ABI=0' -B build . && cmake --build build -j $(nproc)
+        rm build/libgenomicsqlite.so
+        sudo apt-get remove -y libzstd-dev  # should be linked into libgenomicsqlite.so
+    - name: build portable .so in docker
+      run: docker build -t genomicsqlite . && docker run -v $(pwd):/mnt --rm genomicsqlite cp /usr/local/lib/{libgenomicsqlite.so,libsqlite3.so.0} /mnt/build/
+    - name: symbols & digests
+      run: |
+        readelf -d build/libgenomicsqlite.so
+        ldd -r build/libgenomicsqlite.so
+        echo "----"
+        echo "libgenomicsqlite.so GLIBC version requirements:"
+        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBC_.*' | sort -Vr | head -n1
+        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBCXX_.*' | sort -Vr | head -n1
+        echo "libsqlite3.so.0 GLIBC version requirements:"
+        objdump -t build/libsqlite3.so.0 | grep -o 'GLIBC_.*' | sort -Vr | head -n1
+        echo "----"
+        sha256sum build/libgenomicsqlite.so build/libsqlite3.so.0
+        echo "asserting manylinux_2_28 floor (GLIBC <= 2.28, GLIBCXX <= 3.4.25):"
+        for f in build/libgenomicsqlite.so build/libsqlite3.so.0; do
+          max_glibc=$(objdump -t $f | grep -oE 'GLIBC_[0-9.]+' | sort -Vu | tail -n1)
+          echo "$f max GLIBC need: $max_glibc"
+          if [ "$(printf 'GLIBC_2.28\n%s\n' "$max_glibc" | sort -V | tail -n1)" != "GLIBC_2.28" ]; then
+            echo "$f requires $max_glibc, above the glibc 2.28 floor" >&2
+            exit 1
+          fi
+        done
+        max_glibcxx=$(objdump -t build/libgenomicsqlite.so | grep -oE 'GLIBCXX_[0-9.]+' | sort -Vu | tail -n1)
+        echo "build/libgenomicsqlite.so max GLIBCXX need: $max_glibcxx"
+        if [ "$(printf 'GLIBCXX_3.4.25\n%s\n' "$max_glibcxx" | sort -V | tail -n1)" != "GLIBCXX_3.4.25" ]; then
+          echo "build/libgenomicsqlite.so requires $max_glibcxx, above the GLIBCXX 3.4.25 ceiling" >&2
+          exit 1
+        fi
+        sudo cp build/libsqlite3.so.0 /usr/local/lib
+        sudo ldconfig
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: test portable .so
+      run: env -C build SQLITE_WEB_LOG=99 ctest -V
+    - name: test rust crate
+      run: |
+        set -e
+        cp build/libgenomicsqlite.so bindings/rust/libgenomicsqlite-linux-x86_64.so
+        SQLITE_WEB_LOG=99 bash bindings/rust/cargo test --release
+        bash bindings/rust/cargo package --list | grep libgenomicsqlite-linux-x86_64.so
+    - name: prepare artifacts
+      run: cp build/{libgenomicsqlite.so,libsqlite3.so.0} .
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libgenomicsqlite.so
+        path: libgenomicsqlite.so
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libsqlite3.so.0
+        path: libsqlite3.so.0
+
+  macOS-arm64-dylib:
+    runs-on: macos-15
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: dependencies
+      run: |
+        rm -f $(brew --prefix)/bin/2to3  # https://github.com/pypa/pipenv/issues/3831
+        brew update || (sleep 2; brew update)
+        for dep in $BREW_DEPS ; do
+          brew install $dep || brew upgrade $dep
+        done
+
+        # The tests must run under Homebrew's Python: it is configured with
+        # --enable-loadable-sqlite-extensions (the binding cannot be imported
+        # without sqlite3.Connection.enable_load_extension), while the
+        # image's python.org framework Python is built without it.
+        echo "$(brew --prefix)/opt/python@3.12/bin" >> "$GITHUB_PATH"
+        export PATH="$(brew --prefix)/opt/python@3.12/bin:$PATH"
+        python3 -m pip install --break-system-packages $PIP_DEPS
+        python3 -c "import sqlite3; assert hasattr(sqlite3.Connection, 'enable_load_extension')"
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: build environment
+      run: |
+        echo "PATH=$(brew --prefix)/opt/python@3.12/bin:$(brew --prefix)/bin:$(brew --prefix)/opt/sqlite/bin:${PATH}" >> $GITHUB_ENV
+        echo "CFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "CXXFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "LDFLAGS=-L$(brew --prefix)/lib -L$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
+        # used by rusqlite:
+        echo "SQLITE3_INCLUDE_DIR=$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "SQLITE3_LIB_DIR=$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
+    - name: build
+      run: |
+        cmake -DCMAKE_BUILD_TYPE=Release \
+              -DCMAKE_PREFIX_PATH=$(brew --prefix)/opt/sqlite \
+              -B build .
+        cmake --build build -j 4
+    - name: symbols & digests
+      run: |
+        otool -L build/libgenomicsqlite.dylib
+        sha256sum build/libgenomicsqlite.dylib
+    - name: ctest
+      run: |
+        cd build
+        otool -L test/capi_smoke_test
+        SQLITE_WEB_LOG=99 ctest -V
+    - name: test rust crate
+      run: |
+        set -e
+        cp build/libgenomicsqlite.dylib bindings/rust/libgenomicsqlite-macos-aarch64.dylib
+        SQLITE_WEB_LOG=99 bash bindings/rust/cargo test --release
+        bash bindings/rust/cargo package --list | grep libgenomicsqlite-macos-aarch64.dylib
+    - name: prepare artifacts
+      run: cp build/libgenomicsqlite.dylib include/genomicsqlite.h .
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libgenomicsqlite.dylib
+        path: libgenomicsqlite.dylib
+
+  artifacts:
+    runs-on: ubuntu-24.04
+    needs: [linux-x86-64-so, macOS-arm64-dylib]
+    steps:
+    - uses: actions/checkout@v7
+    - name: fetch libgenomicsqlite.so
+      uses: actions/download-artifact@v8
+      with:
+        name: libgenomicsqlite.so
+    - name: fetch libsqlite3.so.0
+      uses: actions/download-artifact@v8
+      with:
+        name: libsqlite3.so.0
+    - name: fetch libgenomicsqlite.dylib
+      uses: actions/download-artifact@v8
+      with:
+        name: libgenomicsqlite.dylib
+    - name: detect GIT_REVISION
+      run: |
+        cp include/genomicsqlite.h .
+        echo "GIT_REVISION=$(git describe --tags --always)" >> $GITHUB_ENV
+    - uses: actions/upload-artifact@v7
+      with:
+        name: GenomicSQLite-${{ env.GIT_REVISION }}
+        path: |
+          LICENSE
+          genomicsqlite.h
+          libgenomicsqlite.so
+          libgenomicsqlite.dylib
+    - name: build jar
+      run: |
+        cp libgenomicsqlite.so libgenomicsqlite.dylib bindings/jdbc/genomicsqlite-jdbc/src/main/resources/
+        mvn deploy -Drevision=${{ env.GIT_REVISION }} -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
+    - name: digests
+      run: sha256sum *genomicsqlite* bindings/jdbc/genomicsqlite-jdbc/target/genomicsqlite*.jar libsqlite3.so.0
+    - uses: actions/upload-artifact@v7
+      with:
+        name: genomicsqlite-jdbc-${{ env.GIT_REVISION }}
+        path: bindings/jdbc/genomicsqlite-jdbc/target/mvn-repo

From 7ed55ba448b6636dcc6212d13c1d5973d74facf2 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 14:30:51 -1000
Subject: [PATCH 28/42] bindings/rust: per-arch bundled libgenomicsqlite matrix
 (build.rs inventory, fallback to library search, legible load errors)

---
 bindings/rust/.gitignore    |   1 +
 bindings/rust/Cargo.toml.in |   2 +-
 bindings/rust/build.rs      |  76 +++++++++++++++++++++++++++
 bindings/rust/src/lib.rs    | 102 ++++++++++++++++++++++++++++++------
 4 files changed, 163 insertions(+), 18 deletions(-)
 create mode 100644 bindings/rust/build.rs

diff --git a/bindings/rust/.gitignore b/bindings/rust/.gitignore
index 2d7878f..042eab2 100644
--- a/bindings/rust/.gitignore
+++ b/bindings/rust/.gitignore
@@ -13,3 +13,4 @@ Cargo.lock
 # Cargo.toml is generated from Cargo.toml.in by ./cargo
 Cargo.toml
 libgenomicsqlite.*
+libgenomicsqlite-*
diff --git a/bindings/rust/Cargo.toml.in b/bindings/rust/Cargo.toml.in
index 7813476..d3979a9 100644
--- a/bindings/rust/Cargo.toml.in
+++ b/bindings/rust/Cargo.toml.in
@@ -7,7 +7,7 @@ edition = "2018"
 license = "Apache-2.0"
 repository = "https://github.com/mlin/GenomicSQLite"
 documentation = "https://mlin.github.io/GenomicSQLite"
-include = ["src/**/*", "Cargo.toml", "libgenomicsqlite.*"]
+include = ["src/**/*", "Cargo.toml", "build.rs", "libgenomicsqlite.*", "libgenomicsqlite-*"]
 
 [features]
 # Use default-features=false to prevent bundling a platform-specific libgenomicsqlite into your
diff --git a/bindings/rust/build.rs b/bindings/rust/build.rs
new file mode 100644
index 0000000..cb6b9f8
--- /dev/null
+++ b/bindings/rust/build.rs
@@ -0,0 +1,76 @@
+// Build script for the genomicsqlite crate: inventory the prebuilt
+// libgenomicsqlite libraries bundled next to Cargo.toml.
+//
+// A bundled library is embedded into the compilation unit only for the
+// target it was built for, under a per-OS/architecture file name:
+//     libgenomicsqlite-linux-x86_64.so    libgenomicsqlite-linux-aarch64.so
+//     libgenomicsqlite-macos-x86_64.dylib libgenomicsqlite-macos-aarch64.dylib
+// For each candidate file that actually exists in the package, this script
+// sets a rustc cfg (bundled_linux_x86_64 etc.) gating the corresponding
+// include_bytes! arm in src/lib.rs. A missing file therefore degrades to
+// the runtime library search instead of breaking compilation with a
+// missing-file error.
+use std::env;
+use std::path::Path;
+
+// (target_os, target_arch, file name, cfg name) for each bundled candidate
+const CANDIDATES: &[(&str, &str, &str, &str)] = &[
+    (
+        "linux",
+        "x86_64",
+        "libgenomicsqlite-linux-x86_64.so",
+        "bundled_linux_x86_64",
+    ),
+    (
+        "linux",
+        "aarch64",
+        "libgenomicsqlite-linux-aarch64.so",
+        "bundled_linux_aarch64",
+    ),
+    (
+        "macos",
+        "x86_64",
+        "libgenomicsqlite-macos-x86_64.dylib",
+        "bundled_macos_x86_64",
+    ),
+    (
+        "macos",
+        "aarch64",
+        "libgenomicsqlite-macos-aarch64.dylib",
+        "bundled_macos_aarch64",
+    ),
+];
+
+fn main() {
+    // Declare the custom cfg names unconditionally, so rustc's check-cfg
+    // validation accepts them wherever src/lib.rs mentions them.
+    for cand in CANDIDATES {
+        println!("cargo:rustc-check-cfg=cfg({})", cand.3);
+    }
+    println!("cargo:rustc-check-cfg=cfg(bundled_target)");
+
+    let manifest_dir = env::var("CARGO_MANIFEST_DIR").unwrap();
+    let bundling = env::var_os("CARGO_FEATURE_BUNDLE_LIBGENOMICSQLITE").is_some();
+    let target_os = env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
+    let target_arch = env::var("CARGO_CFG_TARGET_ARCH").unwrap_or_default();
+
+    for cand in CANDIDATES {
+        let path = Path::new(&manifest_dir).join(cand.2);
+        // Rerun this script if a bundled library appears or disappears.
+        println!("cargo:rerun-if-changed={}", path.display());
+        if path.is_file() {
+            println!("cargo:rustc-cfg={}", cand.3);
+            if cand.0 == target_os && cand.1 == target_arch {
+                // The compilation target has a bundled library, so one of
+                // the include_bytes! arms in src/lib.rs will be compiled.
+                println!("cargo:rustc-cfg=bundled_target");
+            }
+        } else if bundling && cand.0 == target_os && cand.1 == target_arch {
+            println!(
+                "cargo:warning=genomicsqlite: no bundled {} in the crate for {}-{}; \
+                 the crate will fall back to searching for a system libgenomicsqlite at runtime",
+                cand.2, cand.0, cand.1
+            );
+        }
+    }
+}
diff --git a/bindings/rust/src/lib.rs b/bindings/rust/src/lib.rs
index 6114d7d..c964c83 100644
--- a/bindings/rust/src/lib.rs
+++ b/bindings/rust/src/lib.rs
@@ -7,9 +7,9 @@ use json::object::Object;
 use rusqlite::{params, Connection, LoadExtensionGuard, OpenFlags, Result};
 use std::collections::HashMap;
 use std::env;
-#[cfg(feature = "bundle_libgenomicsqlite")]
+#[cfg(all(feature = "bundle_libgenomicsqlite", bundled_target))]
 use std::fs::File;
-#[cfg(feature = "bundle_libgenomicsqlite")]
+#[cfg(all(feature = "bundle_libgenomicsqlite", bundled_target))]
 use std::io::prelude::*;
 use std::path::Path;
 use std::sync::Once;
@@ -18,7 +18,7 @@ use tempfile::TempDir;
 /* Helper functions for bundling libgenomicsqlite.{so,dylib} into the compilation unit */
 
 // extract slice into basename under a temp directory
-#[cfg(feature = "bundle_libgenomicsqlite")]
+#[cfg(all(feature = "bundle_libgenomicsqlite", bundled_target))]
 fn extract_libgenomicsqlite_impl(
     bytes: &[u8],
     basename: &str,
@@ -40,7 +40,7 @@ fn extract_libgenomicsqlite_impl(
     Ok((libpath, tmp))
 }
 
-#[cfg(feature = "bundle_libgenomicsqlite")]
+#[cfg(all(feature = "bundle_libgenomicsqlite", bundled_target))]
 fn extract_libgenomicsqlite(bytes: &[u8], filename: &str) -> (String, TempDir) {
     match extract_libgenomicsqlite_impl(bytes, filename) {
         Ok(ans) => ans,
@@ -48,27 +48,86 @@ fn extract_libgenomicsqlite(bytes: &[u8], filename: &str) -> (String, TempDir) {
     }
 }
 
-#[cfg(not(feature = "bundle_libgenomicsqlite"))]
+/* Bundled libgenomicsqlite selection.
+ *
+ * With the bundle_libgenomicsqlite feature, the crate may embed a prebuilt
+ * libgenomicsqlite for its target, in a per-OS/architecture file next to
+ * Cargo.toml:
+ *     libgenomicsqlite-linux-x86_64.so    libgenomicsqlite-linux-aarch64.so
+ *     libgenomicsqlite-macos-x86_64.dylib libgenomicsqlite-macos-aarch64.dylib
+ * build.rs inventories which of these files the package actually contains
+ * and sets a matching bundled_* cfg for each one present, so an arm below is
+ * compiled only when its file exists. On any other target -- or when the
+ * target's file isn't bundled -- bundle_libgenomicsqlite() returns None and
+ * open() falls back to the normal library search.
+ */
+
+#[cfg(all(
+    feature = "bundle_libgenomicsqlite",
+    target_os = "linux",
+    target_arch = "x86_64",
+    bundled_linux_x86_64
+))]
 fn bundle_libgenomicsqlite() -> Option<(String, TempDir)> {
-    None
+    Some(extract_libgenomicsqlite(
+        include_bytes!("../libgenomicsqlite-linux-x86_64.so"),
+        "libgenomicsqlite.so",
+    ))
+}
+
+#[cfg(all(
+    feature = "bundle_libgenomicsqlite",
+    target_os = "linux",
+    target_arch = "aarch64",
+    bundled_linux_aarch64
+))]
+fn bundle_libgenomicsqlite() -> Option<(String, TempDir)> {
+    Some(extract_libgenomicsqlite(
+        include_bytes!("../libgenomicsqlite-linux-aarch64.so"),
+        "libgenomicsqlite.so",
+    ))
 }
 
-#[cfg(all(feature = "bundle_libgenomicsqlite", target_os = "linux"))]
+#[cfg(all(
+    feature = "bundle_libgenomicsqlite",
+    target_os = "macos",
+    target_arch = "x86_64",
+    bundled_macos_x86_64
+))]
 fn bundle_libgenomicsqlite() -> Option<(String, TempDir)> {
     Some(extract_libgenomicsqlite(
-        include_bytes!("../libgenomicsqlite.so"),
-        &"libgenomicsqlite.so",
+        include_bytes!("../libgenomicsqlite-macos-x86_64.dylib"),
+        "libgenomicsqlite.dylib",
     ))
 }
 
-#[cfg(all(feature = "bundle_libgenomicsqlite", target_os = "macos"))]
+#[cfg(all(
+    feature = "bundle_libgenomicsqlite",
+    target_os = "macos",
+    target_arch = "aarch64",
+    bundled_macos_aarch64
+))]
 fn bundle_libgenomicsqlite() -> Option<(String, TempDir)> {
     Some(extract_libgenomicsqlite(
-        include_bytes!("../libgenomicsqlite.dylib"),
+        include_bytes!("../libgenomicsqlite-macos-aarch64.dylib"),
         "libgenomicsqlite.dylib",
     ))
 }
 
+#[cfg(not(feature = "bundle_libgenomicsqlite"))]
+fn bundle_libgenomicsqlite() -> Option<(String, TempDir)> {
+    None
+}
+
+// Feature on, but no bundled library for this target (another OS, an
+// architecture the release didn't bundle, or the target's file absent from
+// the package -- build.rs sets bundled_target exactly when one of the
+// bundled arms above applies): fall back to the normal library search.
+#[cfg(all(feature = "bundle_libgenomicsqlite", not(bundled_target)))]
+fn bundle_libgenomicsqlite() -> Option<(String, TempDir)> {
+    None
+}
+
 // helper for simple queries
 fn query1str<P>(conn: &Connection, sql: &str, params: P) -> Result<String>
 where
@@ -104,14 +163,20 @@ pub fn open<P: AsRef<Path>>(path: P, flags: OpenFlags, config: &Object) -> Resul
     // once: load libgenomicsqlite extension
     START.call_once(|| {
         let mut _tmpdir;
-        let libgenomicsqlite = match env::var("LIBGENOMICSQLITE") {
-            Ok(v) => v,
+        // Decide where to load libgenomicsqlite from, remembering how it was
+        // obtained, so a load failure can say exactly what was tried.
+        let (libgenomicsqlite, libgenomicsqlite_source) = match env::var("LIBGENOMICSQLITE") {
+            Ok(v) => (v, "path from the LIBGENOMICSQLITE environment variable"),
             Err(_) => match bundle_libgenomicsqlite() {
                 Some((ans, td)) => {
                     _tmpdir = td;
-                    ans
+                    (ans, "copy bundled into the genomicsqlite crate")
                 }
-                None => "libgenomicsqlite".to_string(),
+                None => (
+                    "libgenomicsqlite".to_string(),
+                    "bare library name, to be searched by the system loader \
+                     (no bundled copy available for this target)",
+                ),
             },
         };
         let memconn = Connection::open_in_memory().unwrap();
@@ -119,8 +184,11 @@ pub fn open<P: AsRef<Path>>(path: P, flags: OpenFlags, config: &Object) -> Resul
             let _guard = LoadExtensionGuard::new(&memconn).unwrap();
             match memconn.load_extension(libgenomicsqlite.clone(), None::<&str>) {
                 Err(err) => panic!(
-                    "genomicsqlite failed to load_extension(\"{}\"): {}",
-                    libgenomicsqlite, err
+                    "genomicsqlite: failed to load_extension(\"{}\") [{}]: {}\n\
+                     genomicsqlite needs a loadable libgenomicsqlite shared library. To provide one:\n\
+                     - set the LIBGENOMICSQLITE environment variable to the path of a locally built libgenomicsqlite, or\n\
+                     - install libgenomicsqlite where the system library loader can find it.",
+                    libgenomicsqlite, libgenomicsqlite_source, err
                 ),
                 Ok(()) => (),
             }

From ca71d6be47dd6164a3c026a53c097d1ecb38aacf Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 14:31:52 -1000
Subject: [PATCH 29/42] Dockerfile: plant bundled library under per-arch name
 in Rust run-up stage (libgenomicsqlite-linux-x86_64.so)

---
 Dockerfile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Dockerfile b/Dockerfile
index 85acdc8..936e445 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -110,7 +110,7 @@ COPY --from=builder /usr/local/lib/libsqlite3.so.0 ./lib/
 RUN ln -s libsqlite3.so.0 lib/libsqlite3.so
 ADD ./.git ./.git
 ADD ./bindings/rust ./rust
-COPY --from=builder /work/GenomicSQLite/build/libgenomicsqlite.so ./rust/
+COPY --from=builder /work/GenomicSQLite/build/libgenomicsqlite.so ./rust/libgenomicsqlite-linux-x86_64.so
 RUN SQLITE_WEB_LOG=99 LD_LIBRARY_PATH=$(pwd)/lib LIBRARY_PATH=$(pwd)/lib rust/cargo test --release
 
 ###################################################################################################

From 137cb92faf94ad025fc2d677ec92efeded7b7cdb Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 15:39:55 -1000
Subject: [PATCH 30/42] Rename build.yml to .github/workflows/build.yml

---
 build.yml => .github/workflows/build.yml | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename build.yml => .github/workflows/build.yml (100%)

diff --git a/build.yml b/.github/workflows/build.yml
similarity index 100%
rename from build.yml
rename to .github/workflows/build.yml

From 43545ba9fa30475aaa8215e1bf6d0f2e5505b48e Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 16:33:31 -1000
Subject: [PATCH 31/42] Dockerfile: build portable .so with
 _GLIBCXX_USE_CXX11_ABI=0 (restore historical C++ ABI; Alma stock GCC defaults
 to ABI=1, breaking ABI=0 loader/test executables)

---
 Dockerfile | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/Dockerfile b/Dockerfile
index 936e445..fb9f891 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -60,7 +60,13 @@ RUN ldconfig
 ADD . /work/GenomicSQLite
 WORKDIR /work/GenomicSQLite
 RUN rm -rf build
-RUN cmake -DCMAKE_BUILD_TYPE=Release -DZSTD_WHOLE_ARCHIVE=true -B build . && cmake --build build --target genomicsqlite -j $(nproc)
+# _GLIBCXX_USE_CXX11_ABI=0: the header's C++ API passes std::string across the
+# library boundary, so the .so's C++ ABI is part of its public contract. Keep the
+# pre-C++11 libstdc++ ABI -- the artifact's historical ABI (the old CentOS
+# devtoolset toolchain defaulted to it) and the ABI the CI workflow compiles the
+# loader/test executables with. Stock AlmaLinux GCC defaults to ABI=1, which
+# silently changes the exported symbols and breaks those executables.
+RUN cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS="${CXXFLAGS} -D_GLIBCXX_USE_CXX11_ABI=0" -DZSTD_WHOLE_ARCHIVE=true -B build . && cmake --build build --target genomicsqlite -j $(nproc)
 RUN sqlite3 -cmd '.load build/libgenomicsqlite.so' :memory: 'select sqlite_version(); select genomicsqlite_version()'
 
 

From 4edbadf0362ad95a6feab7835fb458fac9afb23f Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 17:45:06 -1000
Subject: [PATCH 32/42] CI: stage build.yml (portable step-7: put the portable
 build's own sqlite3 shell first on PATH) for rename to
 .github/workflows/build.yml

---
 build.yml | 234 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 234 insertions(+)
 create mode 100644 build.yml

diff --git a/build.yml b/build.yml
new file mode 100644
index 0000000..b1e7ee9
--- /dev/null
+++ b/build.yml
@@ -0,0 +1,234 @@
+name: build
+on: [push, pull_request]
+
+env:
+  APT_DEPS: libzstd-dev samtools tabix libhts-dev pigz python3-pip
+  BREW_DEPS: zstd samtools pigz coreutils sqlite python@3.12
+  PIP_DEPS: pytest pytest-xdist
+
+jobs:
+
+  lint:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: deps
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y clang-format cppcheck python3-pip python3-venv
+        python3 -m venv "$HOME/.lint-venv"
+        "$HOME/.lint-venv/bin/pip" install pre-commit $PIP_DEPS black flake8 pylint
+        echo "$HOME/.lint-venv/bin" >> "$GITHUB_PATH"
+    - name: pre-commit
+      run: pre-commit run --all-files
+    - name: mvn spotless:check
+      run: mvn spotless:check -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+      with:
+        components: rustfmt, clippy
+    - name: rust lint
+      run: |
+        cd bindings/rust
+        bash ./cargo check --no-default-features
+        bash ./cargo fmt -- --check
+
+  test:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        BUILD_TYPE: [Debug, Release]
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: deps
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y $APT_DEPS
+        sudo pip3 install --break-system-packages $PIP_DEPS
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: build
+      run: cmake -DCMAKE_BUILD_TYPE=${{ matrix.BUILD_TYPE }} -B build . && cmake --build build -j $(nproc)
+    - name: test
+      run: env -C build SQLITE_WEB_LOG=99 ctest -V
+
+  linux-x86-64-so:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: build loaders
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y $APT_DEPS
+        sudo pip3 install --break-system-packages $PIP_DEPS
+        cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS='-D_GLIBCXX_USE_CXX11_ABI=0' -B build . && cmake --build build -j $(nproc)
+        rm build/libgenomicsqlite.so
+        sudo apt-get remove -y libzstd-dev  # should be linked into libgenomicsqlite.so
+    - name: build portable .so in docker
+      run: docker build -t genomicsqlite . && docker run -v $(pwd):/mnt --rm genomicsqlite cp /usr/local/lib/{libgenomicsqlite.so,libsqlite3.so.0} /usr/local/bin/sqlite3 /mnt/build/
+    - name: symbols & digests
+      run: |
+        readelf -d build/libgenomicsqlite.so
+        ldd -r build/libgenomicsqlite.so
+        echo "----"
+        echo "libgenomicsqlite.so GLIBC version requirements:"
+        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBC_.*' | sort -Vr | head -n1
+        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBCXX_.*' | sort -Vr | head -n1
+        echo "libsqlite3.so.0 GLIBC version requirements:"
+        objdump -t build/libsqlite3.so.0 | grep -o 'GLIBC_.*' | sort -Vr | head -n1
+        echo "----"
+        sha256sum build/libgenomicsqlite.so build/libsqlite3.so.0
+        echo "asserting manylinux_2_28 floor (GLIBC <= 2.28, GLIBCXX <= 3.4.25):"
+        for f in build/libgenomicsqlite.so build/libsqlite3.so.0; do
+          max_glibc=$(objdump -t $f | grep -oE 'GLIBC_[0-9.]+' | sort -Vu | tail -n1)
+          echo "$f max GLIBC need: $max_glibc"
+          if [ "$(printf 'GLIBC_2.28\n%s\n' "$max_glibc" | sort -V | tail -n1)" != "GLIBC_2.28" ]; then
+            echo "$f requires $max_glibc, above the glibc 2.28 floor" >&2
+            exit 1
+          fi
+        done
+        max_glibcxx=$(objdump -t build/libgenomicsqlite.so | grep -oE 'GLIBCXX_[0-9.]+' | sort -Vu | tail -n1)
+        echo "build/libgenomicsqlite.so max GLIBCXX need: $max_glibcxx"
+        if [ "$(printf 'GLIBCXX_3.4.25\n%s\n' "$max_glibcxx" | sort -V | tail -n1)" != "GLIBCXX_3.4.25" ]; then
+          echo "build/libgenomicsqlite.so requires $max_glibcxx, above the GLIBCXX 3.4.25 ceiling" >&2
+          exit 1
+        fi
+        sudo cp build/libsqlite3.so.0 /usr/local/lib
+        sudo ldconfig
+        # Pair like with like: the ldconfig plant above makes the portable
+        # libsqlite3.so.0 (3.41.2) shadow the system one, so the runner's own
+        # sqlite3 shell (built against >= 3.42) dies at startup with
+        # "undefined symbol: sqlite3_stmt_explain". Put the portable build's
+        # own shell -- copied out of the docker image into build/ in the
+        # previous step -- first on PATH for the remaining steps, so the
+        # portable test exercises the CLI against the exact SQLite vintage
+        # the portable library ships with. (Later steps do not look up a
+        # sqlite3 shell by name, so the prepend is harmless to them.)
+        echo "$(pwd)/build" >> "$GITHUB_PATH"
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: test portable .so
+      run: env -C build SQLITE_WEB_LOG=99 ctest -V
+    - name: test rust crate
+      run: |
+        set -e
+        cp build/libgenomicsqlite.so bindings/rust/libgenomicsqlite-linux-x86_64.so
+        SQLITE_WEB_LOG=99 bash bindings/rust/cargo test --release
+        bash bindings/rust/cargo package --list | grep libgenomicsqlite-linux-x86_64.so
+    - name: prepare artifacts
+      run: cp build/{libgenomicsqlite.so,libsqlite3.so.0} .
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libgenomicsqlite.so
+        path: libgenomicsqlite.so
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libsqlite3.so.0
+        path: libsqlite3.so.0
+
+  macOS-arm64-dylib:
+    runs-on: macos-15
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: dependencies
+      run: |
+        rm -f $(brew --prefix)/bin/2to3  # https://github.com/pypa/pipenv/issues/3831
+        brew update || (sleep 2; brew update)
+        for dep in $BREW_DEPS ; do
+          brew install $dep || brew upgrade $dep
+        done
+
+        # The tests must run under Homebrew's Python: it is configured with
+        # --enable-loadable-sqlite-extensions (the binding cannot be imported
+        # without sqlite3.Connection.enable_load_extension), while the
+        # image's python.org framework Python is built without it.
+        echo "$(brew --prefix)/opt/python@3.12/bin" >> "$GITHUB_PATH"
+        export PATH="$(brew --prefix)/opt/python@3.12/bin:$PATH"
+        python3 -m pip install --break-system-packages $PIP_DEPS
+        python3 -c "import sqlite3; assert hasattr(sqlite3.Connection, 'enable_load_extension')"
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: build environment
+      run: |
+        echo "PATH=$(brew --prefix)/opt/python@3.12/bin:$(brew --prefix)/bin:$(brew --prefix)/opt/sqlite/bin:${PATH}" >> $GITHUB_ENV
+        echo "CFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "CXXFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "LDFLAGS=-L$(brew --prefix)/lib -L$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
+        # used by rusqlite:
+        echo "SQLITE3_INCLUDE_DIR=$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "SQLITE3_LIB_DIR=$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
+    - name: build
+      run: |
+        cmake -DCMAKE_BUILD_TYPE=Release \
+              -DCMAKE_PREFIX_PATH=$(brew --prefix)/opt/sqlite \
+              -B build .
+        cmake --build build -j 4
+    - name: symbols & digests
+      run: |
+        otool -L build/libgenomicsqlite.dylib
+        sha256sum build/libgenomicsqlite.dylib
+    - name: ctest
+      run: |
+        cd build
+        otool -L test/capi_smoke_test
+        SQLITE_WEB_LOG=99 ctest -V
+    - name: test rust crate
+      run: |
+        set -e
+        cp build/libgenomicsqlite.dylib bindings/rust/libgenomicsqlite-macos-aarch64.dylib
+        SQLITE_WEB_LOG=99 bash bindings/rust/cargo test --release
+        bash bindings/rust/cargo package --list | grep libgenomicsqlite-macos-aarch64.dylib
+    - name: prepare artifacts
+      run: cp build/libgenomicsqlite.dylib include/genomicsqlite.h .
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libgenomicsqlite.dylib
+        path: libgenomicsqlite.dylib
+
+  artifacts:
+    runs-on: ubuntu-24.04
+    needs: [linux-x86-64-so, macOS-arm64-dylib]
+    steps:
+    - uses: actions/checkout@v7
+    - name: fetch libgenomicsqlite.so
+      uses: actions/download-artifact@v8
+      with:
+        name: libgenomicsqlite.so
+    - name: fetch libsqlite3.so.0
+      uses: actions/download-artifact@v8
+      with:
+        name: libsqlite3.so.0
+    - name: fetch libgenomicsqlite.dylib
+      uses: actions/download-artifact@v8
+      with:
+        name: libgenomicsqlite.dylib
+    - name: detect GIT_REVISION
+      run: |
+        cp include/genomicsqlite.h .
+        echo "GIT_REVISION=$(git describe --tags --always)" >> $GITHUB_ENV
+    - uses: actions/upload-artifact@v7
+      with:
+        name: GenomicSQLite-${{ env.GIT_REVISION }}
+        path: |
+          LICENSE
+          genomicsqlite.h
+          libgenomicsqlite.so
+          libgenomicsqlite.dylib
+    - name: build jar
+      run: |
+        cp libgenomicsqlite.so libgenomicsqlite.dylib bindings/jdbc/genomicsqlite-jdbc/src/main/resources/
+        mvn deploy -Drevision=${{ env.GIT_REVISION }} -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
+    - name: digests
+      run: sha256sum *genomicsqlite* bindings/jdbc/genomicsqlite-jdbc/target/genomicsqlite*.jar libsqlite3.so.0
+    - uses: actions/upload-artifact@v7
+      with:
+        name: genomicsqlite-jdbc-${{ env.GIT_REVISION }}
+        path: bindings/jdbc/genomicsqlite-jdbc/target/mvn-repo

From 0eeb95e1a4226b7c7508a237d6b2de0fea7d67d2 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 17:45:22 -1000
Subject: [PATCH 33/42] CI: remove .github/workflows/build.yml ahead of staged
 replacement

---
 .github/workflows/build.yml | 224 ------------------------------------
 1 file changed, 224 deletions(-)
 delete mode 100644 .github/workflows/build.yml

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
deleted file mode 100644
index 04b5568..0000000
--- a/.github/workflows/build.yml
+++ /dev/null
@@ -1,224 +0,0 @@
-name: build
-on: [push, pull_request]
-
-env:
-  APT_DEPS: libzstd-dev samtools tabix libhts-dev pigz python3-pip
-  BREW_DEPS: zstd samtools pigz coreutils sqlite python@3.12
-  PIP_DEPS: pytest pytest-xdist
-
-jobs:
-
-  lint:
-    runs-on: ubuntu-24.04
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: deps
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y clang-format cppcheck python3-pip python3-venv
-        python3 -m venv "$HOME/.lint-venv"
-        "$HOME/.lint-venv/bin/pip" install pre-commit $PIP_DEPS black flake8 pylint
-        echo "$HOME/.lint-venv/bin" >> "$GITHUB_PATH"
-    - name: pre-commit
-      run: pre-commit run --all-files
-    - name: mvn spotless:check
-      run: mvn spotless:check -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-      with:
-        components: rustfmt, clippy
-    - name: rust lint
-      run: |
-        cd bindings/rust
-        bash ./cargo check --no-default-features
-        bash ./cargo fmt -- --check
-
-  test:
-    runs-on: ubuntu-24.04
-    strategy:
-      matrix:
-        BUILD_TYPE: [Debug, Release]
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: deps
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y $APT_DEPS
-        sudo pip3 install --break-system-packages $PIP_DEPS
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: build
-      run: cmake -DCMAKE_BUILD_TYPE=${{ matrix.BUILD_TYPE }} -B build . && cmake --build build -j $(nproc)
-    - name: test
-      run: env -C build SQLITE_WEB_LOG=99 ctest -V
-
-  linux-x86-64-so:
-    runs-on: ubuntu-24.04
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: build loaders
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y $APT_DEPS
-        sudo pip3 install --break-system-packages $PIP_DEPS
-        cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS='-D_GLIBCXX_USE_CXX11_ABI=0' -B build . && cmake --build build -j $(nproc)
-        rm build/libgenomicsqlite.so
-        sudo apt-get remove -y libzstd-dev  # should be linked into libgenomicsqlite.so
-    - name: build portable .so in docker
-      run: docker build -t genomicsqlite . && docker run -v $(pwd):/mnt --rm genomicsqlite cp /usr/local/lib/{libgenomicsqlite.so,libsqlite3.so.0} /mnt/build/
-    - name: symbols & digests
-      run: |
-        readelf -d build/libgenomicsqlite.so
-        ldd -r build/libgenomicsqlite.so
-        echo "----"
-        echo "libgenomicsqlite.so GLIBC version requirements:"
-        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBC_.*' | sort -Vr | head -n1
-        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBCXX_.*' | sort -Vr | head -n1
-        echo "libsqlite3.so.0 GLIBC version requirements:"
-        objdump -t build/libsqlite3.so.0 | grep -o 'GLIBC_.*' | sort -Vr | head -n1
-        echo "----"
-        sha256sum build/libgenomicsqlite.so build/libsqlite3.so.0
-        echo "asserting manylinux_2_28 floor (GLIBC <= 2.28, GLIBCXX <= 3.4.25):"
-        for f in build/libgenomicsqlite.so build/libsqlite3.so.0; do
-          max_glibc=$(objdump -t $f | grep -oE 'GLIBC_[0-9.]+' | sort -Vu | tail -n1)
-          echo "$f max GLIBC need: $max_glibc"
-          if [ "$(printf 'GLIBC_2.28\n%s\n' "$max_glibc" | sort -V | tail -n1)" != "GLIBC_2.28" ]; then
-            echo "$f requires $max_glibc, above the glibc 2.28 floor" >&2
-            exit 1
-          fi
-        done
-        max_glibcxx=$(objdump -t build/libgenomicsqlite.so | grep -oE 'GLIBCXX_[0-9.]+' | sort -Vu | tail -n1)
-        echo "build/libgenomicsqlite.so max GLIBCXX need: $max_glibcxx"
-        if [ "$(printf 'GLIBCXX_3.4.25\n%s\n' "$max_glibcxx" | sort -V | tail -n1)" != "GLIBCXX_3.4.25" ]; then
-          echo "build/libgenomicsqlite.so requires $max_glibcxx, above the GLIBCXX 3.4.25 ceiling" >&2
-          exit 1
-        fi
-        sudo cp build/libsqlite3.so.0 /usr/local/lib
-        sudo ldconfig
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: test portable .so
-      run: env -C build SQLITE_WEB_LOG=99 ctest -V
-    - name: test rust crate
-      run: |
-        set -e
-        cp build/libgenomicsqlite.so bindings/rust/libgenomicsqlite-linux-x86_64.so
-        SQLITE_WEB_LOG=99 bash bindings/rust/cargo test --release
-        bash bindings/rust/cargo package --list | grep libgenomicsqlite-linux-x86_64.so
-    - name: prepare artifacts
-      run: cp build/{libgenomicsqlite.so,libsqlite3.so.0} .
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libgenomicsqlite.so
-        path: libgenomicsqlite.so
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libsqlite3.so.0
-        path: libsqlite3.so.0
-
-  macOS-arm64-dylib:
-    runs-on: macos-15
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: dependencies
-      run: |
-        rm -f $(brew --prefix)/bin/2to3  # https://github.com/pypa/pipenv/issues/3831
-        brew update || (sleep 2; brew update)
-        for dep in $BREW_DEPS ; do
-          brew install $dep || brew upgrade $dep
-        done
-
-        # The tests must run under Homebrew's Python: it is configured with
-        # --enable-loadable-sqlite-extensions (the binding cannot be imported
-        # without sqlite3.Connection.enable_load_extension), while the
-        # image's python.org framework Python is built without it.
-        echo "$(brew --prefix)/opt/python@3.12/bin" >> "$GITHUB_PATH"
-        export PATH="$(brew --prefix)/opt/python@3.12/bin:$PATH"
-        python3 -m pip install --break-system-packages $PIP_DEPS
-        python3 -c "import sqlite3; assert hasattr(sqlite3.Connection, 'enable_load_extension')"
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: build environment
-      run: |
-        echo "PATH=$(brew --prefix)/opt/python@3.12/bin:$(brew --prefix)/bin:$(brew --prefix)/opt/sqlite/bin:${PATH}" >> $GITHUB_ENV
-        echo "CFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "CXXFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "LDFLAGS=-L$(brew --prefix)/lib -L$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
-        # used by rusqlite:
-        echo "SQLITE3_INCLUDE_DIR=$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "SQLITE3_LIB_DIR=$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
-    - name: build
-      run: |
-        cmake -DCMAKE_BUILD_TYPE=Release \
-              -DCMAKE_PREFIX_PATH=$(brew --prefix)/opt/sqlite \
-              -B build .
-        cmake --build build -j 4
-    - name: symbols & digests
-      run: |
-        otool -L build/libgenomicsqlite.dylib
-        sha256sum build/libgenomicsqlite.dylib
-    - name: ctest
-      run: |
-        cd build
-        otool -L test/capi_smoke_test
-        SQLITE_WEB_LOG=99 ctest -V
-    - name: test rust crate
-      run: |
-        set -e
-        cp build/libgenomicsqlite.dylib bindings/rust/libgenomicsqlite-macos-aarch64.dylib
-        SQLITE_WEB_LOG=99 bash bindings/rust/cargo test --release
-        bash bindings/rust/cargo package --list | grep libgenomicsqlite-macos-aarch64.dylib
-    - name: prepare artifacts
-      run: cp build/libgenomicsqlite.dylib include/genomicsqlite.h .
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libgenomicsqlite.dylib
-        path: libgenomicsqlite.dylib
-
-  artifacts:
-    runs-on: ubuntu-24.04
-    needs: [linux-x86-64-so, macOS-arm64-dylib]
-    steps:
-    - uses: actions/checkout@v7
-    - name: fetch libgenomicsqlite.so
-      uses: actions/download-artifact@v8
-      with:
-        name: libgenomicsqlite.so
-    - name: fetch libsqlite3.so.0
-      uses: actions/download-artifact@v8
-      with:
-        name: libsqlite3.so.0
-    - name: fetch libgenomicsqlite.dylib
-      uses: actions/download-artifact@v8
-      with:
-        name: libgenomicsqlite.dylib
-    - name: detect GIT_REVISION
-      run: |
-        cp include/genomicsqlite.h .
-        echo "GIT_REVISION=$(git describe --tags --always)" >> $GITHUB_ENV
-    - uses: actions/upload-artifact@v7
-      with:
-        name: GenomicSQLite-${{ env.GIT_REVISION }}
-        path: |
-          LICENSE
-          genomicsqlite.h
-          libgenomicsqlite.so
-          libgenomicsqlite.dylib
-    - name: build jar
-      run: |
-        cp libgenomicsqlite.so libgenomicsqlite.dylib bindings/jdbc/genomicsqlite-jdbc/src/main/resources/
-        mvn deploy -Drevision=${{ env.GIT_REVISION }} -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
-    - name: digests
-      run: sha256sum *genomicsqlite* bindings/jdbc/genomicsqlite-jdbc/target/genomicsqlite*.jar libsqlite3.so.0
-    - uses: actions/upload-artifact@v7
-      with:
-        name: genomicsqlite-jdbc-${{ env.GIT_REVISION }}
-        path: bindings/jdbc/genomicsqlite-jdbc/target/mvn-repo

From 320406566082be1d48361b73908c1e40208eae7c Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 17:46:40 -1000
Subject: [PATCH 34/42] Rename build.yml to .github/workflows/build.yml

---
 build.yml => .github/workflows/build.yml | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename build.yml => .github/workflows/build.yml (100%)

diff --git a/build.yml b/.github/workflows/build.yml
similarity index 100%
rename from build.yml
rename to .github/workflows/build.yml

From 4c4f5deb26e2be807ac7ad2b76bd9f03311ac3df Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 18:04:31 -1000
Subject: [PATCH 35/42] Rust crate: drop macOS x86_64 from the bundled-library
 matrix

macOS CI is ARM-only (R1), so the supported bundled set is three
targets: linux x86_64, linux aarch64, macOS aarch64. macos/x86_64
now takes the catch-all fallback (system library search) like any
other unsupported target, with no build.rs warning.
---
 bindings/rust/build.rs   | 14 ++++++--------
 bindings/rust/src/lib.rs | 20 +++++---------------
 2 files changed, 11 insertions(+), 23 deletions(-)

diff --git a/bindings/rust/build.rs b/bindings/rust/build.rs
index cb6b9f8..5460adf 100644
--- a/bindings/rust/build.rs
+++ b/bindings/rust/build.rs
@@ -3,8 +3,12 @@
 //
 // A bundled library is embedded into the compilation unit only for the
 // target it was built for, under a per-OS/architecture file name:
-//     libgenomicsqlite-linux-x86_64.so    libgenomicsqlite-linux-aarch64.so
-//     libgenomicsqlite-macos-x86_64.dylib libgenomicsqlite-macos-aarch64.dylib
+//     libgenomicsqlite-linux-x86_64.so
+//     libgenomicsqlite-linux-aarch64.so
+//     libgenomicsqlite-macos-aarch64.dylib
+// macOS x86_64 is deliberately not a bundled target (macOS CI builds
+// ARM-only), so it falls back to the runtime library search like any
+// other unsupported target.
 // For each candidate file that actually exists in the package, this script
 // sets a rustc cfg (bundled_linux_x86_64 etc.) gating the corresponding
 // include_bytes! arm in src/lib.rs. A missing file therefore degrades to
@@ -27,12 +31,6 @@ const CANDIDATES: &[(&str, &str, &str, &str)] = &[
         "libgenomicsqlite-linux-aarch64.so",
         "bundled_linux_aarch64",
     ),
-    (
-        "macos",
-        "x86_64",
-        "libgenomicsqlite-macos-x86_64.dylib",
-        "bundled_macos_x86_64",
-    ),
     (
         "macos",
         "aarch64",
diff --git a/bindings/rust/src/lib.rs b/bindings/rust/src/lib.rs
index c964c83..1cdc6c7 100644
--- a/bindings/rust/src/lib.rs
+++ b/bindings/rust/src/lib.rs
@@ -53,8 +53,11 @@ fn extract_libgenomicsqlite(bytes: &[u8], filename: &str) -> (String, TempDir) {
  * With the bundle_libgenomicsqlite feature, the crate may embed a prebuilt
  * libgenomicsqlite for its target, in a per-OS/architecture file next to
  * Cargo.toml:
- *     libgenomicsqlite-linux-x86_64.so    libgenomicsqlite-linux-aarch64.so
- *     libgenomicsqlite-macos-x86_64.dylib libgenomicsqlite-macos-aarch64.dylib
+ *     libgenomicsqlite-linux-x86_64.so
+ *     libgenomicsqlite-linux-aarch64.so
+ *     libgenomicsqlite-macos-aarch64.dylib
+ * macOS x86_64 is deliberately not bundled (macOS CI builds ARM-only);
+ * it takes the fallback path below like any other unsupported target.
  * build.rs inventories which of these files the package actually contains
  * and sets a matching bundled_* cfg for each one present, so an arm below is
  * compiled only when its file exists. On any other target -- or when the
@@ -88,19 +91,6 @@ fn bundle_libgenomicsqlite() -> Option<(String, TempDir)> {
     ))
 }
 
-#[cfg(all(
-    feature = "bundle_libgenomicsqlite",
-    target_os = "macos",
-    target_arch = "x86_64",
-    bundled_macos_x86_64
-))]
-fn bundle_libgenomicsqlite() -> Option<(String, TempDir)> {
-    Some(extract_libgenomicsqlite(
-        include_bytes!("../libgenomicsqlite-macos-x86_64.dylib"),
-        "libgenomicsqlite.dylib",
-    ))
-}
-
 #[cfg(all(
     feature = "bundle_libgenomicsqlite",
     target_os = "macos",

From d837e95f3ab46966d05fd89a13f638cc7981c662 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 19:49:43 -1000
Subject: [PATCH 36/42] Advance portable-build SQLite pin 3.41.2 -> 3.54.1

Per the project's SQLite version policy: the bundled/portable build's pin
tracks the newest upstream release at each maintenance touch (3.54.1,
released 2026-10-16). Runtime floor (3.31.0) and version gates unchanged.

Rehearsed locally in AlmaLinux 8 (udocker): builder builds clean,
sqlite_version()=3.54.1; libsqlite3.so.0 GLIBC ceiling stays exactly
2.28; step-7-shaped ctest 5/5 with the paired portable shell.
---
 Dockerfile | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Dockerfile b/Dockerfile
index fb9f891..c6e8d61 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -4,7 +4,7 @@
 FROM almalinux:8 as builder
 
 ARG CMAKE_VERSION=3.17.3
-ARG SQLITE_VERSION=3410200
+ARG SQLITE_VERSION=3540100
 ARG ZSTD_VERSION=1.5.5
 ARG CPU_ARCH=ivybridge
 ENV CFLAGS="-march=${CPU_ARCH} -O3"
@@ -34,7 +34,7 @@ RUN mkdir -p /work/GenomicSQLite
 
 # SQLite
 WORKDIR /work
-RUN wget -nv http://www.sqlite.org/2023/sqlite-amalgamation-${SQLITE_VERSION}.zip \
+RUN wget -nv http://www.sqlite.org/2026/sqlite-amalgamation-${SQLITE_VERSION}.zip \
         && unzip -o sqlite-amalgamation-${SQLITE_VERSION}.zip
 WORKDIR /work/sqlite-amalgamation-${SQLITE_VERSION}
 RUN bash -c "gcc -shared -o libsqlite3.so.0 -fPIC -shared -Wl,-soname,libsqlite3.so.0 -g ${CFLAGS} ${SQLITE_CFLAGS} sqlite3.c & pid=$? \

From 532b01dc2961b7754149c32bff177b3896e432ff Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 20:30:31 -1000
Subject: [PATCH 37/42] Python formatting/linting: migrate black+flake8+pylint
 to ruff (format + check)

---
 .pre-commit-config.yaml                   | 27 ++-----
 README.md                                 |  2 +-
 bindings/python/genomicsqlite/__init__.py |  6 +-
 bindings/python/version.py                |  6 +-
 docs/guide_db.md                          |  6 +-
 docs/guide_gri.md                         | 42 +++++------
 docs/guide_helpers.md                     | 10 +--
 docs/internals.md                         | 18 +++--
 ruff.toml                                 | 89 +++++++++++++++++++++++
 test/genomicsqlite_smoke_test.py          | 12 +--
 test/test_bam.py                          |  6 +-
 11 files changed, 152 insertions(+), 72 deletions(-)
 create mode 100644 ruff.toml

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 269465d..3e9dcfd 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -17,25 +17,12 @@ repos:
     verbose: true
     entry: cppcheck
     args: [-q,--std=c++11]
-  - id: black
-    name: black
-    language: system
-    files: \.py$
-    verbose: true
-    entry: black
-    args: [-l,'100']
-  - id: flake8
-    name: flake8
-    language: system
-    files: \.py$
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.17.1
+  hooks:
+  - id: ruff-check
+    name: ruff-check
     verbose: true
-    entry: flake8
-    args: [--max-line-length, "100", "--ignore=E501,W503,E722"]
-  - id: pylint
-    name: pylint
-    language: system
-    files: \.py$
-    exclude: version\.py
+  - id: ruff-format
+    name: ruff-format
     verbose: true
-    entry: env PYTHONPATH=bindings/python pylint
-    args: [-d, "global-statement,missing-docstring,missing-module-docstring,line-too-long,too-many-arguments,too-many-positional-arguments,duplicate-code,redefined-outer-name,too-many-locals,bare-except,broad-except,import-outside-toplevel,protected-access,too-many-statements,too-many-branches,unspecified-encoding"]
diff --git a/README.md b/README.md
index 313a0b9..a75793a 100644
--- a/README.md
+++ b/README.md
@@ -54,7 +54,7 @@ cmake --build build -j 4 --target genomicsqlite
 
 * htslib &ge; 1.9, samtools, and tabix
 * pigz
-* Python &ge; 3.6 and packages: pytest pytest-xdist pre-commit black pylint flake8 
+* Python &ge; 3.6 and packages: pytest pytest-xdist pre-commit ruff
 * JDK, mvn, rust
 * clang-format & cppcheck
 
diff --git a/bindings/python/genomicsqlite/__init__.py b/bindings/python/genomicsqlite/__init__.py
index e91da64..8325660 100644
--- a/bindings/python/genomicsqlite/__init__.py
+++ b/bindings/python/genomicsqlite/__init__.py
@@ -174,9 +174,9 @@ def get_reference_sequences_by_rid(
         params = (assembly,)
     ans = {}
     for row in con.execute(sql, params):
-        assert (
-            isinstance(row[0], int) and row[0] not in ans
-        ), "genomicsqlite: invalid or duplicate reference sequence rid"
+        assert isinstance(row[0], int) and row[0] not in ans, (
+            "genomicsqlite: invalid or duplicate reference sequence rid"
+        )
         ans[row[0]] = ReferenceSequence(
             rid=row[0],
             name=row[1],
diff --git a/bindings/python/version.py b/bindings/python/version.py
index 5b7cfd8..964f594 100644
--- a/bindings/python/version.py
+++ b/bindings/python/version.py
@@ -76,7 +76,7 @@ def read_git_version():
         return None
     match = re.search(_GIT_DESCRIPTION_RE, ver)
     if not match:
-        sys.stderr.write("version: git description (%s) is invalid, " "ignoring\n" % ver)
+        sys.stderr.write("version: git description (%s) is invalid, ignoring\n" % ver)
         return None
 
     commits = int(match.group("commits"))
@@ -90,9 +90,7 @@ def read_release_version():
         with open(RELEASE_VERSION_FILE) as infile:
             ver = infile.readline().strip()
         if not re.search(_PEP386_VERSION_RE, ver):
-            sys.stderr.write(
-                "version: release version (%s) is invalid, " "will use it anyway\n" % ver
-            )
+            sys.stderr.write("version: release version (%s) is invalid, will use it anyway\n" % ver)
         return ver
     except:
         return None
diff --git a/docs/guide_db.md b/docs/guide_db.md
index 7b8abea..ac7ad07 100644
--- a/docs/guide_db.md
+++ b/docs/guide_db.md
@@ -94,9 +94,9 @@ First complete the [installation instructions](index.md).
 === "Python"
     ``` python3
     dbconn = genomicsqlite.connect(
-      db_filename,
-      read_only=False,
-      **kwargs  #  genomicsqlite + sqlite3.connect() arguments
+        db_filename,
+        read_only=False,
+        **kwargs,  #  genomicsqlite + sqlite3.connect() arguments
     )
     assert isinstance(dbconn, sqlite3.Connection)
     ```
diff --git a/docs/guide_gri.md b/docs/guide_gri.md
index 8bf7f66..747e0db 100644
--- a/docs/guide_gri.md
+++ b/docs/guide_gri.md
@@ -21,11 +21,7 @@ The extension provides routines to populate a small `_gri_refseq` table describi
 === "Python"
     ``` python3
     create_gri_sql = genomicsqlite.create_genomic_range_index_sql(
-      dbconn,
-      'tableName',
-      'chromosome',
-      'beginPosition',
-      'endPosition'
+        dbconn, "tableName", "chromosome", "beginPosition", "endPosition"
     )
     dbconn.executescript(create_gri_sql)
     ```
@@ -229,9 +225,7 @@ The following routines support the aforementioned, recommended convention for st
 
 === "Python"
     ``` python3
-    refseq_sql = genomicsqlite.put_reference_assembly_sql(
-      dbconn, 'GRCh38_no_alt_analysis_set'
-    )
+    refseq_sql = genomicsqlite.put_reference_assembly_sql(dbconn, "GRCh38_no_alt_analysis_set")
     dbconn.executescript(refseq_sql)
     ```
 
@@ -307,8 +301,10 @@ Available assemblies:
 === "Python"
     ``` python3
     refseq_sql = genomicsqlite.put_reference_sequence_sql(
-      dbconn, 'chr17', 83257441
-      # optional: assembly, refget_id, meta (dict), rid
+        dbconn,
+        "chr17",
+        83257441,
+        # optional: assembly, refget_id, meta (dict), rid
     )
     dbconn.executescript(refseq_sql)
     ```
@@ -407,12 +403,13 @@ If the `rid` argument is omitted or -1 then it will be assigned automatically up
 === "Python"
     ``` python3
     class ReferenceSequence(NamedTuple):
-      rid: int
-      name: str
-      length: int
-      assembly: Optional[str]
-      refget_id: Optional[str]
-      meta: Dict[str, Any]
+        rid: int
+        name: str
+        length: int
+        assembly: Optional[str]
+        refget_id: Optional[str]
+        meta: Dict[str, Any]
+
 
     refseq_by_rid = genomicsqlite.get_reference_sequences_by_rid(dbconn)
     # refseq_by_rid: Dict[int, ReferenceSequence]
@@ -492,12 +489,13 @@ The optional `assembly` argument restricts the retrieved sequences to those with
 === "Python"
     ``` python3
     class ReferenceSequence(NamedTuple):
-      rid: int
-      name: str
-      length: int
-      assembly: Optional[str]
-      refget_id: Optional[str]
-      meta: Dict[str, Any]
+        rid: int
+        name: str
+        length: int
+        assembly: Optional[str]
+        refget_id: Optional[str]
+        meta: Dict[str, Any]
+
 
     refseq_by_name = genomicsqlite.get_reference_sequences_by_name(dbconn)
     # refseq_by_name: Dict[str, ReferenceSequence]
diff --git a/docs/guide_helpers.md b/docs/guide_helpers.md
index d1cd9a7..95bc3e3 100644
--- a/docs/guide_helpers.md
+++ b/docs/guide_helpers.md
@@ -88,8 +88,8 @@ The [UINT collating sequence](https://www.sqlite.org/uintcseq.html) is also bund
 
 === "Python"
     ``` python3
-    dbconn = sqlite3.connect('any.db', uri=True)
-    attach_sql = genomicsqlite.attach_sql(dbconn, 'compressed.db', 'db2')
+    dbconn = sqlite3.connect("any.db", uri=True)
+    attach_sql = genomicsqlite.attach_sql(dbconn, "compressed.db", "db2")
     # attach_sql() also takes configuration keyword arguments like
     # genomicsqlite.connect()
     dbconn.executescript(attach_sql)
@@ -190,13 +190,13 @@ The [UINT collating sequence](https://www.sqlite.org/uintcseq.html) is also bund
 
 === "Python"
     ``` python3
-    dbconn = sqlite3.connect('existing.db', uri=True)
-    vacuum_sql = genomicsqlite.vacuum_into_sql(dbconn, 'compressed.db')
+    dbconn = sqlite3.connect("existing.db", uri=True)
+    vacuum_sql = genomicsqlite.vacuum_into_sql(dbconn, "compressed.db")
     # vacuum_into_sql() also takes configuration keyword arguments like
     # genomicsqlite.connect() to control compression level & page sizes
 
     dbconn.executescript(vacuum_sql)
-    dbconn2 = genomicsqlite.connect('compressed.db')
+    dbconn2 = genomicsqlite.connect("compressed.db")
     ```
 
 === "Java"
diff --git a/docs/internals.md b/docs/internals.md
index df34720..01dd569 100644
--- a/docs/internals.md
+++ b/docs/internals.md
@@ -70,13 +70,19 @@ The extension also exposes the routine to generate the SQL subquery, which you c
 === "Python"
     ``` python3
     query = (
-      'SELECT * FROM tableName WHERE tableName._rowid_ IN ' +
-      genomicsqlite.genomic_range_rowids_sql(dbconn, 'tableName',
-                                             # defaults:
-                                             qrid='?1', qbeg='?2', qend='?3',
-                                             ceiling=-1, floor=-1)
+        "SELECT * FROM tableName WHERE tableName._rowid_ IN "
+        + genomicsqlite.genomic_range_rowids_sql(
+            dbconn,
+            "tableName",
+            # defaults:
+            qrid="?1",
+            qbeg="?2",
+            qend="?3",
+            ceiling=-1,
+            floor=-1,
+        )
     )
-    cursor = dbconn.execute(query, ('chr12',111803912,111804012))
+    cursor = dbconn.execute(query, ("chr12", 111803912, 111804012))
     ```
 
 === "SQLiteCpp"
diff --git a/ruff.toml b/ruff.toml
new file mode 100644
index 0000000..cf3dd06
--- /dev/null
+++ b/ruff.toml
@@ -0,0 +1,89 @@
+# Ruff configuration -- Python formatting and linting for this repo.
+# Adopted 2026-10, replacing black (formatting) and flake8 + pylint
+# (linting), as a tool swap at equal enforcement: every check the old
+# tools enforced is either carried below or named in the migration
+# record (ops/phase2-deps-audit-2026-10-18.md) as having no ruff
+# counterpart.
+# Line length matches the former `black -l 100` / flake8
+# --max-line-length 100 settings.
+line-length = 100
+
+[lint]
+select = [
+    # The flake8 rule families (E/F/W), as configured for this project,
+    # plus ruff's Pylint family (PL), which carries most of the checks
+    # pylint enforced here.
+    "E", "F", "W", "PL",
+    # Individual rules from other ruff families, each carrying one
+    # specific check pylint enforced here (pylint code in parentheses):
+    "ARG001", "ARG002", "ARG003", "ARG004", "ARG005", # unused-argument (W0613)
+    "A001", "A002", "A003", # redefined-builtin (W0622)
+    "B006", "B008", # dangerous-default-value (W0102)
+    "B018", # pointless-statement (W0104)
+    "B023", # cell-var-from-loop (W0640)
+    "B025", # duplicate-except (W0705)
+    "B904", # raise-missing-from (W0707)
+    "G001", "G002", "G003", "G004", # logging-not-lazy / -format-interpolation / -fstring-interpolation (W1201-W1203)
+    "ISC001", "ISC002", "ISC004", # implicit-str-concat (W1404)
+    "S102", "S307", # exec-used (W0122), eval-used (W0123)
+    "T100", # forgotten-debug-statement (W1515)
+    "SIM115", # consider-using-with (R1732), the open() case
+]
+ignore = [
+    # E501 (line too long): line length is policed by `ruff format`,
+    # not the linter; long strings/comments may legitimately exceed
+    # it. Carried over from the flake8 --ignore list; also ports the
+    # pylint line-too-long (C0301) disable.
+    "E501",
+    # E722 (bare except): tolerated in this codebase. Carried over
+    # from the flake8 --ignore list; also ports the pylint
+    # bare-except (W0702) disable.
+    "E722",
+    # The flake8 --ignore list also named W503 (line break before
+    # binary operator). Ruff removed W503/W504 entirely (they
+    # conflict with the formatter); it was a relaxation, not an
+    # enforced check, so nothing is lost.
+    #
+    # Ports of this repo's pylint disable list (formerly the -d list
+    # in .pre-commit-config.yaml), one per entry:
+    "PLW0603", # global-statement
+    "PLR0913", # too-many-arguments
+    "PLR0917", # too-many-positional-arguments (round-4 ruling: the
+               # positional split-out of the too-many-arguments
+               # family; the flagged functions are public API)
+    "PLR0914", # too-many-locals
+    "PLR0912", # too-many-branches
+    "PLR0915", # too-many-statements
+    "PLC0415", # import-outside-toplevel
+    "PLW1514", # unspecified-encoding
+    # The remaining pylint disables have no selector to port:
+    # missing-docstring / missing-module-docstring are not selected
+    # (ruff's pydocstyle D rules stay off, as under pylint);
+    # duplicate-code (R0801), redefined-outer-name (W0621) and
+    # protected-access (W0212) have no ruff counterpart at all;
+    # broad-except's counterpart (BLE001) is not selected.
+    #
+    # Ruff PL rules whose pylint counterparts were NOT part of this
+    # repo's enforced pylint gate (not enabled under the repo's
+    # pylint configuration) -- ignored to hold the swap at equal
+    # enforcement:
+    "PLC1901", # compare-to-empty-string
+    "PLC2701", # import-private-name
+    "PLR2004", # magic-value-comparison
+    "PLR2044", # empty-comment
+    "PLR5501", # collapsible-else-if
+    "PLR6104", # non-augmented-assignment
+    "PLR6201", # literal-membership
+    "PLR6301", # no-self-use
+    "PLW0717", # too-many-statements-in-try-clause
+    "PLW1641", # eq-without-hash
+    "PLW2901", # redefined-loop-name
+    "PLW3201", # bad-dunder-method-name
+]
+
+[lint.per-file-ignores]
+# The pylint hook excluded version.py (generated version-stamping
+# helper); black and flake8 still applied to it. Port that split:
+# version.py is exempt from the pylint-derived rule families below,
+# and still checked by E/F/W and formatted like everything else.
+"**/version.py" = ["PL", "ARG", "A", "B", "G", "ISC", "S", "T100", "SIM"]
diff --git a/test/genomicsqlite_smoke_test.py b/test/genomicsqlite_smoke_test.py
index 9baf123..ba4e7f7 100644
--- a/test/genomicsqlite_smoke_test.py
+++ b/test/genomicsqlite_smoke_test.py
@@ -126,9 +126,9 @@ def main():
         control = "SELECT exons1.id, exons2.id FROM exons1 LEFT JOIN exons2 NOT INDEXED ON NOT (exons2.end < exons1.pos OR exons2.pos > exons1.end) ORDER BY exons1.id, exons2.id"
         control_results = list(dbconn.execute(control))
         assert len(control_results) == 1139, "unexpected control query results"
-        assert (
-            results == control_results
-        ), "discrepancy between genomic_range_rowids_sql() and control results"
+        assert results == control_results, (
+            "discrepancy between genomic_range_rowids_sql() and control results"
+        )
 
         if gri_constraints != 3:
             print("GRI query opcodes:")
@@ -154,9 +154,9 @@ def main():
                 genomic_range_rowids('exons2', exons1.chrom, exons1.pos, exons1.end, _gri_ceiling, _gri_floor)
             ORDER BY exons1.id, exons2.id
             """
-        assert (
-            list(dbconn.execute(query2)) == control_results
-        ), "discrepancy between genomic_range_rowids() and control results"
+        assert list(dbconn.execute(query2)) == control_results, (
+            "discrepancy between genomic_range_rowids() and control results"
+        )
 
         dbconn.close()
         print("\nGenomicSQLite smoke test OK =)\n")
diff --git a/test/test_bam.py b/test/test_bam.py
index 0748485..56e67c9 100644
--- a/test/test_bam.py
+++ b/test/test_bam.py
@@ -55,10 +55,12 @@ def test_bam(tmp_path):
     count = next(con.execute("SELECT COUNT(DISTINCT qname) FROM NA12878_reads_seqs"))[0]
     assert count == 299205
 
-    mq_hist = dict(con.execute("""
+    mq_hist = dict(
+        con.execute("""
             SELECT mq, COUNT(*) as count FROM
                 (SELECT ifnull(json_extract(tags_json, '$.MQ'),0) AS mq
                 FROM NA12878_reads NATURAL JOIN NA12878_reads_tags WHERE (flag & 3840) = 0)
             GROUP BY mq ORDER BY mq DESC
-            """))
+            """)
+    )
     assert (mq_hist[0], mq_hist[60]) == (2734, 520522)

From 4e16a719c694a2bb41ee4aa672d4b2076223ae10 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 20:31:13 -1000
Subject: [PATCH 38/42] CI: remove .github/workflows/build.yml ahead of staged
 replacement

---
 .github/workflows/build.yml | 234 ------------------------------------
 1 file changed, 234 deletions(-)
 delete mode 100644 .github/workflows/build.yml

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
deleted file mode 100644
index b1e7ee9..0000000
--- a/.github/workflows/build.yml
+++ /dev/null
@@ -1,234 +0,0 @@
-name: build
-on: [push, pull_request]
-
-env:
-  APT_DEPS: libzstd-dev samtools tabix libhts-dev pigz python3-pip
-  BREW_DEPS: zstd samtools pigz coreutils sqlite python@3.12
-  PIP_DEPS: pytest pytest-xdist
-
-jobs:
-
-  lint:
-    runs-on: ubuntu-24.04
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: deps
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y clang-format cppcheck python3-pip python3-venv
-        python3 -m venv "$HOME/.lint-venv"
-        "$HOME/.lint-venv/bin/pip" install pre-commit $PIP_DEPS black flake8 pylint
-        echo "$HOME/.lint-venv/bin" >> "$GITHUB_PATH"
-    - name: pre-commit
-      run: pre-commit run --all-files
-    - name: mvn spotless:check
-      run: mvn spotless:check -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-      with:
-        components: rustfmt, clippy
-    - name: rust lint
-      run: |
-        cd bindings/rust
-        bash ./cargo check --no-default-features
-        bash ./cargo fmt -- --check
-
-  test:
-    runs-on: ubuntu-24.04
-    strategy:
-      matrix:
-        BUILD_TYPE: [Debug, Release]
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: deps
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y $APT_DEPS
-        sudo pip3 install --break-system-packages $PIP_DEPS
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: build
-      run: cmake -DCMAKE_BUILD_TYPE=${{ matrix.BUILD_TYPE }} -B build . && cmake --build build -j $(nproc)
-    - name: test
-      run: env -C build SQLITE_WEB_LOG=99 ctest -V
-
-  linux-x86-64-so:
-    runs-on: ubuntu-24.04
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: build loaders
-      run: |
-        sudo apt-get -qq update
-        sudo apt-get install -y $APT_DEPS
-        sudo pip3 install --break-system-packages $PIP_DEPS
-        cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS='-D_GLIBCXX_USE_CXX11_ABI=0' -B build . && cmake --build build -j $(nproc)
-        rm build/libgenomicsqlite.so
-        sudo apt-get remove -y libzstd-dev  # should be linked into libgenomicsqlite.so
-    - name: build portable .so in docker
-      run: docker build -t genomicsqlite . && docker run -v $(pwd):/mnt --rm genomicsqlite cp /usr/local/lib/{libgenomicsqlite.so,libsqlite3.so.0} /usr/local/bin/sqlite3 /mnt/build/
-    - name: symbols & digests
-      run: |
-        readelf -d build/libgenomicsqlite.so
-        ldd -r build/libgenomicsqlite.so
-        echo "----"
-        echo "libgenomicsqlite.so GLIBC version requirements:"
-        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBC_.*' | sort -Vr | head -n1
-        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBCXX_.*' | sort -Vr | head -n1
-        echo "libsqlite3.so.0 GLIBC version requirements:"
-        objdump -t build/libsqlite3.so.0 | grep -o 'GLIBC_.*' | sort -Vr | head -n1
-        echo "----"
-        sha256sum build/libgenomicsqlite.so build/libsqlite3.so.0
-        echo "asserting manylinux_2_28 floor (GLIBC <= 2.28, GLIBCXX <= 3.4.25):"
-        for f in build/libgenomicsqlite.so build/libsqlite3.so.0; do
-          max_glibc=$(objdump -t $f | grep -oE 'GLIBC_[0-9.]+' | sort -Vu | tail -n1)
-          echo "$f max GLIBC need: $max_glibc"
-          if [ "$(printf 'GLIBC_2.28\n%s\n' "$max_glibc" | sort -V | tail -n1)" != "GLIBC_2.28" ]; then
-            echo "$f requires $max_glibc, above the glibc 2.28 floor" >&2
-            exit 1
-          fi
-        done
-        max_glibcxx=$(objdump -t build/libgenomicsqlite.so | grep -oE 'GLIBCXX_[0-9.]+' | sort -Vu | tail -n1)
-        echo "build/libgenomicsqlite.so max GLIBCXX need: $max_glibcxx"
-        if [ "$(printf 'GLIBCXX_3.4.25\n%s\n' "$max_glibcxx" | sort -V | tail -n1)" != "GLIBCXX_3.4.25" ]; then
-          echo "build/libgenomicsqlite.so requires $max_glibcxx, above the GLIBCXX 3.4.25 ceiling" >&2
-          exit 1
-        fi
-        sudo cp build/libsqlite3.so.0 /usr/local/lib
-        sudo ldconfig
-        # Pair like with like: the ldconfig plant above makes the portable
-        # libsqlite3.so.0 (3.41.2) shadow the system one, so the runner's own
-        # sqlite3 shell (built against >= 3.42) dies at startup with
-        # "undefined symbol: sqlite3_stmt_explain". Put the portable build's
-        # own shell -- copied out of the docker image into build/ in the
-        # previous step -- first on PATH for the remaining steps, so the
-        # portable test exercises the CLI against the exact SQLite vintage
-        # the portable library ships with. (Later steps do not look up a
-        # sqlite3 shell by name, so the prepend is harmless to them.)
-        echo "$(pwd)/build" >> "$GITHUB_PATH"
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: test portable .so
-      run: env -C build SQLITE_WEB_LOG=99 ctest -V
-    - name: test rust crate
-      run: |
-        set -e
-        cp build/libgenomicsqlite.so bindings/rust/libgenomicsqlite-linux-x86_64.so
-        SQLITE_WEB_LOG=99 bash bindings/rust/cargo test --release
-        bash bindings/rust/cargo package --list | grep libgenomicsqlite-linux-x86_64.so
-    - name: prepare artifacts
-      run: cp build/{libgenomicsqlite.so,libsqlite3.so.0} .
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libgenomicsqlite.so
-        path: libgenomicsqlite.so
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libsqlite3.so.0
-        path: libsqlite3.so.0
-
-  macOS-arm64-dylib:
-    runs-on: macos-15
-    steps:
-    - uses: actions/checkout@v7
-      with:
-        fetch-depth: 0
-    - name: dependencies
-      run: |
-        rm -f $(brew --prefix)/bin/2to3  # https://github.com/pypa/pipenv/issues/3831
-        brew update || (sleep 2; brew update)
-        for dep in $BREW_DEPS ; do
-          brew install $dep || brew upgrade $dep
-        done
-
-        # The tests must run under Homebrew's Python: it is configured with
-        # --enable-loadable-sqlite-extensions (the binding cannot be imported
-        # without sqlite3.Connection.enable_load_extension), while the
-        # image's python.org framework Python is built without it.
-        echo "$(brew --prefix)/opt/python@3.12/bin" >> "$GITHUB_PATH"
-        export PATH="$(brew --prefix)/opt/python@3.12/bin:$PATH"
-        python3 -m pip install --break-system-packages $PIP_DEPS
-        python3 -c "import sqlite3; assert hasattr(sqlite3.Connection, 'enable_load_extension')"
-    - name: rust toolchain
-      uses: dtolnay/rust-toolchain@stable
-    - name: build environment
-      run: |
-        echo "PATH=$(brew --prefix)/opt/python@3.12/bin:$(brew --prefix)/bin:$(brew --prefix)/opt/sqlite/bin:${PATH}" >> $GITHUB_ENV
-        echo "CFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "CXXFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "LDFLAGS=-L$(brew --prefix)/lib -L$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
-        # used by rusqlite:
-        echo "SQLITE3_INCLUDE_DIR=$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
-        echo "SQLITE3_LIB_DIR=$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
-    - name: build
-      run: |
-        cmake -DCMAKE_BUILD_TYPE=Release \
-              -DCMAKE_PREFIX_PATH=$(brew --prefix)/opt/sqlite \
-              -B build .
-        cmake --build build -j 4
-    - name: symbols & digests
-      run: |
-        otool -L build/libgenomicsqlite.dylib
-        sha256sum build/libgenomicsqlite.dylib
-    - name: ctest
-      run: |
-        cd build
-        otool -L test/capi_smoke_test
-        SQLITE_WEB_LOG=99 ctest -V
-    - name: test rust crate
-      run: |
-        set -e
-        cp build/libgenomicsqlite.dylib bindings/rust/libgenomicsqlite-macos-aarch64.dylib
-        SQLITE_WEB_LOG=99 bash bindings/rust/cargo test --release
-        bash bindings/rust/cargo package --list | grep libgenomicsqlite-macos-aarch64.dylib
-    - name: prepare artifacts
-      run: cp build/libgenomicsqlite.dylib include/genomicsqlite.h .
-    - uses: actions/upload-artifact@v7
-      with:
-        name: libgenomicsqlite.dylib
-        path: libgenomicsqlite.dylib
-
-  artifacts:
-    runs-on: ubuntu-24.04
-    needs: [linux-x86-64-so, macOS-arm64-dylib]
-    steps:
-    - uses: actions/checkout@v7
-    - name: fetch libgenomicsqlite.so
-      uses: actions/download-artifact@v8
-      with:
-        name: libgenomicsqlite.so
-    - name: fetch libsqlite3.so.0
-      uses: actions/download-artifact@v8
-      with:
-        name: libsqlite3.so.0
-    - name: fetch libgenomicsqlite.dylib
-      uses: actions/download-artifact@v8
-      with:
-        name: libgenomicsqlite.dylib
-    - name: detect GIT_REVISION
-      run: |
-        cp include/genomicsqlite.h .
-        echo "GIT_REVISION=$(git describe --tags --always)" >> $GITHUB_ENV
-    - uses: actions/upload-artifact@v7
-      with:
-        name: GenomicSQLite-${{ env.GIT_REVISION }}
-        path: |
-          LICENSE
-          genomicsqlite.h
-          libgenomicsqlite.so
-          libgenomicsqlite.dylib
-    - name: build jar
-      run: |
-        cp libgenomicsqlite.so libgenomicsqlite.dylib bindings/jdbc/genomicsqlite-jdbc/src/main/resources/
-        mvn deploy -Drevision=${{ env.GIT_REVISION }} -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
-    - name: digests
-      run: sha256sum *genomicsqlite* bindings/jdbc/genomicsqlite-jdbc/target/genomicsqlite*.jar libsqlite3.so.0
-    - uses: actions/upload-artifact@v7
-      with:
-        name: genomicsqlite-jdbc-${{ env.GIT_REVISION }}
-        path: bindings/jdbc/genomicsqlite-jdbc/target/mvn-repo

From c6052ccc9d261e94d02e00d307d8c24fc614c3d6 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 20:41:29 -1000
Subject: [PATCH 39/42] CI: staged build.yml (ruff lint deps; 3.54.1 comment)
 for rename into .github/workflows/

---
 build.yml | 235 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 235 insertions(+)
 create mode 100644 build.yml

diff --git a/build.yml b/build.yml
new file mode 100644
index 0000000..7d6af84
--- /dev/null
+++ b/build.yml
@@ -0,0 +1,235 @@
+name: build
+on: [push, pull_request]
+
+env:
+  APT_DEPS: libzstd-dev samtools tabix libhts-dev pigz python3-pip
+  BREW_DEPS: zstd samtools pigz coreutils sqlite python@3.12
+  PIP_DEPS: pytest pytest-xdist
+
+jobs:
+
+  lint:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: deps
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y clang-format cppcheck python3-pip python3-venv
+        python3 -m venv "$HOME/.lint-venv"
+        "$HOME/.lint-venv/bin/pip" install pre-commit $PIP_DEPS ruff
+        echo "$HOME/.lint-venv/bin" >> "$GITHUB_PATH"
+    - name: pre-commit
+      run: pre-commit run --all-files
+    - name: mvn spotless:check
+      run: mvn spotless:check -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+      with:
+        components: rustfmt, clippy
+    - name: rust lint
+      run: |
+        cd bindings/rust
+        bash ./cargo check --no-default-features
+        bash ./cargo fmt -- --check
+
+  test:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        BUILD_TYPE: [Debug, Release]
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: deps
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y $APT_DEPS
+        sudo pip3 install --break-system-packages $PIP_DEPS
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: build
+      run: cmake -DCMAKE_BUILD_TYPE=${{ matrix.BUILD_TYPE }} -B build . && cmake --build build -j $(nproc)
+    - name: test
+      run: env -C build SQLITE_WEB_LOG=99 ctest -V
+
+  linux-x86-64-so:
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: build loaders
+      run: |
+        sudo apt-get -qq update
+        sudo apt-get install -y $APT_DEPS
+        sudo pip3 install --break-system-packages $PIP_DEPS
+        cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS='-D_GLIBCXX_USE_CXX11_ABI=0' -B build . && cmake --build build -j $(nproc)
+        rm build/libgenomicsqlite.so
+        sudo apt-get remove -y libzstd-dev  # should be linked into libgenomicsqlite.so
+    - name: build portable .so in docker
+      run: docker build -t genomicsqlite . && docker run -v $(pwd):/mnt --rm genomicsqlite cp /usr/local/lib/{libgenomicsqlite.so,libsqlite3.so.0} /usr/local/bin/sqlite3 /mnt/build/
+    - name: symbols & digests
+      run: |
+        readelf -d build/libgenomicsqlite.so
+        ldd -r build/libgenomicsqlite.so
+        echo "----"
+        echo "libgenomicsqlite.so GLIBC version requirements:"
+        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBC_.*' | sort -Vr | head -n1
+        objdump -t build/libgenomicsqlite.so | grep -o 'GLIBCXX_.*' | sort -Vr | head -n1
+        echo "libsqlite3.so.0 GLIBC version requirements:"
+        objdump -t build/libsqlite3.so.0 | grep -o 'GLIBC_.*' | sort -Vr | head -n1
+        echo "----"
+        sha256sum build/libgenomicsqlite.so build/libsqlite3.so.0
+        echo "asserting manylinux_2_28 floor (GLIBC <= 2.28, GLIBCXX <= 3.4.25):"
+        for f in build/libgenomicsqlite.so build/libsqlite3.so.0; do
+          max_glibc=$(objdump -t $f | grep -oE 'GLIBC_[0-9.]+' | sort -Vu | tail -n1)
+          echo "$f max GLIBC need: $max_glibc"
+          if [ "$(printf 'GLIBC_2.28\n%s\n' "$max_glibc" | sort -V | tail -n1)" != "GLIBC_2.28" ]; then
+            echo "$f requires $max_glibc, above the glibc 2.28 floor" >&2
+            exit 1
+          fi
+        done
+        max_glibcxx=$(objdump -t build/libgenomicsqlite.so | grep -oE 'GLIBCXX_[0-9.]+' | sort -Vu | tail -n1)
+        echo "build/libgenomicsqlite.so max GLIBCXX need: $max_glibcxx"
+        if [ "$(printf 'GLIBCXX_3.4.25\n%s\n' "$max_glibcxx" | sort -V | tail -n1)" != "GLIBCXX_3.4.25" ]; then
+          echo "build/libgenomicsqlite.so requires $max_glibcxx, above the GLIBCXX 3.4.25 ceiling" >&2
+          exit 1
+        fi
+        sudo cp build/libsqlite3.so.0 /usr/local/lib
+        sudo ldconfig
+        # Pair like with like: the ldconfig plant above makes the portable
+        # libsqlite3.so.0 (3.54.1) shadow the system one, and the runner's own
+        # sqlite3 shell (built against the system's older SQLite) refuses to
+        # run against the planted library -- it aborts at startup with
+        # "SQLite header and source version mismatch". Put the portable
+        # build's own shell -- copied out of the docker image into build/ in
+        # the previous step -- first on PATH for the remaining steps, so the
+        # portable test exercises the CLI against the exact SQLite vintage
+        # the portable library ships with. (Later steps do not look up a
+        # sqlite3 shell by name, so the prepend is harmless to them.)
+        echo "$(pwd)/build" >> "$GITHUB_PATH"
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: test portable .so
+      run: env -C build SQLITE_WEB_LOG=99 ctest -V
+    - name: test rust crate
+      run: |
+        set -e
+        cp build/libgenomicsqlite.so bindings/rust/libgenomicsqlite-linux-x86_64.so
+        SQLITE_WEB_LOG=99 bash bindings/rust/cargo test --release
+        bash bindings/rust/cargo package --list | grep libgenomicsqlite-linux-x86_64.so
+    - name: prepare artifacts
+      run: cp build/{libgenomicsqlite.so,libsqlite3.so.0} .
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libgenomicsqlite.so
+        path: libgenomicsqlite.so
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libsqlite3.so.0
+        path: libsqlite3.so.0
+
+  macOS-arm64-dylib:
+    runs-on: macos-15
+    steps:
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: dependencies
+      run: |
+        rm -f $(brew --prefix)/bin/2to3  # https://github.com/pypa/pipenv/issues/3831
+        brew update || (sleep 2; brew update)
+        for dep in $BREW_DEPS ; do
+          brew install $dep || brew upgrade $dep
+        done
+
+        # The tests must run under Homebrew's Python: it is configured with
+        # --enable-loadable-sqlite-extensions (the binding cannot be imported
+        # without sqlite3.Connection.enable_load_extension), while the
+        # image's python.org framework Python is built without it.
+        echo "$(brew --prefix)/opt/python@3.12/bin" >> "$GITHUB_PATH"
+        export PATH="$(brew --prefix)/opt/python@3.12/bin:$PATH"
+        python3 -m pip install --break-system-packages $PIP_DEPS
+        python3 -c "import sqlite3; assert hasattr(sqlite3.Connection, 'enable_load_extension')"
+    - name: rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+    - name: build environment
+      run: |
+        echo "PATH=$(brew --prefix)/opt/python@3.12/bin:$(brew --prefix)/bin:$(brew --prefix)/opt/sqlite/bin:${PATH}" >> $GITHUB_ENV
+        echo "CFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "CXXFLAGS=-I$(brew --prefix)/include -I$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "LDFLAGS=-L$(brew --prefix)/lib -L$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
+        # used by rusqlite:
+        echo "SQLITE3_INCLUDE_DIR=$(brew --prefix)/opt/sqlite/include" >> $GITHUB_ENV
+        echo "SQLITE3_LIB_DIR=$(brew --prefix)/opt/sqlite/lib" >> $GITHUB_ENV
+    - name: build
+      run: |
+        cmake -DCMAKE_BUILD_TYPE=Release \
+              -DCMAKE_PREFIX_PATH=$(brew --prefix)/opt/sqlite \
+              -B build .
+        cmake --build build -j 4
+    - name: symbols & digests
+      run: |
+        otool -L build/libgenomicsqlite.dylib
+        sha256sum build/libgenomicsqlite.dylib
+    - name: ctest
+      run: |
+        cd build
+        otool -L test/capi_smoke_test
+        SQLITE_WEB_LOG=99 ctest -V
+    - name: test rust crate
+      run: |
+        set -e
+        cp build/libgenomicsqlite.dylib bindings/rust/libgenomicsqlite-macos-aarch64.dylib
+        SQLITE_WEB_LOG=99 bash bindings/rust/cargo test --release
+        bash bindings/rust/cargo package --list | grep libgenomicsqlite-macos-aarch64.dylib
+    - name: prepare artifacts
+      run: cp build/libgenomicsqlite.dylib include/genomicsqlite.h .
+    - uses: actions/upload-artifact@v7
+      with:
+        name: libgenomicsqlite.dylib
+        path: libgenomicsqlite.dylib
+
+  artifacts:
+    runs-on: ubuntu-24.04
+    needs: [linux-x86-64-so, macOS-arm64-dylib]
+    steps:
+    - uses: actions/checkout@v7
+    - name: fetch libgenomicsqlite.so
+      uses: actions/download-artifact@v8
+      with:
+        name: libgenomicsqlite.so
+    - name: fetch libsqlite3.so.0
+      uses: actions/download-artifact@v8
+      with:
+        name: libsqlite3.so.0
+    - name: fetch libgenomicsqlite.dylib
+      uses: actions/download-artifact@v8
+      with:
+        name: libgenomicsqlite.dylib
+    - name: detect GIT_REVISION
+      run: |
+        cp include/genomicsqlite.h .
+        echo "GIT_REVISION=$(git describe --tags --always)" >> $GITHUB_ENV
+    - uses: actions/upload-artifact@v7
+      with:
+        name: GenomicSQLite-${{ env.GIT_REVISION }}
+        path: |
+          LICENSE
+          genomicsqlite.h
+          libgenomicsqlite.so
+          libgenomicsqlite.dylib
+    - name: build jar
+      run: |
+        cp libgenomicsqlite.so libgenomicsqlite.dylib bindings/jdbc/genomicsqlite-jdbc/src/main/resources/
+        mvn deploy -Drevision=${{ env.GIT_REVISION }} -B -f bindings/jdbc/genomicsqlite-jdbc/pom.xml
+    - name: digests
+      run: sha256sum *genomicsqlite* bindings/jdbc/genomicsqlite-jdbc/target/genomicsqlite*.jar libsqlite3.so.0
+    - uses: actions/upload-artifact@v7
+      with:
+        name: genomicsqlite-jdbc-${{ env.GIT_REVISION }}
+        path: bindings/jdbc/genomicsqlite-jdbc/target/mvn-repo

From 12b8864530db7986494a9469d93121969ebbfab2 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 21:07:12 -1000
Subject: [PATCH 40/42] Rename build.yml to .github/workflows/build.yml

---
 build.yml => .github/workflows/build.yml | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename build.yml => .github/workflows/build.yml (100%)

diff --git a/build.yml b/.github/workflows/build.yml
similarity index 100%
rename from build.yml
rename to .github/workflows/build.yml

From ba2a910b569d9fe76254e721a79455b5544e45f2 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 21:33:22 -1000
Subject: [PATCH 41/42] Adopt ruff I001 import sorting (pylint C0411/C0412
 counterpart)

Mike approved adopting ruff's stricter isort grouping on 2026-10-18
as a low-risk cleanup, superseding the tool swap's initial
deliberate non-adoption. ruff.toml now selects I001, and the tree
is import-sorted with ruff 0.17.1 --fix: pure import
regrouping/sorting in 11 Python files, no semantic changes.
---
 bindings/python/genomicsqlite/__init__.py | 6 +++---
 bindings/python/genomicsqlite/__main__.py | 1 +
 bindings/python/setup.py                  | 3 ++-
 ruff.toml                                 | 5 +++++
 test/genomicsqlite_smoke_test.py          | 8 ++++----
 test/test_bam.py                          | 3 ++-
 test/test_gri.py                          | 5 +++--
 test/test_parse_genomic_range.py          | 3 ++-
 test/test_twobit.py                       | 5 +++--
 test/test_txdb.py                         | 7 ++++---
 test/test_vcf.py                          | 3 ++-
 test/test_vcf_lines.py                    | 1 +
 12 files changed, 32 insertions(+), 18 deletions(-)

diff --git a/bindings/python/genomicsqlite/__init__.py b/bindings/python/genomicsqlite/__init__.py
index 8325660..266df4e 100644
--- a/bindings/python/genomicsqlite/__init__.py
+++ b/bindings/python/genomicsqlite/__init__.py
@@ -3,12 +3,12 @@
 GenomicSQLite Python binding
 """
 
+import json
 import os
-import sys
 import platform
-import json
 import sqlite3
-from typing import Optional, NamedTuple, Dict, Any
+import sys
+from typing import Any, Dict, NamedTuple, Optional
 
 _HERE = os.path.dirname(__file__)
 _YES = ("1", "true", "t", "yes", "y")
diff --git a/bindings/python/genomicsqlite/__main__.py b/bindings/python/genomicsqlite/__main__.py
index ba91ed0..bd19d9c 100644
--- a/bindings/python/genomicsqlite/__main__.py
+++ b/bindings/python/genomicsqlite/__main__.py
@@ -1,4 +1,5 @@
 import sys
+
 from . import _cli
 
 if __name__ == "__main__":
diff --git a/bindings/python/setup.py b/bindings/python/setup.py
index 82dfa62..141a0aa 100644
--- a/bindings/python/setup.py
+++ b/bindings/python/setup.py
@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 from os import path
-from setuptools import setup, find_packages  # pylint: disable=import-error
+
+from setuptools import find_packages, setup  # pylint: disable=import-error
 from version import get_version
 
 HERE = path.abspath(path.dirname(__file__))
diff --git a/ruff.toml b/ruff.toml
index cf3dd06..413ea41 100644
--- a/ruff.toml
+++ b/ruff.toml
@@ -25,6 +25,11 @@ select = [
     "B904", # raise-missing-from (W0707)
     "G001", "G002", "G003", "G004", # logging-not-lazy / -format-interpolation / -fstring-interpolation (W1201-W1203)
     "ISC001", "ISC002", "ISC004", # implicit-str-concat (W1404)
+    "I001", # unsorted-imports (isort): the counterpart of pylint's
+            # wrong-import-order (C0411) and ungrouped-imports (C0412).
+            # Deliberately not adopted in the initial tool swap (ruff's
+            # grouping is stricter than pylint's); adopted on Mike's
+            # ruling, 2026-10-18, as a low-risk cleanup.
     "S102", "S307", # exec-used (W0122), eval-used (W0123)
     "T100", # forgotten-debug-statement (W1515)
     "SIM115", # consider-using-with (R1732), the open() case
diff --git a/test/genomicsqlite_smoke_test.py b/test/genomicsqlite_smoke_test.py
index ba4e7f7..25ad8f8 100644
--- a/test/genomicsqlite_smoke_test.py
+++ b/test/genomicsqlite_smoke_test.py
@@ -4,13 +4,13 @@
 small test database and check GRI query plan on it.
 """
 
-import sys
-import time
 import os
-import subprocess
-import traceback
 import platform
+import subprocess
+import sys
 import textwrap
+import time
+import traceback
 
 
 def main():
diff --git a/test/test_bam.py b/test/test_bam.py
index 56e67c9..6d39c2b 100644
--- a/test/test_bam.py
+++ b/test/test_bam.py
@@ -1,6 +1,7 @@
 import os
-import subprocess
 import sqlite3
+import subprocess
+
 import genomicsqlite
 
 HERE = os.path.dirname(__file__)
diff --git a/test/test_gri.py b/test/test_gri.py
index 3ab2cda..ef1d6a1 100644
--- a/test/test_gri.py
+++ b/test/test_gri.py
@@ -1,8 +1,9 @@
 import os
-import sqlite3
 import random
-import pytest
+import sqlite3
+
 import genomicsqlite
+import pytest
 
 HERE = os.path.dirname(__file__)
 BUILD = os.path.abspath(os.path.join(HERE, "..", "build"))
diff --git a/test/test_parse_genomic_range.py b/test/test_parse_genomic_range.py
index 8b5e508..e561f13 100644
--- a/test/test_parse_genomic_range.py
+++ b/test/test_parse_genomic_range.py
@@ -1,6 +1,7 @@
 import sqlite3
-import pytest
+
 import genomicsqlite
+import pytest
 
 
 def test_parse_genomic_range():
diff --git a/test/test_twobit.py b/test/test_twobit.py
index f574d98..2c22afc 100644
--- a/test/test_twobit.py
+++ b/test/test_twobit.py
@@ -1,8 +1,9 @@
-import random
 import math
+import random
 import sqlite3
-import pytest
+
 import genomicsqlite
+import pytest
 
 
 def test_twobit_random():
diff --git a/test/test_txdb.py b/test/test_txdb.py
index b96bb52..87a20fc 100644
--- a/test/test_txdb.py
+++ b/test/test_txdb.py
@@ -1,9 +1,10 @@
 import os
-import sys
-import subprocess
 import random
-import pytest
+import subprocess
+import sys
+
 import genomicsqlite
+import pytest
 
 HERE = os.path.dirname(__file__)
 
diff --git a/test/test_vcf.py b/test/test_vcf.py
index bed3151..f6c6d90 100644
--- a/test/test_vcf.py
+++ b/test/test_vcf.py
@@ -1,8 +1,9 @@
 import os
 import sqlite3
 import subprocess
-import pytest
+
 import genomicsqlite
+import pytest
 
 HERE = os.path.dirname(__file__)
 BUILD = os.path.abspath(os.path.join(HERE, "..", "build"))
diff --git a/test/test_vcf_lines.py b/test/test_vcf_lines.py
index 7ebdb91..d23c90c 100644
--- a/test/test_vcf_lines.py
+++ b/test/test_vcf_lines.py
@@ -1,6 +1,7 @@
 import os
 import sqlite3
 import subprocess
+
 import genomicsqlite
 import pytest
 

From ca7d84bcc41ca4bea5e1fd000a4a333c571b7b12 Mon Sep 17 00:00:00 2001
From: "Wid L. Hacker" <nilekim@gmail.com>
Date: Sun, 18 Oct 2026 21:48:51 -1000
Subject: [PATCH 42/42] JDBC hygiene: junit 4.13.2, Maven plugins to current
 3.x, MavenSmokeTest Java floor 1.8

---
 bindings/jdbc/genomicsqlite-jdbc/pom.xml | 20 ++++++++++----------
 test/MavenSmokeTest/pom.xml              | 22 +++++++++++-----------
 2 files changed, 21 insertions(+), 21 deletions(-)

diff --git a/bindings/jdbc/genomicsqlite-jdbc/pom.xml b/bindings/jdbc/genomicsqlite-jdbc/pom.xml
index 63b4894..b7b3646 100644
--- a/bindings/jdbc/genomicsqlite-jdbc/pom.xml
+++ b/bindings/jdbc/genomicsqlite-jdbc/pom.xml
@@ -61,7 +61,7 @@
     <dependency>
       <groupId>junit</groupId>
       <artifactId>junit</artifactId>
-      <version>4.13.1</version>
+      <version>4.13.2</version>
       <scope>test</scope>
     </dependency>
   </dependencies>
@@ -72,44 +72,44 @@
         <!-- clean lifecycle, see https://maven.apache.org/ref/current/maven-core/lifecycles.html#clean_Lifecycle -->
         <plugin>
           <artifactId>maven-clean-plugin</artifactId>
-          <version>3.1.0</version>
+          <version>3.5.0</version>
         </plugin>
         <!-- default lifecycle, jar packaging: see https://maven.apache.org/ref/current/maven-core/default-bindings.html#Plugin_bindings_for_jar_packaging -->
         <plugin>
           <artifactId>maven-resources-plugin</artifactId>
-          <version>3.0.2</version>
+          <version>3.5.0</version>
         </plugin>
         <plugin>
           <artifactId>maven-compiler-plugin</artifactId>
-          <version>3.8.0</version>
+          <version>3.16.0</version>
         </plugin>
         <plugin>
           <artifactId>maven-surefire-plugin</artifactId>
-          <version>2.22.2</version>
+          <version>3.6.0</version>
           <configuration>
             <trimStackTrace>false</trimStackTrace>
           </configuration>
         </plugin>
         <plugin>
           <artifactId>maven-jar-plugin</artifactId>
-          <version>3.0.2</version>
+          <version>3.5.1</version>
         </plugin>
         <plugin>
           <artifactId>maven-install-plugin</artifactId>
-          <version>2.5.2</version>
+          <version>3.2.0</version>
         </plugin>
         <plugin>
           <artifactId>maven-deploy-plugin</artifactId>
-          <version>2.8.2</version>
+          <version>3.2.0</version>
         </plugin>
         <!-- site lifecycle, see https://maven.apache.org/ref/current/maven-core/lifecycles.html#site_Lifecycle -->
         <plugin>
           <artifactId>maven-site-plugin</artifactId>
-          <version>3.7.1</version>
+          <version>3.22.0</version>
         </plugin>
         <plugin>
           <artifactId>maven-project-info-reports-plugin</artifactId>
-          <version>3.0.0</version>
+          <version>3.9.0</version>
         </plugin>
         <plugin>
           <groupId>com.diffplug.spotless</groupId>
diff --git a/test/MavenSmokeTest/pom.xml b/test/MavenSmokeTest/pom.xml
index 6b93186..bd6c08e 100644
--- a/test/MavenSmokeTest/pom.xml
+++ b/test/MavenSmokeTest/pom.xml
@@ -14,8 +14,8 @@
 
   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <maven.compiler.source>1.7</maven.compiler.source>
-    <maven.compiler.target>1.7</maven.compiler.target>
+    <maven.compiler.source>1.8</maven.compiler.source>
+    <maven.compiler.target>1.8</maven.compiler.target>
   </properties>
 
   <repositories>
@@ -39,41 +39,41 @@
         <!-- clean lifecycle, see https://maven.apache.org/ref/current/maven-core/lifecycles.html#clean_Lifecycle -->
         <plugin>
           <artifactId>maven-clean-plugin</artifactId>
-          <version>3.1.0</version>
+          <version>3.5.0</version>
         </plugin>
         <!-- default lifecycle, jar packaging: see https://maven.apache.org/ref/current/maven-core/default-bindings.html#Plugin_bindings_for_jar_packaging -->
         <plugin>
           <artifactId>maven-resources-plugin</artifactId>
-          <version>3.0.2</version>
+          <version>3.5.0</version>
         </plugin>
         <plugin>
           <artifactId>maven-compiler-plugin</artifactId>
-          <version>3.8.0</version>
+          <version>3.16.0</version>
         </plugin>
         <plugin>
           <artifactId>maven-surefire-plugin</artifactId>
-          <version>2.22.1</version>
+          <version>3.6.0</version>
         </plugin>
         <plugin>
           <artifactId>maven-jar-plugin</artifactId>
-          <version>3.0.2</version>
+          <version>3.5.1</version>
         </plugin>
         <plugin>
           <artifactId>maven-install-plugin</artifactId>
-          <version>2.5.2</version>
+          <version>3.2.0</version>
         </plugin>
         <plugin>
           <artifactId>maven-deploy-plugin</artifactId>
-          <version>2.8.2</version>
+          <version>3.2.0</version>
         </plugin>
         <!-- site lifecycle, see https://maven.apache.org/ref/current/maven-core/lifecycles.html#site_Lifecycle -->
         <plugin>
           <artifactId>maven-site-plugin</artifactId>
-          <version>3.7.1</version>
+          <version>3.22.0</version>
         </plugin>
         <plugin>
           <artifactId>maven-project-info-reports-plugin</artifactId>
-          <version>3.0.0</version>
+          <version>3.9.0</version>
         </plugin>
       </plugins>
     </pluginManagement>