qavf 0.4.0__tar.gz

qavf-0.4.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

qavf-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+on:
+  push:
+    branches: [main]
+    paths-ignore: ["**.md", "docs/**", "LICENSE"]
+  pull_request:
+    paths-ignore: ["**.md", "docs/**", "LICENSE"]
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  UV_VERSION: "0.12.23"
+
+jobs:
+  test:
+    name: Lint, types and tests (Linux)
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: "3.12"
+          enable-cache: true
+      - run: uv sync --all-extras --locked
+      - run: uv run --no-sync ruff check .
+      - run: uv run --no-sync mypy qavf scripts
+      - run: uv run --no-sync python scripts/generate_docs.py --check
+      - run: uv run --no-sync python -m pytest -q -p no:cacheprovider --ignore=tests/integration
+
+  platforms:
+    name: Platform-specific tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: "3.12"
+          enable-cache: true
+      - run: uv sync --all-extras --locked
+      # Code paths that differ by operating system: isolation, locking, numerics,
+      # file identity and benchmark measurement. The full matrix runs on release tags.
+      - run: >-
+          uv run --no-sync python -m pytest -q -p no:cacheprovider
+          tests/test_isolated_supervisor.py tests/test_execution_isolation.py
+          tests/test_execution_policy.py tests/test_isolation_transport.py
+          tests/test_regression_exactness.py tests/test_statistical_rules.py
+          tests/test_scan_identity.py tests/test_loading_native_binding.py
+          tests/test_performance_metrics.py tests/test_performance_runner.py
+          tests/test_performance_process_tree.py

qavf-0.4.0/.github/workflows/verify.yml

@@ -0,0 +1,273 @@
+name: Release verification
+# Full platform, dependency-floor and live-service matrix; run for release tags only.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+permissions:
+  contents: read
+
+env:
+  # Keep service credentials synthetic and local to the disposable CI runner.
+  UV_VERSION: "0.12.23"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: ${{ matrix.python }}
+      - run: uv sync --all-extras --locked
+      - run: uv run --no-sync python scripts/verify_release.py extensions
+      - run: uv run --no-sync python scripts/verify_release.py test ${{ matrix.python == '3.12' && '--coverage' || '' }} --id linux-${{ matrix.python }}-source --output evidence/linux-${{ matrix.python }}-source.json
+      - if: ${{ !cancelled() }}
+        run: uv run --no-sync python scripts/verify_release.py test --optimized --id linux-${{ matrix.python }}-source-optimized --output evidence/linux-${{ matrix.python }}-source-optimized.json
+      - run: uv run --no-sync ruff check .
+      - run: uv run --no-sync mypy qavf scripts
+      - run: uv run --no-sync python scripts/generate_docs.py --check
+      - run: uv build --clear
+      - run: uv run --no-sync python scripts/verify_dist.py
+      - run: uv run --no-sync python scripts/verify_release.py installed --id linux-${{ matrix.python }}-wheel --output-dir evidence
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: evidence-linux-${{ matrix.python }}
+          path: evidence/*.json
+          if-no-files-found: error
+      - uses: actions/upload-artifact@v4
+        with:
+          name: qavf-distributions-${{ matrix.python }}
+          path: dist/*
+          if-no-files-found: error
+
+  dependency-floors:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: "3.12"
+      - run: uv sync --all-extras --locked
+      - run: uv build --clear
+      - run: uv run --no-sync python scripts/verify_dist.py
+      - run: uv run --no-sync python scripts/verify_release.py installed --mode floors --id floors --output-dir evidence
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: evidence-floors
+          path: evidence/*.json
+          if-no-files-found: error
+
+  platform-contracts:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: windows-latest
+            label: windows
+          - os: macos-latest
+            label: macos
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: "3.12"
+      - run: uv sync --all-extras --locked
+      - run: uv run --no-sync python scripts/verify_release.py extensions
+      - run: uv run --no-sync python scripts/verify_release.py test --id ${{ matrix.label }}-3.12-source --output evidence/${{ matrix.label }}-3.12-source.json
+      - if: ${{ !cancelled() }}
+        run: uv run --no-sync python scripts/verify_release.py test --optimized --id ${{ matrix.label }}-3.12-source-optimized --output evidence/${{ matrix.label }}-3.12-source-optimized.json
+      - run: uv build --clear
+      - run: uv run --no-sync python scripts/verify_dist.py
+      - run: uv run --no-sync python scripts/verify_release.py installed --id ${{ matrix.label }}-3.12-wheel --output-dir evidence
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: evidence-${{ matrix.label }}-3.12
+          path: evidence/*.json
+          if-no-files-found: error
+
+  core-installation:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: "3.12"
+      - run: uv sync --all-extras --locked
+      - run: uv build --clear
+      - run: uv run --no-sync python scripts/verify_dist.py
+      - run: uv run --no-sync python scripts/verify_release.py installed --mode core --id core --output-dir evidence
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: evidence-core
+          path: evidence/*.json
+          if-no-files-found: error
+
+  integrations:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16.10
+        env:
+          POSTGRES_USER: qavf
+          POSTGRES_PASSWORD: qavf
+          POSTGRES_DB: qavf
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 12
+    env:
+      QAVF_POSTGRES_DSN: "host=127.0.0.1 port=5432 dbname=qavf user=qavf password=qavf connect_timeout=5"
+      QAVF_S3_ENDPOINT: http://127.0.0.1:9000
+      QAVF_S3_ACCESS_KEY: qavf-integration
+      QAVF_S3_SECRET_KEY: local-integration-secret
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: "3.12"
+      - run: uv sync --all-extras --group integration --locked
+      - run: uv run --no-sync python scripts/verify_release.py extensions --integration
+      # moto's standalone server is a disposable S3-compatible endpoint; it accepts
+      # the synthetic credentials and needs no container registry.
+      - name: Start disposable S3-compatible object store
+        run: |
+          nohup uvx --from "moto[server]==5.2.3" moto_server -H 127.0.0.1 -p 9000 > moto.log 2>&1 &
+          echo $! > moto.pid
+      - name: Wait for object store readiness
+        run: curl --fail --silent --retry 20 --retry-all-errors --retry-delay 2 -o /dev/null http://127.0.0.1:9000/moto-api/
+      - name: Run required live integrations
+        run: uv run --no-sync python scripts/verify_release.py test --integration --id integrations --output evidence/integrations.json tests/integration
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: evidence-integrations
+          path: evidence/*.json
+          if-no-files-found: error
+      - name: Stop disposable object store
+        if: always()
+        run: kill "$(cat moto.pid)" 2>/dev/null || true
+
+  release-assurance:
+    name: Required release assurance
+    runs-on: ubuntu-latest
+    needs: [test, dependency-floors, platform-contracts, core-installation, integrations]
+    if: always()
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+          python-version: "3.12"
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: evidence-*
+          path: collected-evidence
+      - name: Reject missing, stale, failed, skipped, or incomplete release jobs
+        env:
+          QAVF_CI_JOBS: ${{ toJSON(needs) }}
+        run: uv run --no-project python scripts/verify_release.py aggregate --evidence-dir collected-evidence --output release-assurance.json
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: release-assurance
+          path: release-assurance.json
+          if-no-files-found: error
+
+  # Publishing runs only for v* tags, after every required job and the strict
+  # aggregate passed. It ships the exact distributions those jobs verified.
+  publish-pypi:
+    name: Publish to PyPI
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: release-assurance
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/qavf/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: qavf-distributions-3.12
+          path: dist
+      - name: Require the tag to match the verified package version
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          ls -l dist
+          test -f "dist/qavf-${TAG#v}-py3-none-any.whl"
+          test -f "dist/qavf-${TAG#v}.tar.gz"
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: GitHub release
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: qavf-distributions-3.12
+          path: dist
+      - name: Create the release with distributions and SHA-256 hashes
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          (cd dist && sha256sum -- * > SHA256SUMS && cat SHA256SUMS)
+          gh release create "$TAG" dist/* --repo "$GITHUB_REPOSITORY" \
+            --title "QAVF ${TAG#v}" --generate-notes --verify-tag
+
+  container:
+    name: Container image
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: qavf-distributions-3.12
+          path: dist
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+      - id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/ahmedaredah/qavf
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

qavf-0.4.0/.gitignore

@@ -0,0 +1,23 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# QAVF generated artefacts
+qa_output/
+examples/data/
+examples/baseline/
+.coverage
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.hypothesis/
+.coverage.*
+release-evidence/

qavf-0.4.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.4.0] - 2026-10-18
+
+First public release.
+
+- Validation API (`validate`, `QARunner`) and CLI for files, globs, URLs, databases,
+  SQL queries, Polars/pandas/Arrow frames and Python loaders.
+- 28 built-in rules: input contracts, column limits, keys and foreign keys, row
+  expressions and SQL assertions, freshness, temporal and spatial checks, outlier and
+  drift detection, reconciliation and regression against accepted baselines.
+- Fail-closed assessment: checks that cannot be assessed make a run incomplete rather
+  than passing, with exact counts and bounded, deterministic evidence.
+- HTML and JSON reports with full run provenance and redacted credentials.
+- Resource budgets for memory, spill storage, evidence and report size, and optional
+  isolated execution with OS-enforced limits on Linux, macOS and Windows.
+- Plugin discovery for rules and sources from packages, files and entry points.

qavf-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Aredah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qavf-0.4.0/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.5
+Name: qavf
+Version: 0.4.0
+Summary: Configurable, plugin-based data QA/QC: column limits, SQL checks, temporal and spatial outliers, regression testing and HTML reports, over any source DuckDB can read.
+Project-URL: Homepage, https://github.com/AhmedAredah/qavf
+Project-URL: Documentation, https://github.com/AhmedAredah/qavf/tree/main/docs
+Project-URL: Issues, https://github.com/AhmedAredah/qavf/issues
+Project-URL: Changelog, https://github.com/AhmedAredah/qavf/blob/main/CHANGELOG.md
+Author-email: Ahmed Aredah <Ahmed.Aredah@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: data-quality,data-validation,duckdb,outlier-detection,polars,qa,qc,regression-testing,validation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: duckdb>=1.2
+Requires-Dist: jinja2>=3.1
+Requires-Dist: markupsafe>=2.1
+Requires-Dist: numpy>=1.26
+Requires-Dist: polars>=1.32
+Requires-Dist: pyarrow>=16
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0.1
+Provides-Extra: all
+Requires-Dist: pandas>=2.2; extra == 'all'
+Requires-Dist: scipy>=1.11.3; extra == 'all'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.2; extra == 'pandas'
+Provides-Extra: stats
+Requires-Dist: scipy>=1.11.3; extra == 'stats'
+Description-Content-Type: text/markdown
+
+# QAVF
+
+[![CI](https://github.com/AhmedAredah/qavf/actions/workflows/ci.yml/badge.svg)](https://github.com/AhmedAredah/qavf/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/qavf)](https://pypi.org/project/qavf/)
+[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue)](https://github.com/AhmedAredah/qavf/blob/main/pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/AhmedAredah/qavf/blob/main/LICENSE)
+
+**Configurable data QA/QC for Python.** Validate files, dataframes and database
+queries against declared limits, statistical expectations and stored baselines.
+QAVF reports exact violation counts with bounded evidence, and it never reports a
+pass for a check it could not assess.
+
+- **Any input.** CSV, Parquet, JSON, Excel, globs and URLs; DuckDB, SQLite, PostgreSQL
+  and MySQL tables; SQL queries; Polars, pandas and Arrow frames; Python loaders.
+- **Column limits.** Types, nullability, ranges, allowed values, patterns, lengths,
+  uniqueness, keys, foreign keys and aggregate statistics, each with its own severity.
+- **Statistical and temporal QA.** Trend, jump, seasonal and level-shift checks; entity
+  outliers; coverage gaps; distribution drift; reconciliation of totals across datasets.
+- **Regression testing.** Keyed, tolerance-aware comparison against accepted baselines,
+  usable from pytest.
+- **Reports and CI gates.** HTML and JSON reports, deterministic evidence and exit codes.
+- **Extensible.** Rules and sources are plain classes discovered from packages, files or
+  entry points.
+
+## Install
+
+```bash
+pip install "qavf[stats]"                                     # or: uv tool install "qavf[stats]"
+docker run --rm -v "$PWD:/work" ghcr.io/ahmedaredah/qavf run -c qavf.yaml
+```
+
+Python 3.12 or newer on Linux, macOS or Windows. The `stats` extra adds SciPy-based
+tests; `pandas` adds pandas adapters; `all` installs both. In GitHub Actions, use
+[`AhmedAredah/qavf-action`](https://github.com/AhmedAredah/qavf-action).
+
+## Quick start
+
+```bash
+qavf demo my-demo && qavf run -c my-demo/qavf.yaml   # open my-demo/qa_output/qa_report.html
+```
+
+For your own data, generate a configuration with inferred limits, review it, then run it:
+
+```bash
+qavf init -d data/counts.csv -d crashes=data/crashes.parquet --margin 0.1
+qavf run -c qavf.yaml
+```
+
+```yaml
+datasets:
+  counts:
+    path: data/counts.csv
+    schema:
+      primary_key: [site_id, year]
+      columns:
+        site_id: {dtype: str, regex: 'S\d{2}'}
+        aadt:
+          dtype: int
+          ge: 0
+          checks:
+            - {le: 200000, severity: WARNING, name: implausibly high}
+        truck_share: {dtype: float, ge: 0, le: 1}
+    foreign_keys:
+      - {columns: [site_id], ref_dataset: sites}
+  sites:
+    path: data/sites.csv
+    schema: {primary_key: [site_id]}
+```
+
+Row expressions and SQL assertions run in DuckDB, where each dataset is a table:
+
+```yaml
+datasets:
+  crashes:
+    path: data/crashes.parquet
+    expressions:
+      - {expr: fatal <= crashes, severity: CRITICAL}
+assertions:
+  - name: every site has counts
+    sql: SELECT site_id FROM sites WHERE site_id NOT IN (SELECT site_id FROM counts)
+```
+
+[`config/qavf.full.yaml`](https://github.com/AhmedAredah/qavf/blob/main/config/qavf.full.yaml)
+documents every option. Paths are relative to the configuration file, and any string
+may use `${ENV_VAR}` so credentials stay out of the file.
+
+## Python API
+
+```python
+from qavf import Dataset, ResourceLimits, validate
+
+report = validate(
+    "readings.parquet",
+    schema={"columns": {"value": {"dtype": "float", "ge": 0}}},
+)
+print(report.verdict())
+
+report = validate({
+    "counts": Dataset(counts_frame, schema={"columns": {"count": {"ge": 0}}}),
+    "sites": Dataset("sites.parquet", schema={"primary_key": ["site_id"]}),
+})
+
+# Run in a supervised worker process with OS-enforced limits.
+report = validate("readings.parquet", config="qavf.yaml",
+                  resources=ResourceLimits(wall_time=60, address_space="4GiB"))
+```
+
+## How a run is judged
+
+Each result is **PASS**, **FAIL**, **SKIPPED** (nothing configured) or **ERROR**
+(configured but not assessed, for example missing data or invalid SQL).
+
+| Verdict | When | Exit code |
+|---|---|---|
+| passed | Every configured check was assessed and no failure meets `engine.fail_on` | 0 |
+| failed | A failure at or above `engine.fail_on` (default `ERROR`) | 1 |
+| incomplete | Any configured check could not be assessed | 1 |
+
+Use `engine.require` to name checks that must be assessed for a run to pass.
+
+## Rules
+
+| ID | Default | Checks |
+|---|---|---|
+| INP-001 | CRITICAL | Sources accessible and schemas inspectable |
+| INP-002 | CRITICAL | Columns present with declared types; row-count limits |
+| INP-003 | ERROR* | Column QA limits (*per-check severities) |
+| INP-004 | ERROR | Primary keys unique |
+| INP-005 | ERROR* | Foreign keys resolve |
+| INP-006 | ERROR* | Row expressions hold |
+| INP-007 | ERROR* | SQL assertions return no rows |
+| INP-008 | ERROR | Newest date/time value is recent enough |
+| TMP-001 | WARNING | Period-over-period change within a rate |
+| TMP-002 | WARNING | Series trend in their declared direction |
+| TMP-003 | WARNING | No period is a significant and material trend outlier |
+| TMP-004 | ERROR | No group is missing a period |
+| TMP-005 | WARNING | No value stuck for several periods |
+| TMP-006 | ERROR | Cumulative series never decrease |
+| TMP-007 | WARNING | No value is anomalous for its season |
+| TMP-008 | WARNING | No series shifts to a sustained new level |
+| SPA-001 | WARNING | No entity is an outlier among its peers |
+| SPA-002 | WARNING | Each entity within a factor of its group's median |
+| SPA-003 | ERROR | Every expected entity is covered in every period |
+| GEO-001 | ERROR | Coordinates valid, present and inside a bounding box |
+| STA-001 | WARNING | z-score, modified z-score or IQR outlier scans |
+| STA-002 | WARNING | Distributions have not drifted from a reference |
+| REC-001 | ERROR | Totals reconcile between datasets, key by key |
+| REC-002 | ERROR | Shares sum to their total within each group |
+| REC-003 | ERROR | The full expected key grid is present |
+| REC-004 | ERROR | Two datasets have the same key set |
+| REC-005 | ERROR | Related datasets carry one identical batch id |
+| REG-001 | ERROR | Outputs match baselines within tolerance |
+
+Parameters for every rule: [docs/rules.md](https://github.com/AhmedAredah/qavf/blob/main/docs/rules.md)
+or `qavf list-rules`.
+
+## Regression testing
+
+```python
+from qavf.regression import assert_outputs_match
+
+
+def test_output_matches_baseline(tmp_path):
+    run_pipeline(output=tmp_path / "out.parquet")
+    assert_outputs_match("tests/baselines/out.parquet", tmp_path / "out.parquet",
+                         keys=["site_id", "year"], rtol=1e-6)
+```
+
+Rows match by key, numbers within tolerance, and changed values, added or removed rows
+and schema changes are reported. Accept reviewed outputs with `qavf baseline`, which
+records a manifest with the keys, column types and a SHA-256 of the file.
+
+## CLI
+
+| Command | Purpose |
+|---|---|
+| `qavf run -c CONFIG` | Run QA and write HTML/JSON reports |
+| `qavf init -d [NAME=]PATH` | Profile data and write a starting configuration |
+| `qavf profile PATH` | Print inferred QA limits for a file |
+| `qavf schema` | Write the configuration JSON Schema for editor support |
+| `qavf list-rules` | List discovered rules |
+| `qavf compare BASELINE CANDIDATE -k KEY` | Compare an output with a baseline |
+| `qavf baseline SOURCE DEST -k KEY` | Accept an output as a baseline |
+| `qavf demo DIR` | Write a runnable demo project |
+
+Exit codes: `0` passed, `1` QA failed or outputs differ, `2` usage, configuration or
+resource error.
+
+## Documentation
+
+- [Python API](https://github.com/AhmedAredah/qavf/blob/main/docs/api.md) and
+  [sources](https://github.com/AhmedAredah/qavf/blob/main/docs/sources.md)
+- [Rules reference](https://github.com/AhmedAredah/qavf/blob/main/docs/rules.md) and
+  [writing plugins](https://github.com/AhmedAredah/qavf/blob/main/docs/plugins.md)
+- [Resource limits](https://github.com/AhmedAredah/qavf/blob/main/docs/resources.md) and
+  [isolated execution](https://github.com/AhmedAredah/qavf/blob/main/docs/execution_limits.md)
+- [Numerical contracts](https://github.com/AhmedAredah/qavf/blob/main/docs/numerics.md) and
+  [baseline acceptance](https://github.com/AhmedAredah/qavf/blob/main/docs/baseline_acceptance.md)
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check . && uv run mypy qavf scripts
+```
+
+See [release assurance](https://github.com/AhmedAredah/qavf/blob/main/docs/release_assurance.md)
+for the full verification matrix and [CHANGELOG.md](CHANGELOG.md) for changes.
+
+## License
+
+[MIT](LICENSE)