Sync main into dev

.github/workflows/action-smoke.yml

@@ -0,0 +1,76 @@
+name: Gate Action Smoke Test
+
+on:
+  push:
+    branches: [main, dev, "develop/august"]
+    paths:
+      - action.yml
+      - pyproject.toml
+      - src/framevitals/cli.py
+      - src/framevitals/operations.py
+      - .github/workflows/action-smoke.yml
+  pull_request:
+    paths:
+      - action.yml
+      - pyproject.toml
+      - src/framevitals/cli.py
+      - src/framevitals/operations.py
+      - .github/workflows/action-smoke.yml
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Create stable fixture datasets
+        shell: bash
+        run: |
+          cat > reference.csv <<'CSV'
+          age,income,segment
+          21,30000,basic
+          34,62000,pro
+          48,81000,pro
+          52,90000,enterprise
+          CSV
+          cp reference.csv current.csv
+
+      - name: Run local FrameVitals gate action
+        id: framevitals
+        uses: ./
+        with:
+          current: current.csv
+          reference: reference.csv
+          output: gate-result.json
+
+      - name: Verify action outputs
+        shell: bash
+        env:
+          STATUS: ${{ steps.framevitals.outputs.status }}
+          PASSED: ${{ steps.framevitals.outputs.passed }}
+          RESULT_PATH: ${{ steps.framevitals.outputs.result-path }}
+        run: |
+          test "$STATUS" = "pass"
+          test "$PASSED" = "true"
+          test "$RESULT_PATH" = "gate-result.json"
+          test -s gate-result.json
+          python - <<'PY'
+          import json
+          from pathlib import Path
+
+          payload = json.loads(Path("gate-result.json").read_text(encoding="utf-8"))
+          assert payload["status"] == "pass"
+          assert payload["passed"] is True
+          assert payload["checks_run"] == ["drift"]
+          PY

.github/workflows/benchmark.yml

@@ -0,0 +1,152 @@
+name: Performance Benchmark
+
+on:
+  push:
+    branches: [main, "develop/august"]
+    paths:
+      - "src/framevitals/**"
+      - "benchmarks/**"
+      - ".github/workflows/benchmark.yml"
+  workflow_dispatch:
+    inputs:
+      rows:
+        description: Rows in the synthetic profile benchmark workload
+        required: false
+        default: "50000"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  profile-scale:
+    name: profile scale benchmark
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install benchmark runtime
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[arrow]"
+
+      - name: Run reproducible profile benchmark
+        env:
+          BENCHMARK_ROWS: ${{ inputs.rows || '50000' }}
+        run: |
+          python benchmarks/benchmark_profile_scale.py \
+            --rows "$BENCHMARK_ROWS" \
+            --numeric-columns 40 \
+            --categorical-columns 5 \
+            --scenarios numpy auto parquet \
+            --output benchmark-results.json
+
+      - name: Publish benchmark summary
+        run: |
+          python - <<'PY'
+          import json
+          import os
+          from pathlib import Path
+
+          payload = json.loads(Path("benchmark-results.json").read_text(encoding="utf-8"))
+          lines = [
+              "## FrameVitals profile benchmark",
+              "",
+              "| Scenario | Seconds | Peak RSS (MB) | Backend |",
+              "| --- | ---: | ---: | --- |",
+          ]
+          for measurement in payload["measurements"]:
+              backend = measurement.get("backend_status", {}).get("selected", "unknown")
+              lines.append(
+                  f"| {measurement['scenario']} | {measurement['elapsed_seconds']:.3f} "
+                  f"| {measurement['peak_rss_mb']:.1f} | {backend} |"
+              )
+          lines.extend([
+              "",
+              "Results are measurements, not absolute pass/fail thresholds. Compare like-for-like runs.",
+          ])
+          Path(os.environ["GITHUB_STEP_SUMMARY"]).write_text(
+              "\n".join(lines) + "\n",
+              encoding="utf-8",
+          )
+          PY
+
+      - name: Upload benchmark result
+        uses: actions/upload-artifact@v5
+        with:
+          name: framevitals-profile-benchmark
+          path: benchmark-results.json
+          retention-days: 30
+
+  deep-8k-180:
+    name: 8k x 180 Deep benchmark
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install benchmark runtime
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e "."
+
+      - name: Run reproducible 8k x 180 Deep benchmark
+        env:
+          FRAMEVITALS_BACKEND: numpy
+        run: |
+          python benchmarks/benchmark_deep_pipeline.py \
+            --rows 8000 \
+            --columns 180 \
+            --output deep-benchmark-results.json
+
+      - name: Publish Deep benchmark summary
+        run: |
+          python - <<'PY' >> "$GITHUB_STEP_SUMMARY"
+          import json
+          from pathlib import Path
+
+          payload = json.loads(Path("deep-benchmark-results.json").read_text())
+          print("## FrameVitals 8k x 180 Deep benchmark")
+          print()
+          print(f"- Wall time: **{payload['elapsed_seconds']:.3f}s**")
+          print(f"- Historical original: {payload['historical_original_seconds']:.3f}s")
+          print(f"- Speedup vs historical original: **{payload['speedup_vs_historical_original']:.2f}x**")
+          print(f"- 10x target: {payload['ten_x_target_seconds']:.3f}s")
+          print(f"- Target met: **{payload['ten_x_target_met']}**")
+          print()
+          print("### Pipeline stages")
+          for name, milliseconds in sorted(payload["pipeline_timings_ms"].items()):
+              if isinstance(milliseconds, (int, float)):
+                  print(f"- {name}: {milliseconds / 1000:.3f}s")
+          PY
+
+      - name: Upload Deep benchmark result
+        uses: actions/upload-artifact@v6
+        with:
+          name: framevitals-deep-8k-180-benchmark
+          path: deep-benchmark-results.json
+          retention-days: 30

.github/workflows/codeql.yml

@@ -0,0 +1,45 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+  schedule:
+    - cron: "17 4 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: ${{ matrix.language }} security analysis
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      packages: read
+      security-events: write
+    strategy:
+      fail-fast: false
+      matrix:
+        language:
+          - python
+          - javascript-typescript
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Analyze
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{ matrix.language }}"

.github/workflows/developer-guardrails.yml

@@ -0,0 +1,57 @@
+name: Developer Guardrails
+
+on:
+  pull_request:
+    paths:
+      - ".pre-commit-config.yaml"
+      - "pyproject.toml"
+      - "src/framevitals/**"
+      - "tests/**"
+      - ".github/workflows/developer-guardrails.yml"
+  push:
+    branches: [main, dev, "develop/august"]
+    paths:
+      - ".pre-commit-config.yaml"
+      - "pyproject.toml"
+      - "src/framevitals/**"
+      - "tests/**"
+      - ".github/workflows/developer-guardrails.yml"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  hooks:
+    name: pre-commit + pre-push contracts
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install development environment
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Verify dependency consistency
+        run: python -m pip check
+
+      - name: Run commit-stage hooks
+        run: pre-commit run --all-files --hook-stage pre-commit --show-diff-on-failure
+
+      - name: Run pre-push public contract hooks
+        run: pre-commit run --all-files --hook-stage pre-push --show-diff-on-failure

.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: Docs
+
+on:
+  push:
+    branches: [main, dev, "develop/august"]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: strict MkDocs build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install documentation dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+      - name: Verify dependency consistency
+        run: python -m pip check
+
+      - name: Build documentation strictly
+        run: mkdocs build --strict