Mid-term recommendations: contract unification, shared currency data, benchmarks, PEP 562 lazy exports

.github/workflows/ci.yml

@@ -49,6 +49,16 @@ jobs:
       - name: Import lint
         run: uv run import-linter lint
 
+      - name: Check generated Currency/Money data drift
+        run: uv run python tools/regenerate_currency_data.py --check
+
+      - name: Check generated SIUnit data drift
+        run: uv run python tools/regenerate_si_prefix_data.py --check
+
+      - name: Benchmark (informational, non-blocking)
+        continue-on-error: true
+        run: uv run python -m benchmarks.harness --iterations 50 --output /tmp/bench.json && cat /tmp/bench.json
+
       - name: Tests with coverage
         run: uv run pytest --cov=paxman --cov-report=term-missing --cov-report=html --tb=short -q
 

HOW_TO_ADD_NEW_CAPABILITY.md

@@ -438,6 +438,8 @@ Every contract and rule in the codebase follows the same structural rules. The `
 
 **1. Every contract MUST inherit `CapabilityContract`**
 
+Subclass `CapabilityContract` (never `Contract` directly). `Contract` is engine-internal since ADR-0007.
+
 Import it from `paxman.core.contract` (defined in `paxman/core/capability_contract.py`). Your contract is a frozen dataclass subclass:
 
 ```python

benchmarks/README.md

@@ -0,0 +1,11 @@
+# Benchmarks (Item 7, W5)
+
+One scenario per capability, deterministic per (input, contract, library snapshot).
+
+Run:
+  uv run python -m benchmarks.harness --iterations 200
+  uv run python -m benchmarks.harness --output bench.json
+  uv run python -m benchmarks.harness --update-baseline  # refresh committed baseline.json
+
+CI runs 50 iterations informational (non-blocking). Baseline is tracked but not gated.
+Add a new capability: add one entry to `benchmarks/scenarios.py` with `register` + `contract_factory`.

benchmarks/baseline.json

@@ -0,0 +1,95 @@
+{
+  "scenarios": [
+    {
+      "capability": "country",
+      "iterations": 100,
+      "mean_ms": 0.27881579706445336,
+      "p50_ms": 0.20324101205915213,
+      "p95_ms": 0.31342904549092054,
+      "min_ms": 0.15853706281632185,
+      "max_ms": 4.520129994489253
+    },
+    {
+      "capability": "currency",
+      "iterations": 100,
+      "mean_ms": 0.1070823660120368,
+      "p50_ms": 0.10521896183490753,
+      "p95_ms": 0.12719491496682167,
+      "min_ms": 0.090339919552207,
+      "max_ms": 0.15212292782962322
+    },
+    {
+      "capability": "date",
+      "iterations": 100,
+      "mean_ms": 0.11676306487061083,
+      "p50_ms": 0.0926790526136756,
+      "p95_ms": 0.17091899644583464,
+      "min_ms": 0.0784930307418108,
+      "max_ms": 0.26655092369765043
+    },
+    {
+      "capability": "email",
+      "iterations": 100,
+      "mean_ms": 0.09656466194428504,
+      "p50_ms": 0.09762297850102186,
+      "p95_ms": 0.11605804320424795,
+      "min_ms": 0.060654012486338615,
+      "max_ms": 0.17720204778015614
+    },
+    {
+      "capability": "ip",
+      "iterations": 100,
+      "mean_ms": 0.13068879838101566,
+      "p50_ms": 0.14457793440669775,
+      "p95_ms": 0.17728202510625124,
+      "min_ms": 0.08774595335125923,
+      "max_ms": 0.27406506706029177
+    },
+    {
+      "capability": "isbn",
+      "iterations": 100,
+      "mean_ms": 0.13500795583240688,
+      "p50_ms": 0.13043393846601248,
+      "p95_ms": 0.18328602891415358,
+      "min_ms": 0.0971390400081873,
+      "max_ms": 0.20166800823062658
+    },
+    {
+      "capability": "money",
+      "iterations": 100,
+      "mean_ms": 0.20503543317317963,
+      "p50_ms": 0.20394206512719393,
+      "p95_ms": 0.246229930780828,
+      "min_ms": 0.11839496437460184,
+      "max_ms": 0.5321740172803402
+    },
+    {
+      "capability": "phone",
+      "iterations": 100,
+      "mean_ms": 0.18060301197692752,
+      "p50_ms": 0.18282991368323565,
+      "p95_ms": 0.21669501438736916,
+      "min_ms": 0.10399601887911558,
+      "max_ms": 0.46293798368424177
+    },
+    {
+      "capability": "si_unit",
+      "iterations": 100,
+      "mean_ms": 0.12988552218303084,
+      "p50_ms": 0.12476707343012094,
+      "p95_ms": 0.15376601368188858,
+      "min_ms": 0.11326710227876902,
+      "max_ms": 0.2440139651298523
+    },
+    {
+      "capability": "url",
+      "iterations": 100,
+      "mean_ms": 0.23713358445093036,
+      "p50_ms": 0.2435100032016635,
+      "p95_ms": 0.27114199474453926,
+      "min_ms": 0.14298106543719769,
+      "max_ms": 0.47093897592276335
+    }
+  ],
+  "iterations": 100
+}

benchmarks/harness.py

@@ -0,0 +1,97 @@
+"""Minimal benchmark harness — one scenario per capability (W5, Item 7).
+
+No external deps. Deterministic per contract+input+library snapshot.
+Measures wall-clock via time.perf_counter, reports mean/p50/p95 per scenario.
+Used in CI as non-blocking signal and locally via --update-baseline.
+
+Usage:
+    uv run python -m benchmarks.harness --iterations 200
+    uv run python -m benchmarks.harness --output /tmp/bench.json
+    uv run python -m benchmarks.harness --update-baseline
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import statistics
+import sys
+import time
+from pathlib import Path
+
+from benchmarks.scenarios import SCENARIOS
+
+ROOT = Path(__file__).resolve().parents[1]
+BASELINE = ROOT / "benchmarks" / "baseline.json"
+
+
+def run_once(
+    capability: str, text: str, iterations: int = 100
+) -> dict[str, float | str | int]:
+    from paxman import canonicalize
+    from paxman.core.discovery import reset_registry
+
+    if iterations <= 0:
+        raise ValueError(f"iterations must be a positive integer, got {iterations!r}")
+
+    # Import capability lazily to respect PEP 562 (Item 8)
+    # — harness must not hide import cost
+    # Scenarios carry a factory: lambda: (contract, text)
+    scenario = next(s for s in SCENARIOS if s["capability"] == capability)
+    durations: list[float] = []
+    for _ in range(iterations):
+        reset_registry()
+        # Register only the needed capability for this scenario
+        # (isolates import cost if lazy)
+        scenario["register"]()
+        contract = scenario["contract_factory"]()
+        start = time.perf_counter()
+        canonicalize(text, contract)
+        durations.append((time.perf_counter() - start) * 1000)
+        # reset_registry cleans for next iteration
+        reset_registry()
+    durations.sort()
+    p50 = durations[len(durations) // 2]
+    p95 = durations[int(len(durations) * 0.95)]
+    return {
+        "capability": capability,
+        "iterations": iterations,
+        "mean_ms": statistics.mean(durations),
+        "p50_ms": p50,
+        "p95_ms": p95,
+        "min_ms": min(durations),
+        "max_ms": max(durations),
+    }
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(description="Paxman benchmark harness (Item 7)")
+    parser.add_argument("--iterations", type=int, default=100)
+    parser.add_argument("--output", type=str, default=None)
+    parser.add_argument("--update-baseline", action="store_true")
+    args = parser.parse_args(argv)
+
+    results: list[dict[str, float | str | int]] = []
+    for scenario in SCENARIOS:
+        results.append(
+            run_once(
+                scenario["capability"], scenario["text"], iterations=args.iterations
+            )
+        )
+
+    payload: dict[str, object] = {"scenarios": results, "iterations": args.iterations}
+    if args.output:
+        Path(args.output).write_text(
+            json.dumps(payload, indent=2) + "\n", encoding="utf-8"
+        )
+        print(f"wrote {args.output}")
+    elif args.update_baseline:
+        BASELINE.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+        print(f"wrote {BASELINE}")
+    else:
+        json.dump(payload, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+
+
+if __name__ == "__main__":
+    main()