Merge: Type Hints, Graph Iterators, Builds, & Safety

Author: ashvardanian

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -92,7 +92,8 @@ body:
     id: terms
     attributes:
       label: Code of Conduct
-      description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/unum-cloud/USearch/blob/main/CODE_OF_CONDUCT.md)
+      description: By submitting this issue, you agree to follow our [Code of
+        Conduct](https://github.com/unum-cloud/USearch/blob/main/CODE_OF_CONDUCT.md)
       options:
         - label: I agree to follow this project's Code of Conduct
           required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -58,7 +58,8 @@ body:
     id: terms
     attributes:
       label: Code of Conduct
-      description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/unum-cloud/USearch/blob/main/CODE_OF_CONDUCT.md)
+      description: By submitting this issue, you agree to follow our [Code of
+        Conduct](https://github.com/unum-cloud/USearch/blob/main/CODE_OF_CONDUCT.md)
       options:
         - label: I agree to follow this project's Code of Conduct
           required: true

.github/workflows/prerelease.yml

@@ -68,7 +68,6 @@ jobs:
         uses: actions/checkout@v6
       - name: Pull Git submodules
         run: git submodule update --init --recursive
-
         # C/C++
       - name: Build C/C++
         run: |
@@ -80,7 +79,6 @@ jobs:
         run: build_artifacts/test_cpp
       - name: Test C
         run: build_artifacts/test_c
-
         # Python
       - name: Set up Python ${{ env.PYTHON_VERSION }}
         uses: actions/setup-python@v6
@@ -94,7 +92,6 @@ jobs:
           python -m pip install .
       - name: Test Python
         run: pytest
-
         # JavaScript
       - name: Set up Node.js
         uses: actions/setup-node@v6
@@ -106,7 +103,6 @@ jobs:
         run: npm run build-js
       - name: Test JavaScript
         run: npm test
-
         # Rust
       - name: Set up Rust
         run: |
@@ -120,7 +116,6 @@ jobs:
         run: cargo build
       - name: Test Rust
         run: cargo test
-
         # Java
       - name: Setup Java
         uses: actions/setup-java@v5
@@ -133,7 +128,6 @@ jobs:
         run: gradle spotlessCheck
       - name: Test Java
         run: gradle clean build
-
         # C#
       - name: Setup .NET ${{ env.DOTNET_VERSION }}
         uses: actions/setup-dotnet@v5
@@ -146,7 +140,6 @@ jobs:
           dotnet test -c Debug --logger "console;verbosity=detailed"
         shell: bash
         working-directory: ${{ github.workspace }}/csharp
-
         # GoLang
         # With `LD_DEBUG=all` we detect the addresses of the libraries that are loaded
       - name: Test GoLang
@@ -168,7 +161,6 @@ jobs:
         uses: actions/checkout@v6
       - name: Pull Git submodules
         run: git submodule update --init --recursive
-
         # C/C++
       - name: Build C/C++
         run: |
@@ -180,7 +172,6 @@ jobs:
         run: build_artifacts/test_cpp
       - name: Test C
         run: build_artifacts/test_c
-
         # JavaScript
       - name: Set up Node.js
         uses: actions/setup-node@v6
@@ -192,7 +183,6 @@ jobs:
         run: npm run build-js
       - name: Test JavaScript
         run: npm test
-
         # Python
       - name: Set up Python ${{ env.PYTHON_VERSION }}
         uses: actions/setup-python@v6
@@ -209,7 +199,6 @@ jobs:
           CC: clang++ # Override the default compiler
       - name: Test Python
         run: pytest
-
         # Rust
       - name: Set up Rust
         run: |
@@ -220,7 +209,6 @@ jobs:
         run: cargo build
       - name: Test Rust
         run: cargo test
-
         # C#
       - name: Setup .NET ${{ env.DOTNET_VERSION }}
         uses: actions/setup-dotnet@v5
@@ -243,7 +231,6 @@ jobs:
         uses: actions/checkout@v6
       - name: Pull Git submodules
         run: git submodule update --init --recursive
-
         # C/C++
       - name: Build C/C++
         run: |
@@ -255,7 +242,6 @@ jobs:
         run: build_artifacts/test_cpp
       - name: Test C
         run: build_artifacts/test_c
-
         # JavaScript
       - name: Set up Node.js
         uses: actions/setup-node@v6
@@ -267,7 +253,6 @@ jobs:
         run: npm run build-js
       - name: Test JavaScript
         run: npm test
-
         # Python
       - name: Set up Python ${{ env.PYTHON_VERSION }}
         uses: actions/setup-python@v6
@@ -283,13 +268,11 @@ jobs:
           CC: clang++ # Override the default compiler
       - name: Test Python
         run: pytest
-
         # ObjC/Swift
       - name: Build ObjC/Swift
         run: swift build
       - name: Test ObjC/Swift
         run: swift test
-
         # Rust
       - name: Set up Rust
         run: |
@@ -300,7 +283,6 @@ jobs:
         run: cargo build
       - name: Test Rust
         run: cargo test
-
         # C#
       - name: Setup .NET ${{ env.DOTNET_VERSION }}
         uses: actions/setup-dotnet@v5
@@ -322,7 +304,6 @@ jobs:
         uses: actions/checkout@v6
       - name: Pull Git submodules
         run: git submodule update --init --recursive
-
         # C/C++
       - name: Build C/C++
         run: |
@@ -333,7 +314,6 @@ jobs:
         run: .\build_artifacts\test_cpp.exe
       - name: Test C
         run: .\build_artifacts\test_c.exe
-
         # Python
       - name: Set up Python ${{ env.PYTHON_VERSION }}
         uses: actions/setup-python@v6
@@ -346,7 +326,6 @@ jobs:
           python -m pip install .
       - name: Test Python
         run: pytest
-
         # JavaScript
       - name: Set up Node.js
         uses: actions/setup-node@v6
@@ -358,7 +337,6 @@ jobs:
         run: npm run build-js
       - name: Test JavaScript
         run: npm test
-
         # Rust
       - name: Set up Rust
         run: |
@@ -369,7 +347,6 @@ jobs:
         run: cargo build
       - name: Test Rust
         run: cargo test
-
         # C#
       - name: Setup .NET ${{ env.DOTNET_VERSION }}
         uses: actions/setup-dotnet@v5
@@ -394,7 +371,6 @@ jobs:
 
       - name: Setup MSVC for ARM64
         uses: microsoft/setup-msbuild@v2
-
         # C/C++
       - name: Build C/C++ (ARM64)
         run: |
@@ -547,7 +523,6 @@ jobs:
         uses: actions/checkout@v6
       - name: Pull Git submodules
         run: git submodule update --init --recursive
-
         # C/C++
         # We need to install the cross-compilation toolchain for ARM64 and ARMHF
       - name: Install dependencies
@@ -570,7 +545,6 @@ jobs:
             -D USEARCH_BUILD_BENCH_CPP=0
 
           cmake --build build_artifacts --config RelWithDebInfo
-
         # We can't run the produced builds, but we can make sure they exist
       - name: Test artifacts presence
         run: |
@@ -616,11 +590,9 @@ jobs:
             -D USEARCH_BUILD_BENCH_CPP=0
 
           cmake --build build_artifacts --config RelWithDebInfo
-
         # We can't run the produced builds, but we can make sure they exist
       - name: Test artifacts presence
         run: test -e build_artifacts/libusearch_c.so
-
         # Rust
       - name: Set up Rust
         run: |
@@ -641,14 +613,12 @@ jobs:
 
       - name: Build Rust
         run: cargo build --target ${{ matrix.target }}
-
         # Java
       - name: Set up JDK 21
         uses: actions/setup-java@v5
         with:
           java-version: ${{ env.JAVA_VERSION }}
           distribution: "adopt"
-
         # We skip native compilation with Gradle and focus just on the Java part,
         # assuming the we won't be able to tun the tests without emulation
       - name: Check Java formatting

.github/workflows/release.yml

@@ -213,13 +213,29 @@ jobs:
 
       - name: Build library (MinGW)
         if: matrix.arch != 'arm64'
+        # `-G "MinGW Makefiles"` is required: without it, CMake on the
+        # `windows-2022` runner falls back to the Visual Studio generator
+        # (x64 by default), so the `x86` matrix entry was silently producing
+        # a 64-bit DLL and shipping it under the `windows_x86` archive name.
         run: |
-          cmake -DCMAKE_BUILD_TYPE=Release -DUSEARCH_BUILD_LIB_C=1 -DUSEARCH_BUILD_SQLITE=0 -DUSEARCH_BUILD_TEST_CPP=0 -DUSEARCH_BUILD_BENCH_CPP=0 -B ./build_release
+          cmake -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release -DUSEARCH_BUILD_LIB_C=1 -DUSEARCH_BUILD_SQLITE=0 -DUSEARCH_BUILD_TEST_CPP=0 -DUSEARCH_BUILD_BENCH_CPP=0 -B ./build_release
           cmake --build ./build_release --config Release
           mkdir pkg
           copy .\build_release\libusearch_c.dll pkg\
           copy .\c\usearch.h pkg\
           tar -cvf usearch_windows_${{ matrix.arch }}_${{ steps.set_version.outputs.version }}.tar -C pkg libusearch_c.dll usearch.h
+        # Guard against silent generator fallback — the DLL must match the
+        # advertised matrix arch, otherwise the archive ships a mislabeled binary.
+      - name: Verify Windows DLL architecture
+        if: matrix.arch != 'arm64'
+        shell: bash
+        run: |
+          case "${{ matrix.arch }}" in
+            x64)  expected='x86-64'    ;;
+            x86)  expected='80386\|Intel 80386' ;;
+          esac
+          file ./build_release/libusearch_c.dll
+          file ./build_release/libusearch_c.dll | grep -q "$expected"
 
       - name: Build library (MSVC ARM64)
         if: matrix.arch == 'arm64'
@@ -420,8 +436,11 @@ jobs:
       - name: Install dependencies
         run: |
           sudo apt-get update
-          sudo apt-get install -y clang lld make crossbuild-essential-arm64 crossbuild-essential-armhf
+          sudo apt-get install -y clang mold make crossbuild-essential-arm64 crossbuild-essential-armhf
 
+      # `-fuse-ld=mold` keeps clang LTO on while sidestepping the
+      # experimental `lld 1:18.0-59~exp2` from Noble universe that
+      # segfaults on the widened `nk_shared` LTO unit.
       - name: Build JNI library
         run: |
           cmake -B build_artifacts \
@@ -430,6 +449,9 @@ jobs:
             -DCMAKE_CXX_COMPILER_TARGET=${{ matrix.target }} \
             -DCMAKE_SYSTEM_NAME=Linux \
             -DCMAKE_SYSTEM_PROCESSOR=${{ matrix.cmake_processor }} \
+            -DCMAKE_SHARED_LINKER_FLAGS=-fuse-ld=mold \
+            -DCMAKE_MODULE_LINKER_FLAGS=-fuse-ld=mold \
+            -DCMAKE_EXE_LINKER_FLAGS=-fuse-ld=mold \
             -DUSEARCH_BUILD_JNI=1 \
             -DUSEARCH_BUILD_TEST_CPP=0 \
             -DUSEARCH_BUILD_BENCH_CPP=0 \
@@ -728,8 +750,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-24.04, macos-14, windows-2022]
-        python-version:
-          ["310", "311", "312", "313", "313t", "314", "314t"]
+        python-version: ["310", "311", "312", "313", "313t", "314", "314t"]
     steps:
       - name: Check out refreshed version
         uses: actions/checkout@v6
@@ -892,7 +913,6 @@ jobs:
 
       - name: Look for links
         run: find . -type f -links +1
-
         # NPM installation fails spuriously all the time
       - name: Install Dependencies
         run: |
@@ -928,14 +948,7 @@ jobs:
 
   publish_java:
     name: Publish Java
-    needs:
-      [
-        versioning,
-        build_jni_linux,
-        build_jni_windows,
-        build_jni_macos,
-        build_jni_android,
-      ]
+    needs: [versioning, build_jni_linux, build_jni_windows, build_jni_macos, build_jni_android]
     runs-on: ubuntu-24.04
     permissions:
       contents: write
@@ -1186,28 +1199,22 @@ jobs:
         working-directory: ${{ github.workspace }}
 
       - name: Publish to NuGet
-        run: dotnet nuget push "${{ env.NUGET_PACKAGES }}/*.nupkg" --api-key "${{ secrets.NUGET_API }}" --source "${{ env.NUGET_SOURCE }}" --skip-duplicate
+        run: dotnet nuget push "${{ env.NUGET_PACKAGES }}/*.nupkg" --api-key "${{ secrets.NUGET_API }}" --source "${{
+          env.NUGET_SOURCE }}" --skip-duplicate
 
       - name: Prepare publish to GitHub Registry
-        run: dotnet nuget add source --username ${{ github.repository_owner }} --password ${{ secrets.GITHUB_TOKEN }} --store-password-in-clear-text --name github "${{ env.GITHUB_PACKAGES_SOURCE }}"
+        run: dotnet nuget add source --username ${{ github.repository_owner }} --password ${{ secrets.GITHUB_TOKEN }}
+          --store-password-in-clear-text --name github "${{ env.GITHUB_PACKAGES_SOURCE }}"
 
       - name: Publish to GitHub Registry
-        run: dotnet nuget push "${{ env.NUGET_PACKAGES }}/*.nupkg"  --api-key "${{ secrets.GITHUB_TOKEN }}" --source "github" --skip-duplicate
+        run: dotnet nuget push "${{ env.NUGET_PACKAGES }}/*.nupkg"  --api-key "${{ secrets.GITHUB_TOKEN }}" --source "github"
+          --skip-duplicate
 
   build_docs:
     name: Build Docs
     runs-on: ubuntu-24.04
     if: ${{ always() }}
-    needs:
-      [
-        publish_python,
-        publish_javascript,
-        publish_rust,
-        publish_java,
-        publish_swift,
-        publish_docker,
-        publish_csharp,
-      ]
+    needs: [publish_python, publish_javascript, publish_rust, publish_java, publish_swift, publish_docker, publish_csharp]
     permissions:
       contents: write
     steps:
@@ -1223,7 +1230,6 @@ jobs:
           npm install -g jsdoc typedoc
       - name: Install USearch from PyPi
         run: pip install usearch
-
         # NPM installation fails spuriously all the time
       - name: Build CJS JS
         run: |