paxman 0.1.0__tar.gz

paxman-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,72 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [main, "feature/**", "refactor/**"]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
+
+      - name: Set up Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --python ${{ matrix.python-version }}
+
+      - name: Ruff lint
+        run: uv run ruff check paxman/ tests/
+
+      - name: Ruff format check
+        run: uv run ruff format --check paxman/ tests/
+
+      - name: Pyright type check
+        run: uv run pyright
+
+      - 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
+
+      - name: Enforce per-package coverage
+        run: |
+          echo "Checking per-package coverage thresholds..."
+          uv run coverage report --include="paxman/core/*" --fail-under=95
+          uv run coverage report --include="paxman/capabilities/*" --fail-under=95
+          uv run coverage report --include="paxman/engine/*" --fail-under=95
+          uv run coverage report --include="paxman/api/*" --fail-under=95
+          echo "All packages meet 95% coverage threshold."

paxman-0.1.0/.github/workflows/opencode.yml

@@ -0,0 +1,33 @@
+name: opencode
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+
+jobs:
+  opencode:
+    if: |
+      contains(github.event.comment.body, ' /oc') ||
+      startsWith(github.event.comment.body, '/oc') ||
+      contains(github.event.comment.body, ' /opencode') ||
+      startsWith(github.event.comment.body, '/opencode')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+      pull-requests: read
+      issues: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Run opencode
+        uses: anomalyco/opencode/github@latest
+        env:
+          OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
+        with:
+          model: ${{ secrets.OPENCODE_MODEL_ID }}

paxman-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,88 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Validate version matches tag
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          TAG_RAW="${GITHUB_REF#refs/tags/}"
+          if [[ ! "$TAG_RAW" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::Tag $TAG_RAW does not match expected format vX.Y.Z"
+            exit 1
+          fi
+          TAG="${TAG_RAW#v}"
+          VERSION="$(uv run python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          echo "Tag: $TAG  pyproject version: $VERSION"
+          if [ "$TAG" != "$VERSION" ]; then
+            echo "::error::Tag v$TAG does not match pyproject.toml version $VERSION"
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Twine check
+        run: uv run --with twine twine check dist/*
+
+      - name: Verify py.typed in wheel
+        run: |
+          uv run python -c "
+          import zipfile, pathlib, sys
+          whls = list(pathlib.Path('dist').glob('*.whl'))
+          assert whls, 'no wheel built'
+          for whl in whls:
+              with zipfile.ZipFile(whl) as z:
+                  names = z.namelist()
+                  assert any(n.endswith('paxman/py.typed') for n in names), f'py.typed missing in {whl.name}: {names[:20]}'
+                  print(f'py.typed Ships in {whl.name}')
+          "
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI via Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1
+        with:
+          verbose: true
+          print-hash: true

paxman-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+.omo
+.worktrees/
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.venv/
+venv/
+ENV/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.pyright/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/

paxman-0.1.0/AGENTS.md

@@ -0,0 +1,108 @@
+# PROJECT KNOWLEDGE BASE
+
+**Generated:** 2026-08-22
+**Commit:** d7737f0
+**Branch:** chores/pre-release-housekeeping
+
+## OVERVIEW
+Paxman is a Python 3.11+ canonicalization library with a small CLI: takes ambiguous human input, returns what authoritative specs say it means, with full provenance. Deterministic, provenance-first. 12 capabilities (Country, Currency, Date, Email, IBAN, IP, ISBN, ISSN, Money, Phone, SI Unit, URL). Toolchain: uv + hatchling, ruff, strict pyright, import-linter, pytest at 95% coverage.
+
+## STRUCTURE
+```text
+paxman/
+├── api/            # canonicalize() + bootstrap (register_all_shipped, list_shipped_capabilities)
+├── cli.py          # CLI: `paxman` console script / `python -m paxman` (--list, --json, stdin)
+├── __main__.py     # python -m paxman entry
+├── engine/         # run_capability() pipeline orchestrator
+├── core/           # domain objects, Contract protocol, registry, extensions, errors (+ grammar/ shared machinery)
+├── capabilities/   # 12 self-contained capability packages
+├── shared_data/    # cross-capability source snapshots (currency_snapshot.json → Currency + Money data)
+└── py.typed        # PEP 561 marker
+benchmarks/         # harness.py (CI-run), grammar_stage_parity.py, baseline.json
+tests/              # unit / capabilities/<cap> / integration / property / e2e
+tools/              # new_capability.py (scaffolder), generate_readme_table.py,
+                    # regenerate_{isbn_range,si_prefix,idna_uts46,currency}_data.py
+docs/               # adr/, development/, recipes/, user/
+```
+
+## WHERE TO LOOK
+| Task | Location |
+|------|----------|
+| Trace pipeline flow | `paxman/engine/orchestrator.py` → `run_capability()` |
+| Domain vocabulary (Rule, Provenance, Candidate…) | `paxman/core/domain.py` |
+| Contract protocol | `paxman/core/contract.py`, `paxman/core/capability_contract.py` |
+| Capability registration | `paxman/core/discovery.py` (explicit, never auto) |
+| Community extensions | `paxman/core/extensions.py` → `register_grammar` / `register_rule` + `extra_grammars` on contracts |
+| Error hierarchy | `paxman/core/errors.py` |
+| Add a capability | `HOW_TO_ADD_NEW_CAPABILITY.md` (62KB spec — read first). Scaffold first with `tools/new_capability.py` (see HOW_TO_ADD_NEW_CAPABILITY.md Step 0); then fill in the domain. |
+| Recognition (per cap) | `paxman/capabilities/<Name>/grammar/` |
+| Validation (per cap) | `paxman/capabilities/<Name>/rules/` |
+| Presentation seam | `paxman/capabilities/<Name>/capability.py` → `format_value()` |
+| Regenerate generated data | `tools/regenerate_isbn_range_data.py` (ISBN range), `tools/regenerate_si_prefix_data.py` (SIUnit prefixed units), `tools/regenerate_idna_uts46_data.py` (URL IDNA mapping), `tools/regenerate_currency_data.py` (Currency + Money from `paxman/shared_data/currency_snapshot.json`) |
+| CLI behavior | `paxman/cli.py` (`--list`, `--json`, stdin; contract flags are API-only) |
+| Merge-blocking commands | `.github/workflows/ci.yml` (authoritative) |
+
+## CODE MAP
+| Symbol | Type | Location | Role |
+|--------|------|----------|------|
+| `canonicalize()` | function | `paxman/api/canonicalize.py` | Sole user entry point → `run_capability()` |
+| `register_all_shipped()` / `list_shipped_capabilities()` | functions | `paxman/api/bootstrap.py` | One-call registration of the 12 shipped capabilities; deterministic name list |
+| `list_registered_capabilities()` | function | `paxman/core/discovery.py` | Introspection of the live registry |
+| `register_capability()` | function | `paxman/core/discovery.py` | Registry add; freezes on first run |
+| `register_grammar()` / `register_rule()` | functions | `paxman/core/extensions.py` | Community extension seam (opt-in via contract `extra_grammars`) |
+| `run_capability()` | function | `paxman/engine/orchestrator.py` | Full pipeline (recognize→validate→resolve→hash) |
+| `ExecutionResult` | dataclass | `paxman/engine/orchestrator.py` | Return type of `canonicalize()` |
+| `Capability` | ABC | `paxman/core/capability.py` | `get_grammars`/`get_rules`/`format_value` |
+| `CapabilityContract` | dataclass | `paxman/core/capability_contract.py` | Frozen contract base (no slots) |
+| `Contract` | Protocol | `paxman/core/contract.py` | Structural contract interface |
+| `Rule` / `Grammar` | ABCs | `paxman/core/domain.py` | Validation / recognition units |
+| `Resolution`, `Provenance`, `Candidate`, `RecognizedRep`, `VersionStamp` | dataclasses | `paxman/core/domain.py` | Pipeline value objects |
+| `main()` | function | `paxman/cli.py` | CLI entry (`[project.scripts] paxman` + `python -m paxman`) |
+
+## CONVENTIONS
+- **uv only** — no Makefile/tox/nox. Every command via `uv run`.
+- Per-capability layout: `notation.py`, `contract.py`, `capability.py`, `grammar/`, `rules/`.
+- Rule file = ONE publication (`rfc_5322_ed2008.py`); class = one section; rule `name` = `"Section 3.4.1-addr-spec"`.
+- Grammars recognize only: span-bearing `RecognitionMatch`, never bare notation, never validate/dedup/order.
+- Rules never read `output_format` (CI source-scan enforced), never raise, never gate on `include_*` (declared as `requires_features`).
+- `format_value()` is the ONLY presentation seam; `output_format` resolved in `CapabilityContract.__post_init__`.
+- Domain objects: `@dataclass(frozen=True, slots=True)`. Contracts: `@dataclass(frozen=True)` **without** slots.
+- Test doubles local to the test file/conftest — no shared mock libraries.
+- Registry is module-level and freezes per pipeline run; tests use autouse `_clean_registry` fixture (integration/e2e).
+- TDD: failing test first. No skipped tests without justification.
+
+## ANTI-PATTERNS (THIS PROJECT)
+- **No `# type: ignore` / `# noqa` / `# pyright: ignore` in `paxman/` source** — fix root cause or use scoped ruff `per-file-ignores` (sanctioned pattern in pyproject). Tests may use `# type: ignore[misc]` for immutability checks.
+- Deterministic by construction: given the same input, the same contract, and the same library snapshot (fixed library version, registry contents, and rule-data tables), the pipeline always yields the same canonical output — no world-knowledge, no clock, no environment-dependent ordering, no fuzzy logic, no network inference across recognition, validation, and canonicalization.
+- No cross-capability imports; capabilities import only from `paxman.core`; `paxman.core` imports nothing from `paxman.*`.
+- Grammars must not map tokens to canonical values or import rule-layer data.
+- Rules never contain the token `output_format` (code, comments, or docstrings).
+- No `as any`, no broad exception suppression.
+
+## COMMANDS
+```bash
+uv sync --all-extras                                   # install
+uv run ruff check paxman/ tests/                      # lint
+uv run ruff format --check paxman/ tests/             # format check
+uv run pyright                                        # strict typecheck
+uv run import-linter lint                             # layer boundaries
+uv run pytest                                         # all tests
+uv run pytest -m "unit or capability or integration or e2e"      # by marker (also: property, benchmark, country, currency, isbn, issn, money, url, si_unit)
+uv run pytest --cov=paxman --cov-report=term-missing --tb=short -q
+uv run coverage report --include="paxman/core/*,paxman/capabilities/*,paxman/engine/*,paxman/api/*" --fail-under=95
+uv run python tools/regenerate_isbn_range_data.py     # regenerate ISBN range message module
+uv run python tools/regenerate_si_prefix_data.py      # regenerate SIUnit prefixed-unit modules
+uv run python tools/regenerate_idna_uts46_data.py     # regenerate URL IDNA UTS #46 mapping
+uv run python tools/regenerate_currency_data.py       # regenerate Currency + Money data from shared snapshot
+uv run python -m paxman email "user@example.com"      # CLI smoke test
+```
+Full pre-PR gate: `uv run ruff check . && uv run ruff format --check . && uv run pyright && uv run import-linter lint && uv run pytest`
+
+## NOTES
+- `paxman/capabilities/__init__.py` exports all twelve shipped capabilities (Country, Currency, Date, Email, IBAN, IP, ISBN, ISSN, Money, Phone, SI Unit, URL); export completeness is enforced by `tests/unit/test_capability_exports.py`.
+- CONTEXT.md is the domain glossary for the full shipped set (twelve capabilities). It is kept in sync with the code; when adding a capability, update its Notation/table entries there too.
+- No `pyrightconfig.json` — pyright config is inline `[tool.pyright]` in pyproject.toml. No `.editorconfig`.
+- Data modules live under `rules/data/` and `grammar/data/` — plain module-level tables separating data from logic. Generated modules (edit via snapshot + regenerate, never by hand): ISBN range message (`tools/regenerate_isbn_range_data.py`), URL IDNA UTS #46 mapping (`tools/regenerate_idna_uts46_data.py`), SIUnit prefixed-unit and grammar token tables (`tools/regenerate_si_prefix_data.py`), and the Currency + Money data set (`tools/regenerate_currency_data.py`, from `paxman/shared_data/currency_snapshot.json`). Unmarked data files are edited directly.
+- Library + CLI: `[project.scripts] paxman = "paxman.cli:main"` and `python -m paxman`; CLI supports `--list`, `--json`, stdin input. Version 0.1.0.
+- Publishing: `.github/workflows/publish.yml` uses PyPI Trusted Publishing (OIDC) with a Git-tag ↔ `pyproject.toml` version safety check; `paxman/py.typed` ships PEP 561 conformance.
+- Coverage: global `fail_under = 95`; `paxman/cli.py` and `paxman/__main__.py` are omitted from coverage (smoke-tested via e2e).

paxman-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,258 @@
+# Paxman Architecture
+
+Paxman is a canonicalization authority resolver — a library that takes ambiguous human input and returns what authoritative specifications say that input means, with full provenance. This document describes the architectural principles, structural layers, and design decisions that shape the system.
+
+---
+
+## Core Principles
+
+### Determinism
+
+Paxman never guesses. Given the same input, the same contract configuration, and the same library snapshot (fixed library version, registry contents, and rule-data tables), the pipeline always yields the same canonical output. This property holds by construction: every pipeline stage — grammar recognition, rule validation, capability formatting, candidate deduplication, and status determination — is a pure function of its inputs with no world-knowledge, no clock, no environment-dependent ordering, no fuzzy logic, and no network inference. Identical inputs therefore always produce identical outputs, enabling auditability and reproducibility. Across library snapshots, provenance or rule-routing changes may alter the resulting metadata; the determinism guarantee is scoped to a fixed snapshot.
+
+### Provenance-First
+
+Every canonicalized value carries full provenance — a citation of the authoritative specification, registry, or policy that validates it. Provenance is not optional metadata; it is a structural requirement. If no authority can validate a recognized input, the system reports INVALID rather than returning an unvalidated value. This ensures that users always know *why* a value is considered canonical.
+
+### Separation of Recognition and Validation
+
+Paxman strictly separates the act of finding values in text (recognition) from the act of determining whether those values are valid (validation). This separation is the foundation of the architecture:
+
+- **Recognition** (syntactic): Grammars scan raw text and extract structured representations. They do not validate — they only find.
+- **Validation** (semantic): Rules accept structured representations and determine whether authoritative specifications validate them. They produce canonical values with provenance.
+
+This separation means that a single input can be recognized by multiple grammars and validated by multiple rules, enabling ambiguity detection when different authoritative sources disagree.
+
+### Recognition Pipeline Contract
+
+Every grammar implements `recognize(text) -> list[RecognitionMatch]`, where
+`RecognitionMatch` carries the notation plus a half-open `[start, end)` span
+and the matched `raw_text`. The grammar produces positions; the engine owns
+all cross-match policy:
+
+- **Containment dedup (per grammar):** a match fully contained in a longer
+  match from the SAME grammar is dropped ("longer wins"). Matches from the
+  same grammar with identical `[start, end)` spans keep the first-emitted
+  match. Dedup never runs across grammars, so two grammars agreeing on the
+  same span (e.g. US vs European date reading of `01/02/2026`) are both
+  preserved and ambiguity stays observable.
+- **Ordering:** recognitions are emitted in the total order
+  `(start, end, active-set index, grammar name)`, i.e. document order — where the
+  active set is `contract.active_grammars` or, when the contract returns `None`,
+  every shipped grammar in `get_grammars()` order.
+- **Candidate dedup** (`value, recognition_rule, validation_rule`) runs
+  after validation as a stability net.
+
+Grammars perform syntax-level extraction and normalization only; rules own
+semantic validation with provenance. This contract applies identically to
+every capability, built-in or future.
+
+### Capability Isolation
+
+Each domain (Email, Date, Country, etc.) is encapsulated as a **Capability** — an independent module that defines its own intermediate representation, recognition rules, and validation rules. Capabilities cannot import from each other. The engine and core domain provide the orchestration layer; capabilities provide the domain expertise.
+
+---
+
+## Structural Layers
+
+Paxman is organized into four layers, each with a distinct responsibility. Dependencies flow inward — outer layers depend on inner layers, never the reverse.
+
+### Core Domain
+
+The innermost layer defines the shared vocabulary and abstract contracts that all other layers consume. It contains:
+
+- **Abstract base classes** for Grammars (recognition) and Rules (validation)
+- **Immutable value objects** representing provenance, candidates, recognized representations, and version stamps
+- **Enums** for resolution status (MISSING, INVALID, SUCCESS, AMBIGUOUS) and rule strategies (REGEX, LOOKUP_TABLE, PARSER)
+- **The Contract protocol** — a structural interface that all capability contracts must satisfy
+- **The Capability abstract class** — a base class that all capability implementations must extend
+- **The discovery registry** — a module-level registry that manages capability registration and lookup
+- **Exception hierarchy** — typed errors for different failure modes
+
+The core layer has no knowledge of specific capabilities. It defines *what* a capability is, not *how* any particular capability works.
+
+### Capabilities
+
+Each capability is a self-contained domain module that provides:
+
+- **A Notation type** — a typed intermediate representation specific to the domain (e.g., email local part and domain part, date N1/N2/N3)
+- **Grammars** — recognition rules that extract the notation from raw text
+- **Validation Rules** — semantic rules that validate the notation against authoritative specifications
+- **A Contract** — a user-facing configuration object that toggles grammars, excludes rules, and passes parameters
+
+Capabilities are registered with the discovery registry before the first canonicalization call. The registry freezes on the first `canonicalize()` call and remains frozen for later runs, ensuring that the set of available capabilities is stable during execution. The sanctioned bulk form is `paxman.register_all_shipped()`, which registers all ten shipped capabilities in fixed alphabetical order; registration — single or bootstrap — must complete from a single thread before the first `canonicalize()` call, after which reads are safe from any thread.
+
+### Engine
+
+The engine is the orchestration layer that coordinates the full pipeline. It:
+
+1. Freezes the capability registry
+2. Looks up the requested capability by name
+3. Runs the recognition phase — iterating over active grammars to extract span-bearing recognition matches
+4. Runs the validation phase — testing each notation against active rules, which normalize to each capability's default canonical form and never inspect `output_format`
+5. Formats each validated value through the capability's `format_value()` seam — immediately after normalization and before deduplication and status determination
+6. Deduplicates identical candidates
+7. Determines the resolution status based on candidate outcomes
+8. Assembles the final execution result
+
+The engine is capability-agnostic. It does not know what a "grammar" or "rule" does — it only knows that grammars produce span-bearing recognition matches and rules produce candidates.
+
+Before the recognition phase, the engine composes each capability's shipped grammars and rules with any community extensions registered for that capability (see "Community Extensions" below). Composition is guarded: duplicate names fail fast, and every rule's declared `target_semantics` must resolve within the composed set.
+
+### Public API
+
+The outermost layer exposes the user-facing interface. It is intentionally minimal — a single entry point that accepts input text and a contract, and returns a fully-resolved execution result with full provenance.
+
+---
+
+## Key Architectural Patterns
+
+### Protocol-Based Contracts
+
+Contracts are defined as structural protocols (`Contract`), not inheritance-based base classes. Any class that satisfies the structural interface — providing the required attributes and methods — qualifies as a contract. This allows capability authors to design contract objects that fit their domain (using dataclasses, Pydantic models, etc.) without being constrained by a base class hierarchy. This prioritizes **user flexibility** and **decoupling**.
+
+### ABC-Based Capabilities
+
+In contrast to contracts, Capabilities are defined as Abstract Base Classes (`Capability`). This prioritizes **internal rigidity** and **reliability**. Since capabilities are internal components managed by the engine's registry, strict inheritance ensures they adhere to the required structure (`get_grammars()`, `get_rules()`) and prevents runtime errors during discovery.
+
+### Capability as Factory
+
+Capabilities do not hold state. They are factories that produce grammars and rules on demand. The engine queries a capability for its available grammars and rules, then filters them based on the contract configuration. This design keeps capabilities lightweight and makes the filtering logic centralized in the engine.
+
+### Typed Notation
+
+Each capability defines a frozen dataclass Notation with one `str` field per recognized component (e.g., `DateNotation` carries `N1`, `N2`, `N3`). The concrete notation type is the sole type parameter threaded end to end: `Grammar[NotationT]` recognizes it and `Rule[NotationT]` validates it, so the engine and every rule operate on the fully typed object rather than a positional `list[str]`. Rules read notation fields by name (e.g., `notation.N1`); there is no generic list alias and no conversion bridge between the typed notation and a list form.
+
+### Contract Parameters
+
+Contracts pass configuration parameters to validation rules, enabling rules to adapt their behavior based on user preferences.
+
+**Base Contract Parameters:**
+- **`output_format`**: Controls the canonical value format (e.g., `"ISO"` for `YYYY-MM-DD`, `"US"` for `MM/DD/YYYY`). `CapabilityContract.__post_init__` resolves `None`, `"default"`, and each capability's default format to a concrete string; the capability's `format_value()` seam applies the format to the rule-produced default canonical value. Validation rules never inspect `output_format` — they always normalize to the default canonical form. See "The Formatting Seam" below.
+- **`pinned_rules`**: Pins to specific validation rules by name. When set, ONLY those rules run — `excluded_rules` is ignored. Takes precedence over `excluded_rules`.
+- **`extra_grammars`**: Names community grammars (opt-in) to run alongside the capability's shipped active set — `contract.active_grammars`, or every shipped grammar when the contract returns `None` — in order. Unknown names are silently skipped; shipped names listed here are deduplicated. Registration happens through `paxman.register_grammar` / `paxman.register_rule` (see "Community Extensions" below).
+
+**Date-Specific Parameters:**
+- **`two_digit_base_year`**: Specifies the base year for interpreting two-digit years (e.g., `2000` means `"26"` becomes `2026`). Only available on Date contracts, not part of the base Contract protocol. Used by US and European grammars to resolve ambiguous year values.
+
+These parameters are passed through the contract to rule methods (`matches()` and `normalize()`), allowing rules to be contract-aware without direct coupling to specific capabilities. `output_format` is the exception: it is a presentation parameter consumed by the capability's formatting seam, never by validation rules.
+
+### The Formatting Seam
+
+Validation and presentation are separated at the pipeline level. Rules own validation and default normalization only: `matches()` never consults `output_format`, and `normalize()` always returns the capability's default canonical form (e.g., `YYYY-MM-DD` for Date, E.164 `+CCNSN` for Phone, alpha-2 for Country). The engine then renders each validated value through the capability's `format_value(value, output_format, notation)` method — called immediately after `normalize()` and before candidate deduplication and status determination:
+
+**recognition → validation → default normalization → capability formatting → candidate deduplication → status → result**
+
+Formatting adds no provenance: `Candidate.provenance`, `recognition_rule`, and `validation_rule` are set from the rule that validated the notation, and the formatter only transforms the value. Date, Phone, and Country implement conversions; Email and IP inherit the identity implementation because they offer no alternative formats.
+
+A CI source scan (`tests/unit/test_rule_output_format_purity.py`) rejects any `output_format` token in `paxman/capabilities/*/rules/` modules — in code, comments, or docstrings — so presentation cannot migrate back into rules. In the Country capability, localized names (e.g., `Alemania` → `DE`) are formatted through the current alpha-2 conversion tables for `alpha3`, `numeric`, and `name` while retaining Unicode/CLDR provenance; historical former codes (e.g., `SU`) pass through unchanged for those formats when no current mapping exists, retaining ISO 3166-3 provenance.
+
+### Immutability
+
+All domain objects are immutable. Once created, they cannot be modified. This is enforced through `@dataclass(frozen=True, slots=True)` — stdlib dataclasses that prevent attribute assignment and use efficient slot-based storage. Immutability ensures that objects can be safely shared, hashed, and used as dictionary keys without defensive copying.
+
+### Temporal Filtering
+
+Rules carry a publication year from their authoritative specification. When a contract specifies a year, the engine filters out rules whose publication year exceeds that year. This allows users to pin to a specific historical version of a specification, excluding rules from newer revisions.
+
+### Determinism by Construction
+
+Determinism is a structural property of the layered pipeline, not a post-hoc artifact:
+
+- **Recognition layer.** Active grammars emit span-bearing `RecognitionMatch` objects from the input text, matching the `Grammar.recognize()` contract. Grammar output depends only on the input and the grammar itself.
+- **Validation layer.** Rules accept recognized representations and produce candidates, each carrying a canonical value and provenance. A rule's output depends only on the representation and the contract.
+- **Result layer.** The engine deduplicates identical candidates and folds the distinct candidate values into one of the resolution statuses: `SUCCESS` when all candidates agree on a single canonical value, `AMBIGUOUS` when they disagree, `INVALID` when nothing validated, and `MISSING` when no grammar recognized anything.
+
+Every stage is a pure function of its inputs — no clocks, no randomness, no environment-dependent ordering, no world-knowledge, no fuzzy logic, no network inference — so the same input, contract configuration, and library snapshot (fixed library version, registry contents, and rule-data tables) always produce the same canonical output. The `VersionStamp` on each execution result records the library version for provenance; the determinism guarantee rests on this determinism-by-construction. Changes to provenance or rule routing across library snapshots can alter result metadata; the determinism guarantee is scoped to a fixed snapshot.
+
+### Community Extensions
+
+Capabilities are closed for modification but open for extension. Community contributors register additional grammars (and the rules that validate them) against an existing capability through `paxman.core.extensions` — never by editing the capability package. The registries freeze with the capability registry at the first pipeline run.
+
+A contract opts a registered grammar in by naming it in `extra_grammars`, a base `CapabilityContract` field surfaced on every `create_contract` factory. The engine composes the shipped active set with the opted-in extras, deduplicating names while preserving order — shipped slots first, extras after (unknown extra names are silently skipped). The shipped slots are `contract.active_grammars` when the contract implements it (the gated capabilities), or every shipped grammar in `get_grammars()` order when it returns `None` (the base default). Opt-in preserves determinism: a contract that names no extras composes to exactly the shipped set, so non-opt-in behavior is identical (deterministic).
+
+Community rules follow the same opt-in discipline: a registered rule runs only when the contract's `extra_grammars` resolve to one of its `target_semantics` ids. An un-opted community rule — even one targeting a shipped grammar's semantics — never affects results, so a default contract resolves with shipped rules only.
+
+Composition is guarded at pipeline start: a community grammar name colliding with a shipped name raises `CapabilityError`, and an opted-in community rule whose `target_semantics` names an id no grammar claims raises `ContractError` — failing fast rather than producing a silently wrong result. Community grammars and rules are pure functions of their inputs, and the composed set is fixed once the registries freeze, so the determinism guarantees of "Determinism by Construction" extend unchanged.
+
+---
+
+## Resolution Semantics
+
+The system produces one of four resolution statuses:
+
+| Status | Meaning |
+|--------|---------|
+| **MISSING** | No grammars recognized anything in the input. The input does not match any known pattern. |
+| **INVALID** | Grammars recognized the input, but no validation rule could validate it against an authoritative specification. |
+| **SUCCESS** | One or more rules validated the input, and all agree on the same canonical value. |
+| **AMBIGUOUS** | Multiple rules validated the input but produced different canonical values. The system cannot determine which is correct. |
+
+Ambiguity is detected at the value level, not the candidate level. Multiple candidates with the same canonical value still produce SUCCESS. Ambiguity requires genuinely different canonical outputs from different authoritative sources.
+
+For multi-entity input, segmentation is caller-owned — see the [segmentation recipe](docs/recipes/segmentation.md) (ADR-0004 companion).
+
+---
+
+## Error Handling
+
+The exception hierarchy separates different failure modes:
+
+- **CapabilityError** — the requested capability is unknown or the registry is in an invalid state
+- **ContractError** — the contract configuration is malformed or missing required fields
+- **RecognitionError** — a grammar failed during recognition (e.g., malformed regex), wrapping the original exception
+- **ValidationError** — a rule failed during validation (e.g., unexpected data), wrapping the original exception
+
+Recognition and validation errors carry the name of the offending rule and the original exception, enabling targeted debugging without losing context.
+
+---
+
+## Quality Enforcement
+
+Paxman enforces architectural invariants through tooling:
+
+- **Static type checking** in strict mode ensures type safety across all layers
+- **Import boundary enforcement** prevents capability-to-capability dependencies and ensures the core layer remains independent
+- **Linting and formatting** enforce consistent code style
+- **Rule-purity source scan** fails CI when any validation-rule module under `paxman/capabilities/*/rules/` references `output_format`, enforcing that presentation is owned solely by `Capability.format_value()`
+- **Property-based testing** validates domain object contracts (immutability, equality, hashability)
+
+These tools run as part of the development workflow and block merges when invariants are violated.
+
+---
+
+## Date Capability Design
+
+The Date capability demonstrates the system's handling of ambiguous inputs through multiple grammars and validation rules.
+
+### Grammars
+
+Three grammars recognize date patterns with different position mappings:
+
+| Grammar | Delimiter | N1 (first) | N2 (second) | N3 (third) | Notes |
+|---------|-----------|------------|-------------|------------|-------|
+| ISO | `-` | year | month | day | 4-digit year only |
+| US | `/` | month | day | year | Supports 2-digit years |
+| European | `/` | day | month | year | Supports 2-digit years |
+
+European and US grammars both use `/` as delimiter. Ambiguity arises from different position mappings, not delimiters.
+
+### Validation Rules
+
+Three rules validate date notations against authoritative specifications:
+
+| Rule | Standard | Canonical Output |
+|------|----------|------------------|
+| ISO 8601 | ISO 8601:2019 | `YYYY-MM-DD` |
+| US federal | US government standard | `YYYY-MM-DD` |
+| EN 50160 | European EN 50160 | `YYYY-MM-DD` |
+
+All rules normalize to ISO 8601 format (`YYYY-MM-DD`) regardless of input grammar; the capability's formatting seam applies a requested alternative (e.g., `output_format="US"`) to that default afterward.
+
+### Ambiguity Detection
+
+When the same input is recognized by multiple grammars, each grammar produces notation with different position mappings. For example, `"01/02/2026"` is recognized by both US and European grammars:
+- US grammar: N1=month=01, N2=day=02, N3=year=2026
+- European grammar: N1=day=01, N2=month=02, N3=year=2026
+
+Each grammar's notation flows to its corresponding validation rule. If both rules validate and produce different canonical values, the system reports AMBIGUOUS.