sqlrules 0.1.0__tar.gz → 0.2.0__tar.gz

{sqlrules-0.1.0 → sqlrules-0.2.0}/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0/).
 
+## [0.2.0] - 2026-07-10
+
+### Added
+
+- Two-phase compilation: `Compiler.compile_model()` (static IR) and
+  `Compiler.bind()` (column resolve + translate)
+- In-process metadata cache for Phase-1 `ModelIR` (default on; disable with
+  `cache=False`)
+- Structured diagnostics: public `Diagnostic` via `compiler.diagnostics` for
+  skipped constraints under `on_unsupported="warn"` / `"ignore"`
+- Type support for `UUID` and `time` (range comparisons for `time`;
+  Literal/Enum for `UUID`)
+- First-class `pattern` constraint IR (no portable core translator; register
+  a custom translator or use a future dialect plugin)
+- IR types: `ModelIR`, `FieldIR`, `Diagnostic`
+- Local benchmark suite: `python -m benchmarks.bench_compile`
+
+### Changed
+
+- Unsupported-constraint error messages no longer hard-code a release version
+- `CompilationContext` carries an optional diagnostics collector
+- Unconstrained `UUID` / `time` fields are skipped (no longer type-rejected);
+  `timedelta` and containers still always raise
+- Validation-only metadata flags (`strip_whitespace`, `allow_inf_nan`, …) are
+  ignored when extracting constraints
+- `pattern` values from `re.Pattern` are normalized to strings in IR
+- Invalid `column_map` entries raise instead of falling through to table columns
+
+### Fixed
+
+- Reject `multiple_of` on `date` / `datetime` / `time` (previously emitted
+  nonsensical modulo SQL)
+- Module-level `sqlrules.compile(..., on_unsupported="warn")` now attributes
+  warnings to the caller, not `compiler.py`
+- `compile_model` clears stale diagnostics from prior binds
+
 ## [0.1.0] - 2026-07-10
 
 ### Added
@@ -48,4 +84,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Docs clarify that `on_unsupported` does not soften unsupported types;
   plugin / two-phase compile designs are marked as future
 
+[0.2.0]: https://github.com/eddiethedean/sqlrules/releases/tag/v0.2.0
 [0.1.0]: https://github.com/eddiethedean/sqlrules/releases/tag/v0.1.0

{sqlrules-0.1.0 → sqlrules-0.2.0}/CONTRIBUTING.md

@@ -23,11 +23,15 @@ pre-commit install
 
 ```bash
 ruff check .
-ruff format .
+ruff format --check .
 mypy src/sqlrules
 pytest
+python -m build && twine check dist/*
 ```
 
+CI also verifies `pyproject.toml` / `__version__` sync and that the built
+wheel imports cleanly.
+
 ## Pull requests
 
 - Keep changes focused.
@@ -36,17 +40,17 @@ pytest
 
 ## Releasing
 
-0.1.x releases are published to PyPI by pushing a version tag. Before tagging:
+Releases are published to PyPI by pushing a version tag. Before tagging:
 
 1. Confirm `pyproject.toml` and `sqlrules.__version__` match the changelog.
 2. Run the full check suite (`ruff`, `mypy`, `pytest`).
 3. Ensure CI is green on `main`.
 
-Then create and push the tag (example for 0.1.0):
+Then create and push the tag (example for 0.2.0):
 
 ```bash
-git tag -a v0.1.0 -m "sqlrules 0.1.0"
-git push origin v0.1.0
+git tag -a v0.2.0 -m "sqlrules 0.2.0"
+git push origin v0.2.0
 ```
 
 The [release workflow](.github/workflows/release.yml) runs CI, builds the

{sqlrules-0.1.0 → sqlrules-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlrules
-Version: 0.1.0
+Version: 0.2.0
 Summary: Compile constrained Pydantic models into SQLAlchemy WHERE-rule dictionaries.
 Project-URL: Homepage, https://github.com/eddiethedean/sqlrules
 Project-URL: Documentation, https://github.com/eddiethedean/sqlrules#readme
@@ -29,11 +29,13 @@ Requires-Dist: annotated-types>=0.6
 Requires-Dist: pydantic>=2.0
 Requires-Dist: sqlalchemy>=2.0
 Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pre-commit>=3.7; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # SQLRules
@@ -79,7 +81,7 @@ pip install sqlrules
 
 Requires Python 3.10+, Pydantic v2, and SQLAlchemy 2.x.
 
-## Supported constraints (0.1)
+## Supported constraints (0.2)
 
 | Constraint | SQLAlchemy expression |
 |---|---|
@@ -89,6 +91,8 @@ Requires Python 3.10+, Pydantic v2, and SQLAlchemy 2.x.
 | `Literal[...]` | `column.in_(...)` |
 | `Enum` | `column.in_(...)` |
 
+`pattern` is extracted into IR but has no portable core translator.
+
 Unsupported constraints raise `UnsupportedConstraintError` by default.
 Use `on_unsupported="warn"` or `"ignore"` to change that policy for unknown
 constraint operators (unsupported types always raise).
@@ -96,7 +100,7 @@ constraint operators (unsupported types always raise).
 ## Public API
 
 ```python
-sqlrules.compile(model, table, *, column_map=None, on_unsupported="raise")
+sqlrules.compile(model, table, *, column_map=None, on_unsupported="raise", cache=True)
 sqlrules.where(rules)    # flatten all expressions
 sqlrules.flatten(rules)  # alias of where()
 ```
@@ -120,6 +124,7 @@ pip install -e ".[dev]"
 pytest
 ruff check .
 mypy src/sqlrules
+python -m benchmarks.bench_compile
 ```
 
 ## License

{sqlrules-0.1.0 → sqlrules-0.2.0}/README.md

@@ -41,7 +41,7 @@ pip install sqlrules
 
 Requires Python 3.10+, Pydantic v2, and SQLAlchemy 2.x.
 
-## Supported constraints (0.1)
+## Supported constraints (0.2)
 
 | Constraint | SQLAlchemy expression |
 |---|---|
@@ -51,6 +51,8 @@ Requires Python 3.10+, Pydantic v2, and SQLAlchemy 2.x.
 | `Literal[...]` | `column.in_(...)` |
 | `Enum` | `column.in_(...)` |
 
+`pattern` is extracted into IR but has no portable core translator.
+
 Unsupported constraints raise `UnsupportedConstraintError` by default.
 Use `on_unsupported="warn"` or `"ignore"` to change that policy for unknown
 constraint operators (unsupported types always raise).
@@ -58,7 +60,7 @@ constraint operators (unsupported types always raise).
 ## Public API
 
 ```python
-sqlrules.compile(model, table, *, column_map=None, on_unsupported="raise")
+sqlrules.compile(model, table, *, column_map=None, on_unsupported="raise", cache=True)
 sqlrules.where(rules)    # flatten all expressions
 sqlrules.flatten(rules)  # alias of where()
 ```
@@ -82,6 +84,7 @@ pip install -e ".[dev]"
 pytest
 ruff check .
 mypy src/sqlrules
+python -m benchmarks.bench_compile
 ```
 
 ## License

sqlrules-0.2.0/benchmarks/__init__.py

@@ -0,0 +1 @@
+"""Benchmark package for local performance checks (not a CI gate)."""

sqlrules-0.2.0/benchmarks/bench_compile.py

@@ -0,0 +1,70 @@
+"""Compile benchmarks for small / medium / large models (cold vs warm cache).
+
+Illustrative targets from docs/PERFORMANCE.md (not enforced):
+  Small  (< 5 fields)   < 0.5 ms
+  Medium (~25 fields)   < 2 ms
+  Large  (100+ fields)  < 10 ms
+
+Run::
+
+    python -m benchmarks.bench_compile
+"""
+
+from __future__ import annotations
+
+import timeit
+from typing import Annotated, Any
+
+from pydantic import BaseModel, Field, create_model
+from sqlalchemy import Column, Integer, MetaData, String, Table
+
+import sqlrules
+from sqlrules.cache import ModelIRCache
+
+
+def _build_model(n_fields: int) -> type[BaseModel]:
+    fields: dict[str, Any] = {}
+    for i in range(n_fields):
+        if i % 2 == 0:
+            fields[f"n{i}"] = (Annotated[int, Field(ge=0, le=100)], ...)
+        else:
+            fields[f"s{i}"] = (Annotated[str, Field(min_length=1, max_length=50)], ...)
+    return create_model(f"Filter{n_fields}", **fields)  # type: ignore[call-overload]
+
+
+def _build_table(n_fields: int) -> Table:
+    metadata = MetaData()
+    columns: list[Column[Any]] = []
+    for i in range(n_fields):
+        if i % 2 == 0:
+            columns.append(Column(f"n{i}", Integer))
+        else:
+            columns.append(Column(f"s{i}", String))
+    return Table(f"t{n_fields}", metadata, *columns)
+
+
+def _bench(label: str, model: type[BaseModel], table: Table, *, repeats: int = 50) -> None:
+    cache = ModelIRCache()
+    compiler = sqlrules.Compiler(cache=True, model_cache=cache)
+
+    # Cold: empty cache
+    cache.clear()
+    cold = timeit.timeit(lambda: compiler.compile(model, table), number=1)
+
+    # Warm: IR already cached
+    warm = min(timeit.repeat(lambda: compiler.compile(model, table), number=1, repeat=repeats))
+
+    print(f"{label:12} cold={cold * 1000:8.3f} ms  warm={warm * 1000:8.3f} ms")
+
+
+def main() -> None:
+    print("SQLRules compile benchmarks (cache cold vs warm)")
+    print("-" * 56)
+    for size, n in (("small", 5), ("medium", 25), ("large", 100)):
+        model = _build_model(n)
+        table = _build_table(n)
+        _bench(f"{size} ({n})", model, table)
+
+
+if __name__ == "__main__":
+    main()

{sqlrules-0.1.0 → sqlrules-0.2.0}/docs/API.md

@@ -11,6 +11,7 @@ sqlrules.compile(
     *,
     column_map=None,
     on_unsupported="raise",
+    cache=True,
 ) -> dict[str, list[ColumnElement[bool]]]
 ```
 
@@ -20,8 +21,9 @@ Compile a constrained Pydantic model into a field-keyed rule dictionary.
 |---|---|
 | `model` | Pydantic `BaseModel` subclass |
 | `table` | SQLAlchemy `Table`, alias, ORM class, or object with `.c` |
-| `column_map` | Optional explicit `field_name` or alias → column mapping |
+| `column_map` | Optional explicit `field_name` or alias → column mapping. If a key matches but the value is not a column, raises `MissingColumnError` (no fallthrough). |
 | `on_unsupported` | `"raise"` (default), `"warn"`, or `"ignore"` for unknown **operators** only |
+| `cache` | Cache Phase-1 model IR (default `True`) |
 
 Rule dictionary keys are always the Python field names. String field aliases
 (`alias`, `validation_alias`, `serialization_alias`) are used only for column
@@ -44,12 +46,32 @@ Flatten a rule dictionary into a single list of expressions suitable for
 ## `Compiler`
 
 ```python
-compiler = sqlrules.Compiler(on_unsupported="raise", registry=None)
+compiler = sqlrules.Compiler(
+    on_unsupported="raise",
+    registry=None,
+    cache=True,
+    model_cache=None,  # optional shared ModelIRCache; default is process-wide
+)
 rules = compiler.compile(model, table, column_map=None)
+
+# Two-phase (advanced):
+model_ir = compiler.compile_model(model)  # also clears diagnostics
+rules = compiler.bind(model_ir, table, column_map=None)
+
+# Diagnostics from the last compile_model / compile / bind:
+compiler.diagnostics
 ```
 
-Reusable compiler instance with a fixed unsupported-constraint policy and
-optional custom translator registry.
+Reusable compiler instance with a fixed unsupported-constraint policy,
+optional custom translator registry, and optional Phase-1 metadata cache.
+
+`compile_model` / `bind` separate static IR extraction from table binding so
+the same `ModelIR` can be reused across tables.
+
+**Concurrency:** do not call `compile` / `bind` / `compile_model` concurrently
+on the same `Compiler` instance (diagnostics are per-instance and not locked).
+The shared Phase-1 IR cache is thread-safe for concurrent reads/writes across
+instances.
 
 ## Other exports
 
@@ -57,7 +79,11 @@ Also exported for advanced use and typing:
 
 - `__version__`
 - `SQLRulesWarning`
-- `CompilationContext`, `Constraint`, `FieldDescriptor` (IR helpers)
+- `CompilationContext`, `Constraint`, `FieldDescriptor`, `FieldIR`, `ModelIR`,
+  `Diagnostic` (IR helpers)
+
+`DiagnosticsCollector` and `ModelIRCache` are internal (import from
+`sqlrules.ir` / `sqlrules.cache` only if you accept instability).
 
 ## Exceptions
 
@@ -67,9 +93,9 @@ All public exceptions inherit from `SQLRulesError`:
 - `MissingColumnError`
 - `UnsupportedConstraintError`
 - `TranslatorError`
-- `InvalidTranslatorError` (reserved; not raised in 0.1)
+- `InvalidTranslatorError` (reserved; not raised in 0.2)
 - `RegistryError`
 - `ConfigurationError`
-- `InternalCompilerError` (reserved; not raised in 0.1)
+- `InternalCompilerError` (reserved; not raised in 0.2)
 
 See [ERRORS.md](ERRORS.md) for details.

sqlrules-0.2.0/docs/ARCHITECTURE.md

@@ -0,0 +1,33 @@
+# Architecture
+
+```text
+Pydantic Model
+    ↓
+Metadata Reader  (cached ModelIR)
+    ↓
+Constraint IR
+    ↓
+Column Binding
+    ↓
+SQLAlchemy Compiler
+    ↓
+Rule Dictionary (+ diagnostics)
+```
+
+SQLRules is a pure compiler pipeline with two phases:
+
+**Phase 1 — static model IR**
+
+1. **Inspect** the Pydantic model and preserve field declaration order.
+2. **Extract** supported constraints into a dialect-neutral IR.
+3. **Cache** immutable `ModelIR` keyed by model class (optional).
+
+**Phase 2 — bind and translate**
+
+4. **Resolve** each constrained field to a SQLAlchemy column.
+5. **Translate** each IR constraint into one SQLAlchemy expression.
+6. **Assemble** expressions into `dict[str, list[ColumnElement[bool]]]`.
+
+The compiler never connects to a database, executes SQL, or renders SQL
+strings. See [COMPILER.md](COMPILER.md) and [INTERNAL_API.md](INTERNAL_API.md)
+for stage-level detail.

{sqlrules-0.1.0 → sqlrules-0.2.0}/docs/COMPILER.md

@@ -37,13 +37,14 @@ Rule Dictionary
 
 ## Stage 1 -- Model Introspection
 
-Inputs: - Pydantic BaseModel subclass - SQLAlchemy Table, Alias, ORM
-class, or column mapping
+Inputs: - Pydantic BaseModel subclass
 
 Responsibilities: - Validate the input model. - Enumerate model
 fields. - Preserve declaration order.
 
-Output: - Iterable of field definitions.
+Output: - Iterable of field definitions (later cached as `ModelIR`).
+
+Table / column binding happens in Phase 2 (`bind`), not Stage 1.
 
 ## Stage 2 -- Field Extraction
 
@@ -64,6 +65,9 @@ Read only constraints that have deterministic SQL equivalents.
 Examples: - gt - ge - lt - le - multiple_of - min_length - max_length -
 Literal - Enum
 
+`pattern` is normalized into IR (`operator="pattern"`) but has no
+portable core translator.
+
 Constraints without SQL equivalents are delegated to the
 unsupported-constraint policy.
 
@@ -130,16 +134,23 @@ Errors include:
 
 ## Caching
 
-Future versions may cache compiled metadata using the model type as the
-cache key. Translation remains deterministic.
+Phase-1 model IR is cached in-process by model class (default on).
+Cached values are immutable field descriptors and constraints — never
+SQLAlchemy column objects. Disable with `cache=False`.
+
+Translation remains deterministic.
 
 ## Extension Points
 
+Available today:
+
+-   Inject a custom `TranslatorRegistry` via `Compiler(registry=...)`
+    (including a `pattern` translator).
+
 Future plugin hooks:
 
--   Register custom translators.
--   Register dialect-specific translators.
--   Override built-in mappings.
+-   Register dialect-specific translators via a plugin API.
+-   Override built-in mappings through versioned plugins.
 -   Add new IR transforms.
 
 ## Design Principles

{sqlrules-0.1.0 → sqlrules-0.2.0}/docs/CONSTRAINTS.md

@@ -11,10 +11,21 @@
 | `multiple_of` | `column % value == 0` |
 | `Literal[...]` | `column.in_(...)` |
 | `Enum` | `column.in_(member values)` |
+| `pattern` | IR only in 0.2 (no portable core translator) |
 
 Accepted input forms for the same semantics include `Field(...)`,
 `annotated_types` primitives, `Interval`, `Len`, `conint`/`constr`, and
-`StringConstraints` (length attributes only).
+`StringConstraints` (length attributes; `pattern` becomes IR).
 
 Constraints without a deterministic SQL equivalent are rejected by default.
 See [TYPE_SUPPORT.md](TYPE_SUPPORT.md) and [ERRORS.md](ERRORS.md).
+
+To translate `pattern`, register a custom translator:
+
+```python
+from sqlrules.translators import default_registry
+
+registry = default_registry()
+registry.register("pattern", lambda c, col, ctx: col.op("~")(c.value))
+compiler = sqlrules.Compiler(registry=registry)
+```

{sqlrules-0.1.0 → sqlrules-0.2.0}/docs/DESIGN_DECISIONS.md

@@ -235,8 +235,9 @@ SQL Server, or Oracle plugins.
 
 ## Decision
 
-SQLRules 0.1 does **not** ship a plugin API. Customization today is limited
-to injecting a `TranslatorRegistry` into `Compiler(registry=...)`.
+SQLRules 0.2 does **not** ship a plugin API. Customization today is limited
+to injecting a `TranslatorRegistry` into `Compiler(registry=...)` (for
+example a custom `pattern` translator).
 
 A future release may add explicit plugin registration (for example
 `Compiler(plugins=[...])`) without automatic discovery.
@@ -248,7 +249,7 @@ reproducibility, and keeps the compiler deterministic.
 
 ## Consequences
 
-Do not treat plugin examples in design docs as available in 0.1. See
+Do not treat plugin examples in design docs as available in 0.2. See
 [PLUGIN_SYSTEM.md](PLUGIN_SYSTEM.md) for the planned design.
 
 ------------------------------------------------------------------------
@@ -297,21 +298,19 @@ early.
 
 ------------------------------------------------------------------------
 
-# Decision 12: Two-Phase Compilation (Future)
+# Decision 12: Two-Phase Compilation
 
 ## Decision
 
-SQLRules should eventually separate static model compilation from table
-binding. **0.1 compiles in a single pass** (inspect → extract → resolve →
-translate).
+SQLRules separates static model compilation from table binding.
 
-## Planned Phase 1: Static Compilation
+## Phase 1: Static Compilation
 
 - inspect Pydantic model
 - extract constraints
-- build IR
+- build `ModelIR` (cached by default)
 
-## Planned Phase 2: Binding
+## Phase 2: Binding
 
 - resolve SQLAlchemy columns
 - translate IR to expressions
@@ -323,7 +322,8 @@ aliases, ORM models, or column maps.
 
 ## Consequences
 
-This supports better performance and cleaner architecture.
+`Compiler.compile_model` / `Compiler.bind` expose the phases.
+`sqlrules.compile(...)` remains the one-shot public API.
 
 ------------------------------------------------------------------------
 
@@ -438,12 +438,12 @@ This may improve ergonomics while preserving dictionary output.
 
 ## Should Regex Be Core or Dialect Plugin?
 
-Regex support varies by database.
+**Decided for 0.2:**
 
-Likely answer:
-
--   IR support in core
--   translator support in dialect plugins
+- IR support in core (`Constraint(operator="pattern", ...)`)
+- No portable core translator
+- Translator support via custom `TranslatorRegistry` today, dialect
+  plugins in 0.3+
 
 ------------------------------------------------------------------------
 

{sqlrules-0.1.0 → sqlrules-0.2.0}/docs/DIALECT_SUPPORT.md

@@ -31,7 +31,7 @@ compiler deterministic.
 
 # Planned Dialects
 
-0.1 emits portable SQLAlchemy Core expressions. The table below describes
+Core emits portable SQLAlchemy Core expressions. The table below describes
 **intended** dialect posture, not a certified multi-backend test matrix.
 
   Dialect             Status        Notes

{sqlrules-0.1.0 → sqlrules-0.2.0}/docs/ERRORS.md

@@ -13,6 +13,7 @@ Goals:
 - Helpful error messages
 - Deterministic behavior
 - Configurable handling for unsupported **constraint operators**
+- Structured diagnostics for skipped constraints
 
 ------------------------------------------------------------------------
 
@@ -24,10 +25,10 @@ SQLRulesError
 ├── MissingColumnError
 ├── UnsupportedConstraintError
 ├── TranslatorError
-├── InvalidTranslatorError   (reserved in 0.1)
+├── InvalidTranslatorError   (reserved in 0.2)
 ├── RegistryError
 ├── ConfigurationError
-└── InternalCompilerError    (reserved in 0.1)
+└── InternalCompilerError    (reserved in 0.2)
 ```
 
 All public exceptions inherit from `SQLRulesError`.
@@ -66,15 +67,15 @@ an unsupported type, or an invalid operator/type combination.
 
 Examples:
 
-- `pattern`, `max_digits`, `decimal_places`
+- `pattern` (no core translator), `max_digits`, `decimal_places`
 - custom validators / `Strict`
-- unsupported types (`UUID`, containers, `time`, `timedelta`)
+- unsupported types (containers, `timedelta`)
 - `multiple_of <= 0`
 - length constraints on non-`str` fields
 
 Example:
 
-    Field 'name': constraint 'pattern' is not supported by SQLRules 0.1.
+    Field 'name': constraint 'pattern' is not supported by SQLRules.
     Remove the constraint, or set on_unsupported='warn'/'ignore'.
 
 ------------------------------------------------------------------------
@@ -89,7 +90,7 @@ expression (unexpected SQLAlchemy errors wrapped by the registry).
 # InvalidTranslatorError
 
 Reserved for future validation of custom translators. Not raised by the
-0.1 compiler path.
+0.2 compiler path.
 
 ------------------------------------------------------------------------
 
@@ -109,13 +110,13 @@ Missing operators raise `UnsupportedConstraintError`, not `RegistryError`.
 
 Raised when compiler configuration is inconsistent.
 
-In 0.1 this is raised for an invalid `on_unsupported` mode only.
+In 0.2 this is raised for an invalid `on_unsupported` mode only.
 
 ------------------------------------------------------------------------
 
 # InternalCompilerError
 
-Reserved for unexpected internal failures. Not raised by the 0.1
+Reserved for unexpected internal failures. Not raised by the 0.2
 compiler path.
 
 ------------------------------------------------------------------------
@@ -131,16 +132,39 @@ Immediately raises `UnsupportedConstraintError`.
 
 ## warn
 
-Emits a `SQLRulesWarning` and skips the constraint.
+Emits a `SQLRulesWarning`, records a `Diagnostic`, and skips the
+constraint.
 
 ## ignore
 
-Silently skips unsupported constraints.
+Records a `Diagnostic` and silently skips unsupported constraints.
 
 Unsupported **types** always raise, regardless of `on_unsupported`.
 
 ------------------------------------------------------------------------
 
+# Structured Diagnostics
+
+After `compile` / `bind` / `compile_model`, inspect skipped constraints:
+
+```python
+compiler = sqlrules.Compiler(on_unsupported="warn")
+rules = compiler.compile(Model, table)
+for diag in compiler.diagnostics:
+    print(diag.severity, diag.field, diag.operator, diag.message)
+```
+
+`Diagnostic` fields: `severity` (`"warning"` | `"info"`), `field`,
+`operator`, `value`, `message`.
+
+`compile_model` clears diagnostics. Diagnostics are separate from
+exceptions and do not change the rules dict return type.
+
+Do not call `compile` / `bind` concurrently on the same `Compiler`
+instance; diagnostics collection is not locked.
+
+------------------------------------------------------------------------
+
 # Error Message Guidelines
 
 Every public exception should include:
@@ -150,17 +174,13 @@ Every public exception should include:
 - offending value (when applicable)
 - suggested resolution
 
-Example:
-
-    Field 'age': constraint 'between' is not supported by SQLRules 0.1.
-
 ------------------------------------------------------------------------
 
 # Logging
 
 SQLRules does not log by default.
 
-Applications decide how to handle exceptions and warnings.
+Applications decide how to handle exceptions, warnings, and diagnostics.
 
 ------------------------------------------------------------------------