chore(deps): add hypothesis + pre-commit to dev deps + document local hook activation

.pre-commit-config.yaml

@@ -4,7 +4,7 @@ repos:
     # ([project.optional-dependencies].dev / [dependency-groups].dev) and
     # .github/workflows/ci.yml. A different ruff here produces different
     # formatter output than CI and breaks `ruff format --check` in lint.
-    rev: v0.15.9
+    rev: v0.15.14
     hooks:
       - id: ruff
         args: [--fix]

CONTRIBUTING.md

@@ -15,8 +15,18 @@ uv sync --extra dev
 
 # Or with pip in your own venv:
 # pip install -e ".[dev]"
+
+# Activate pre-commit hooks (one-time, per clone)
+pre-commit install
 ```
 
+The `pre-commit install` step is important: the repo has a
+`.pre-commit-config.yaml` that pins ruff to the exact version CI uses,
+but the actual git hook is per-machine and **must be installed
+locally**. Without this step, you can commit code that passes your
+local lint (using whatever ruff version you happen to have installed)
+but fails CI on push.
+
 ## Running Tests
 
 ```bash
@@ -25,6 +35,23 @@ uv run pytest tests/ -v
 
 All tests must pass before submitting a PR. Tests should run without API keys or network access.
 
+### Property-based tests (optional)
+
+`hypothesis` is available in the dev extras for property-based tests:
+
+```python
+from hypothesis import given, strategies as st
+
+@given(st.text(min_size=1, max_size=40))
+def test_function_never_fabricates_output_on_random_input(s):
+    # ... property that must hold for ANY string in the strategy
+```
+
+Hypothesis generates hundreds of inputs per test and shrinks failing
+cases to a minimal counterexample. Useful any time a function returns
+`Optional[X]` or has a wide input domain — it catches the failure-space
+gaps that hand-written positive tests miss.
+
 ## Running Benchmarks
 
 ```bash

pyproject.toml

@@ -58,7 +58,29 @@ chroma = "mempalace.backends.chroma:ChromaBackend"
 [project.entry-points."mempalace.sources"]
 
 [project.optional-dependencies]
-dev = ["pytest>=7.0", "pytest-cov>=4.0", "ruff==0.15.14", "psutil>=5.9"]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff==0.15.14",
+    "psutil>=5.9",
+    # Property-based testing — generates hundreds of random inputs per
+    # test to find counterexamples the hand-written positive tests miss.
+    # Used opt-in (sprinkle ``@given(...)`` on a test); zero runtime
+    # cost on tests that don't use it.
+    "hypothesis>=6.0",
+    # Pre-commit framework — gates every local ``git commit`` on the
+    # same ruff checks CI runs. Required activation step in
+    # CONTRIBUTING.md: ``pre-commit install`` once per clone. Without
+    # this, contributors silently bypass the lint gate locally and only
+    # discover failures at CI time.
+    "pre-commit>=3.0",
+    # mypy — static type checker. Catches lazy ``list`` / ``dict``
+    # annotations that should be ``list[str]`` / ``dict[str, int]``,
+    # missing return types, mismatched signatures across call sites.
+    # Run ad-hoc with ``mypy mempalace/``; CI doesn't gate on it yet but
+    # contributors should fix mypy errors they see before pushing.
+    "mypy>=1.0",
+]
 spellcheck = ["autocorrect>=2.0"]
 # Hardware acceleration for the ONNX embedding model. Install exactly one:
 #   pip install mempalace[gpu]       — NVIDIA CUDA
@@ -85,7 +107,15 @@ extract = [
 ]
 
 [dependency-groups]
-dev = ["pytest>=7.0", "pytest-cov>=4.0", "ruff==0.15.14", "psutil>=5.9"]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff==0.15.14",
+    "psutil>=5.9",
+    "hypothesis>=6.0",
+    "pre-commit>=3.0",
+    "mypy>=1.0",
+]
 
 [build-system]
 requires = ["hatchling"]