V2.0.0

.github/workflows/api-semver.yml

@@ -0,0 +1,48 @@
+name: api-semver
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  public-api-contract:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo
+        uses: Swatinem/rust-cache@v2
+
+      - name: Public API contract test
+        run: cargo test -p ffq-client --test public_api_contract
+
+  semver-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout (full history)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo
+        uses: Swatinem/rust-cache@v2
+
+      - name: Install cargo-semver-checks
+        run: cargo install cargo-semver-checks --locked
+
+      - name: SemVer check (ffq-client vs base branch)
+        env:
+          BASE_REF: ${{ github.base_ref }}
+        run: |
+          BASE_REF="${BASE_REF:-main}"
+          git fetch origin "${BASE_REF}" --depth=1
+          cargo semver-checks check-release \
+            --manifest-path crates/client/Cargo.toml \
+            --baseline-rev "origin/${BASE_REF}"

.github/workflows/bench-13_3.yml

@@ -112,11 +112,15 @@ jobs:
             echo "warmup=1" >> "$GITHUB_OUTPUT"
             echo "iterations=3" >> "$GITHUB_OUTPUT"
             echo "rag_matrix=1000,16,10,1.0;5000,32,10,0.8;10000,64,10,0.2" >> "$GITHUB_OUTPUT"
+            echo "window_matrix=narrow;wide;skewed;many_exprs" >> "$GITHUB_OUTPUT"
+            echo "adaptive_shuffle_matrix=tiny;large;skewed;mixed" >> "$GITHUB_OUTPUT"
           else
             echo "mode=reduced" >> "$GITHUB_OUTPUT"
             echo "warmup=0" >> "$GITHUB_OUTPUT"
             echo "iterations=2" >> "$GITHUB_OUTPUT"
             echo "rag_matrix=1000,16,5,1.0;5000,32,10,0.5" >> "$GITHUB_OUTPUT"
+            echo "window_matrix=narrow;many_exprs" >> "$GITHUB_OUTPUT"
+            echo "adaptive_shuffle_matrix=tiny;skewed" >> "$GITHUB_OUTPUT"
           fi
 
       - name: Run embedded benchmark
@@ -156,6 +160,114 @@ jobs:
           fi
           make bench-13.3-compare BASELINE="${BASELINE}" CANDIDATE="${{ steps.candidate.outputs.json }}" THRESHOLD="${THRESHOLD}"
 
+      - name: Run window benchmark matrix
+        shell: bash
+        run: |
+          set -euo pipefail
+          export FFQ_BENCH_MODE=embedded
+          export FFQ_BENCH_INCLUDE_RAG=0
+          export FFQ_BENCH_WARMUP="${{ steps.matrix.outputs.warmup }}"
+          export FFQ_BENCH_ITERATIONS="${{ steps.matrix.outputs.iterations }}"
+          export FFQ_BENCH_WINDOW_MATRIX="${{ steps.matrix.outputs.window_matrix }}"
+          make bench-v2-window-embedded
+
+      - name: Resolve window candidate artifact
+        id: window_candidate
+        shell: bash
+        run: |
+          set -euo pipefail
+          CANDIDATE_JSON="$(ls -t tests/bench/results/*.json | head -n1)"
+          echo "json=${CANDIDATE_JSON}" >> "$GITHUB_OUTPUT"
+          echo "window_candidate_json=${CANDIDATE_JSON}" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Window regression gate (optional)
+        if: >-
+          ${{
+            github.event_name == 'workflow_dispatch' &&
+            inputs.regression_gate &&
+            steps.matrix.outputs.mode == 'reduced'
+          }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          BASELINE="${{ inputs.baseline_path }}"
+          THRESHOLD="${{ inputs.threshold }}"
+          if [[ -z "${BASELINE}" ]]; then
+            echo "baseline_path is required when regression_gate=true"
+            exit 1
+          fi
+          make bench-v2-window-compare BASELINE="${BASELINE}" CANDIDATE="${{ steps.window_candidate.outputs.json }}" THRESHOLD="${THRESHOLD}"
+
+      - name: Run adaptive shuffle benchmark matrix
+        shell: bash
+        run: |
+          set -euo pipefail
+          export FFQ_BENCH_MODE=embedded
+          export FFQ_BENCH_INCLUDE_RAG=0
+          export FFQ_BENCH_INCLUDE_WINDOW=0
+          export FFQ_BENCH_WARMUP="${{ steps.matrix.outputs.warmup }}"
+          export FFQ_BENCH_ITERATIONS="${{ steps.matrix.outputs.iterations }}"
+          export FFQ_BENCH_ADAPTIVE_SHUFFLE_MATRIX="${{ steps.matrix.outputs.adaptive_shuffle_matrix }}"
+          make bench-v2-adaptive-shuffle-embedded
+
+      - name: Resolve adaptive shuffle candidate artifact
+        id: adaptive_candidate
+        shell: bash
+        run: |
+          set -euo pipefail
+          CANDIDATE_JSON="$(ls -t tests/bench/results/*.json | head -n1)"
+          echo "json=${CANDIDATE_JSON}" >> "$GITHUB_OUTPUT"
+          echo "adaptive_candidate_json=${CANDIDATE_JSON}" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Adaptive shuffle regression gate (optional)
+        if: >-
+          ${{
+            github.event_name == 'workflow_dispatch' &&
+            inputs.regression_gate &&
+            steps.matrix.outputs.mode == 'reduced'
+          }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          BASELINE="${{ inputs.baseline_path }}"
+          THRESHOLD="${{ inputs.threshold }}"
+          if [[ -z "${BASELINE}" ]]; then
+            echo "baseline_path is required when regression_gate=true"
+            exit 1
+          fi
+          make bench-v2-adaptive-shuffle-compare BASELINE="${BASELINE}" CANDIDATE="${{ steps.adaptive_candidate.outputs.json }}" THRESHOLD="${THRESHOLD}"
+
+      - name: Run pipelined-shuffle TTFR benchmark
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [[ "${{ steps.matrix.outputs.mode }}" == "full" ]]; then
+            export FFQ_PIPE_TTFR_ROWS=600000
+            export FFQ_PIPE_TTFR_WARMUP=1
+            export FFQ_PIPE_TTFR_ITERATIONS=3
+          else
+            export FFQ_PIPE_TTFR_ROWS=250000
+            export FFQ_PIPE_TTFR_WARMUP=1
+            export FFQ_PIPE_TTFR_ITERATIONS=2
+          fi
+          export FFQ_PIPE_TTFR_SHUFFLE_PARTITIONS=64
+          make bench-v2-pipelined-shuffle
+
+      - name: Resolve pipelined TTFR candidate artifact
+        id: pipelined_candidate
+        shell: bash
+        run: |
+          set -euo pipefail
+          CANDIDATE_JSON="$(ls -t tests/bench/results/bench_v2_pipelined_shuffle_ttfr_*.json | head -n1)"
+          echo "json=${CANDIDATE_JSON}" >> "$GITHUB_OUTPUT"
+          echo "pipelined_candidate_json=${CANDIDATE_JSON}" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Pipelined TTFR threshold gate
+        shell: bash
+        run: |
+          set -euo pipefail
+          make bench-v2-pipelined-shuffle-gate CANDIDATE="${{ steps.pipelined_candidate.outputs.json }}"
+
       - name: Upload benchmark artifacts
         uses: actions/upload-artifact@v4
         with:

.github/workflows/docs-v2-guardrails.yml

@@ -0,0 +1,21 @@
+name: docs-v2-guardrails
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  docs-v2-guardrails:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Validate v2 docs guardrails
+        run: python3 scripts/validate-docs-v2.py
+

.github/workflows/feature-matrix.yml

@@ -0,0 +1,34 @@
+name: feature-matrix
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  build-matrix:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo
+        uses: Swatinem/rust-cache@v2
+
+      - name: Build core-only (no default features)
+        run: cargo build --no-default-features
+
+      - name: Build minimal preset
+        run: cargo build -p ffq-client --no-default-features --features minimal
+
+      - name: Build distributed + python + s3
+        run: cargo build --features distributed,python,s3
+
+      - name: Build full feature matrix
+        run: cargo build -p ffq-client --no-default-features --features core,distributed,s3,vector,qdrant,python,ffi
+
+      - name: FFI C example smoke
+        run: make ffi-example

.github/workflows/python-wheels.yml

@@ -0,0 +1,76 @@
+name: python-wheels
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  wheel-linux:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build manylinux wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          args: --release --out dist
+      - name: Wheel smoke test (pip install + collect)
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pyarrow dist/*.whl
+          python - <<'PY'
+          import os
+          import ffq
+          root = os.getcwd()
+          lineitem = os.path.join(root, "tests/fixtures/parquet/lineitem.parquet")
+          e = ffq.Engine()
+          e.register_table("lineitem", lineitem)
+          df = e.sql("SELECT l_orderkey FROM lineitem LIMIT 1")
+          t = df.collect()
+          assert t.num_rows == 1, t
+          print("python wheel smoke: OK")
+          PY
+      - name: Upload Linux wheel
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheel-linux
+          path: dist/*
+
+  wheel-macos:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build macOS wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          command: build
+          args: --release --out dist
+      - name: Wheel smoke test (pip install + collect)
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pyarrow dist/*.whl
+          python - <<'PY'
+          import os
+          import ffq
+          root = os.getcwd()
+          lineitem = os.path.join(root, "tests/fixtures/parquet/lineitem.parquet")
+          e = ffq.Engine()
+          e.register_table("lineitem", lineitem)
+          df = e.sql("SELECT l_orderkey FROM lineitem LIMIT 1")
+          t = df.collect()
+          assert t.num_rows == 1, t
+          print("python wheel smoke: OK")
+          PY
+      - name: Upload macOS wheel
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheel-macos
+          path: dist/*