Evidence-gated FreshData performance investigation

.github/workflows/performance-large.yml

@@ -0,0 +1,77 @@
+name: Large performance investigation
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 4 * * 0"
+
+permissions:
+  contents: read
+
+jobs:
+  performance-large:
+    runs-on: ubuntu-latest
+    timeout-minutes: 180
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install benchmark dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,bench,ml]"
+
+      - name: Run large performance matrix
+        id: benchmark
+        continue-on-error: true
+        run: >-
+          python -m benchmarks.performance run
+          --rows 100000,500000,1000000
+          --widths narrow,medium,wide
+          --configs default,conservative,representation_off,statistical_off,explicit
+          --report-modes false,true
+          --warmups 1
+          --repetitions 5
+          --timeout 1800
+          --output benchmarks/results/performance/large
+
+      - name: Analyze all completed and failed cases
+        id: analyze
+        if: always()
+        continue-on-error: true
+        run: >-
+          python -m benchmarks.performance analyze
+          --input benchmarks/results/performance/large
+          --output benchmarks/results/performance/large-summary.json
+
+      - name: Render compact report
+        id: render
+        if: always()
+        continue-on-error: true
+        run: >-
+          python -m benchmarks.performance render
+          --input benchmarks/results/performance/large-summary.json
+          --output benchmarks/results/performance/large-report.md
+
+      - name: Upload performance evidence
+        id: upload
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: performance-large-${{ github.run_id }}
+          path: benchmarks/results/performance/
+          if-no-files-found: error
+
+      - name: Preserve failure status after evidence upload
+        if: >-
+          always() &&
+          (steps.benchmark.outcome != 'success' ||
+          steps.analyze.outcome != 'success' ||
+          steps.render.outcome != 'success' ||
+          steps.upload.outcome != 'success')
+        run: exit 1

.gitignore

@@ -23,8 +23,12 @@ src/freshdata/benchmarks/results/
 /tmp/freshdata_bench/
 /tmp/freshdata_spill/
 
-# Benchmark Release harness: runtime results and generated fixture files
-benchmarks/results/
+# Benchmark runtime results: raw case files stay local; compact evidence is committed.
+benchmarks/results/*
+!benchmarks/results/performance/
+benchmarks/results/performance/*
+!benchmarks/results/performance/*-summary.json
+!benchmarks/results/performance/*-report.md
 benchmarks/generated_fixtures/
 
 # Rust native backend build output

Makefile

@@ -5,7 +5,8 @@ PY ?= python
 # training-* targets are matched by the pattern rule below (pattern rules
 # cannot be .PHONY; the delegated targets are .PHONY inside training/Makefile).
 .PHONY: help benchmark benchmark-ci benchmark-report benchmark-fixtures benchmark-test \
-        cleanbench-full
+        cleanbench-full performance-ci performance-baseline performance-profile \
+        performance-report
 
 help:
 	@echo "Targets:"
@@ -15,6 +16,10 @@ help:
 	@echo "  benchmark-fixtures  Write fixture CSVs to benchmarks/generated_fixtures/"
 	@echo "  benchmark-test      Run the benchmark test suite"
 	@echo "  cleanbench-full     Full CleanBench T1-T5 with release gates + site report"
+	@echo "  performance-ci      Run the CI-safe performance contract suite"
+	@echo "  performance-baseline Run the performance investigation matrix"
+	@echo "  performance-profile Profile one 100k-row performance case"
+	@echo "  performance-report Analyze and render compact performance evidence"
 	@echo "  training-*          Phase-5 training pipeline (see training/Makefile)"
 
 # Full release-gating CleanBench run.
@@ -45,3 +50,16 @@ benchmark-test:
 	# --no-cov: the benchmark suite exercises only a slice of freshdata, so it
 	# must not be measured against the package-wide --cov-fail-under gate.
 	$(PY) -m pytest tests/benchmark -q --no-cov
+
+performance-ci:
+	$(PY) -m pytest tests/performance -q --no-cov
+
+performance-baseline:
+	$(PY) -m benchmarks.performance run --output benchmarks/results/performance/baseline
+
+performance-profile:
+	$(PY) -m benchmarks.performance profile --rows 100000 --widths medium --configs default --report-modes true --output benchmarks/results/performance/baseline
+
+performance-report:
+	$(PY) -m benchmarks.performance analyze --input benchmarks/results/performance/baseline --output benchmarks/results/performance/baseline-summary.json
+	$(PY) -m benchmarks.performance render --input benchmarks/results/performance/baseline-summary.json --output benchmarks/results/performance/baseline-report.md

benchmarks/performance/__init__.py

@@ -0,0 +1,3 @@
+from .datasets import DATASET_TYPES, WIDTHS, DatasetSpec, make_mixed_frame
+
+__all__ = ["DATASET_TYPES", "DatasetSpec", "WIDTHS", "make_mixed_frame"]

benchmarks/performance/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())