sqlrules 0.1.0__tar.gz → 0.3.0__tar.gz

{sqlrules-0.1.0 → sqlrules-0.3.0}/.gitignore

@@ -10,6 +10,7 @@ __pycache__/
 .coverage.*
 htmlcov/
 dist/
+dist-plugins/
 build/
 *.egg-info/
 .DS_Store

sqlrules-0.3.0/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+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.3.0] - 2026-07-10
+
+### Added
+
+- Versioned plugin API: `SQLRulesPlugin`, `PLUGIN_API_VERSION` (`"1"`),
+  and `PluginError`
+- `Compiler(plugins=..., on_conflict=..., dialect=...)` for explicit
+  plugin registration (no auto-discovery)
+- Expanded registry API: `register_constraint`, conflict policies
+  (`raise` / `replace` / `ignore`), `copy()`, `operators()`, and
+  `__contains__`
+- `InvalidTranslatorError` raised for non-callable or wrong-arity
+  translators at registration time
+- `Diagnostic.code` (e.g. `unsupported_constraint` on warn/ignore skips)
+- Optional `CompilationContext.dialect` hint (never auto-detected)
+- Plugin conformance helpers in `sqlrules.conformance`
+- Official starter dialect packages:
+  - `sqlrules-postgresql` (`pattern` → `~`)
+  - `sqlrules-sqlite` (`pattern` → `REGEXP`)
+
+### Changed
+
+- Package version bumped to 0.3.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
+
+- Public API: `compile()`, `where()`, `flatten()`, and `Compiler`
+- Constraint support: `gt`, `ge`, `lt`, `le`, `multiple_of`, `min_length`,
+  `max_length`, `Literal`, and `Enum`
+- Equivalent Pydantic forms: `Interval`, `conint`/`constr`, `Len`, and
+  `StringConstraints` (supported attributes only)
+- Fail-fast handling for unsupported metadata (`pattern`, validators,
+  decimal precision) and unsupported types (containers, UUID, time,
+  timedelta)
+- Field alias resolution when binding SQLAlchemy columns (`alias`,
+  `validation_alias`, and `serialization_alias` string forms)
+- Unsupported-constraint policies: `raise` (default), `warn`, and `ignore`
+  for unknown **operators** (unsupported types always raise)
+- Exception hierarchy rooted at `SQLRulesError`
+- Column resolution for SQLAlchemy `Table` objects, ORM attributes, and
+  explicit `column_map`
+- Documentation for the compiler, translators, errors, types, and roadmap
+
+### Fixed
+
+- Column resolution no longer treats non-column `Table` attributes (such as
+  `name` or `is_selectable`) as columns, which previously produced invalid
+  SQL or Python `bool` values in the rules dict
+- `Annotated[T, ...] | None` / `Optional[Annotated[T, ...]]` now unwraps
+  nested metadata correctly
+- String `validation_alias` / `serialization_alias` participate in column
+  binding
+- `multiple_of` values `<= 0` are rejected
+- Length constraints on non-`str` fields and numeric constraints on `str` /
+  `bool` fields are rejected
+
+### Changed
+
+- Alias candidates are preferred over the Python field name when binding
+  columns
+- Unconstrained fields are skipped and no longer require a matching column
+- Packaging URLs point at `eddiethedean/sqlrules`
+- Docs clarify that `on_unsupported` does not soften unsupported types;
+  plugin / two-phase compile designs are marked as future
+
+[0.3.0]: https://github.com/eddiethedean/sqlrules/releases/tag/v0.3.0
+[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.3.0/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing
+
+Thanks for helping improve SQLRules.
+
+## Principles
+
+- Keep the public API minimal.
+- Every feature must map directly to SQLAlchemy expressions.
+- Unsupported Pydantic features should not be approximated.
+- Prefer fail-fast behavior over silent semantic changes.
+- Update relevant docs before or alongside implementation.
+
+## Development setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pip install -e packages/sqlrules-postgresql -e packages/sqlrules-sqlite
+pre-commit install
+```
+
+## Checks
+
+```bash
+ruff check .
+ruff format --check .
+mypy src/sqlrules
+pytest tests packages/sqlrules-postgresql/tests packages/sqlrules-sqlite/tests
+python -m build && twine check dist/*
+python -m build packages/sqlrules-postgresql --outdir dist-plugins
+python -m build packages/sqlrules-sqlite --outdir dist-plugins
+twine check dist-plugins/*
+```
+
+CI also verifies `pyproject.toml` / `__version__` sync and that the built
+wheel imports cleanly.
+
+## Plugins
+
+- Declare `name`, `api_version` (`PLUGIN_API_VERSION`), and `register(registry)`.
+- Prefer `register_constraint(..., on_conflict=...)`.
+- Run `sqlrules.conformance.run_basic_conformance(plugin)`.
+- Official dialect packages live under `packages/` and should track the
+  plugin API major (`sqlrules>=0.3,<0.4` while `PLUGIN_API_VERSION == "1"`).
+
+## Pull requests
+
+- Keep changes focused.
+- Add or update tests for every constraint or error path you touch.
+- Match existing code style and documentation tone.
+
+## Releasing
+
+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.3.0):
+
+```bash
+git tag -a v0.3.0 -m "sqlrules 0.3.0"
+git push origin v0.3.0
+```
+
+The [release workflow](.github/workflows/release.yml) runs CI, verifies the
+tag matches `pyproject.toml` / `__version__`, builds the sdist/wheel, and
+publishes **core** `sqlrules` with `PYPI_API_TOKEN`.
+
+Dialect plugin packages under `packages/` are versioned independently and
+are **not** published by the core release workflow. Publish them separately
+after core `0.3.0` is on PyPI (they depend on `sqlrules>=0.3,<0.4`):
+
+```bash
+python -m build packages/sqlrules-postgresql
+python -m build packages/sqlrules-sqlite
+twine upload dist-plugins/*   # after building with --outdir dist-plugins
+```

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlrules
-Version: 0.1.0
+Version: 0.3.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,22 @@ pip install sqlrules
 
 Requires Python 3.10+, Pydantic v2, and SQLAlchemy 2.x.
 
-## Supported constraints (0.1)
+Optional dialect plugins:
+
+```bash
+pip install sqlrules-postgresql   # pattern → PostgreSQL ~
+pip install sqlrules-sqlite       # pattern → SQLite REGEXP
+```
+
+```python
+from sqlrules import Compiler
+from sqlrules_postgresql import PostgresPlugin
+
+compiler = Compiler(plugins=[PostgresPlugin()], dialect="postgresql")
+rules = compiler.compile(UserFilter, users)
+```
+
+## Supported constraints (0.3)
 
 | Constraint | SQLAlchemy expression |
 |---|---|
@@ -89,6 +106,10 @@ 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.
+Use a custom registry translator or a dialect plugin
+(`sqlrules-postgresql`, `sqlrules-sqlite`).
+
 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,9 +117,17 @@ 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()
+
+compiler = sqlrules.Compiler(
+    plugins=[...],           # optional SQLRulesPlugin instances
+    on_conflict="raise",     # raise | replace | ignore
+    dialect=None,            # optional hint for translators
+    on_unsupported="raise",
+    cache=True,
+)
 ```
 
 ## Non-goals
@@ -111,15 +140,18 @@ constraints into SQLAlchemy expressions.
 
 See [`docs/index.md`](docs/index.md) for the full documentation set,
 including the [spec](docs/SPEC.md), [API](docs/API.md),
-[architecture](docs/ARCHITECTURE.md), and [roadmap](docs/ROADMAP.md).
+[plugin system](docs/PLUGIN_SYSTEM.md), [architecture](docs/ARCHITECTURE.md),
+and [roadmap](docs/ROADMAP.md).
 
 ## Development
 
 ```bash
 pip install -e ".[dev]"
-pytest
+pip install -e packages/sqlrules-postgresql -e packages/sqlrules-sqlite
+pytest tests packages/sqlrules-postgresql/tests packages/sqlrules-sqlite/tests
 ruff check .
 mypy src/sqlrules
+python -m benchmarks.bench_compile
 ```
 
 ## License

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

@@ -41,7 +41,22 @@ pip install sqlrules
 
 Requires Python 3.10+, Pydantic v2, and SQLAlchemy 2.x.
 
-## Supported constraints (0.1)
+Optional dialect plugins:
+
+```bash
+pip install sqlrules-postgresql   # pattern → PostgreSQL ~
+pip install sqlrules-sqlite       # pattern → SQLite REGEXP
+```
+
+```python
+from sqlrules import Compiler
+from sqlrules_postgresql import PostgresPlugin
+
+compiler = Compiler(plugins=[PostgresPlugin()], dialect="postgresql")
+rules = compiler.compile(UserFilter, users)
+```
+
+## Supported constraints (0.3)
 
 | Constraint | SQLAlchemy expression |
 |---|---|
@@ -51,6 +66,10 @@ 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.
+Use a custom registry translator or a dialect plugin
+(`sqlrules-postgresql`, `sqlrules-sqlite`).
+
 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,9 +77,17 @@ 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()
+
+compiler = sqlrules.Compiler(
+    plugins=[...],           # optional SQLRulesPlugin instances
+    on_conflict="raise",     # raise | replace | ignore
+    dialect=None,            # optional hint for translators
+    on_unsupported="raise",
+    cache=True,
+)
 ```
 
 ## Non-goals
@@ -73,15 +100,18 @@ constraints into SQLAlchemy expressions.
 
 See [`docs/index.md`](docs/index.md) for the full documentation set,
 including the [spec](docs/SPEC.md), [API](docs/API.md),
-[architecture](docs/ARCHITECTURE.md), and [roadmap](docs/ROADMAP.md).
+[plugin system](docs/PLUGIN_SYSTEM.md), [architecture](docs/ARCHITECTURE.md),
+and [roadmap](docs/ROADMAP.md).
 
 ## Development
 
 ```bash
 pip install -e ".[dev]"
-pytest
+pip install -e packages/sqlrules-postgresql -e packages/sqlrules-sqlite
+pytest tests packages/sqlrules-postgresql/tests packages/sqlrules-sqlite/tests
 ruff check .
 mypy src/sqlrules
+python -m benchmarks.bench_compile
 ```
 
 ## License

sqlrules-0.3.0/benchmarks/__init__.py

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

sqlrules-0.3.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.3.0/docs/API.md

@@ -0,0 +1,138 @@
+# Public API
+
+SQLRules exposes a deliberately small public surface.
+
+## `compile`
+
+```python
+sqlrules.compile(
+    model,
+    table,
+    *,
+    column_map=None,
+    on_unsupported="raise",
+    cache=True,
+) -> dict[str, list[ColumnElement[bool]]]
+```
+
+Compile a constrained Pydantic model into a field-keyed rule dictionary.
+
+| Parameter | Description |
+|---|---|
+| `model` | Pydantic `BaseModel` subclass |
+| `table` | SQLAlchemy `Table`, alias, ORM class, or object with `.c` |
+| `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
+binding. Unconstrained fields are omitted and do not require a column.
+
+Unsupported types always raise, regardless of `on_unsupported`.
+
+Module-level `compile` does not accept plugins; use `Compiler` for extensions.
+
+## `where` / `flatten`
+
+```python
+sqlrules.where(rules) -> list[ColumnElement[bool]]
+sqlrules.flatten(rules) -> list[ColumnElement[bool]]
+```
+
+Flatten a rule dictionary into a single list of expressions suitable for
+`Query.where(*expressions)` or `select(...).where(*expressions)`.
+
+`where` and `flatten` are identical aliases.
+
+## `Compiler`
+
+```python
+compiler = sqlrules.Compiler(
+    on_unsupported="raise",
+    registry=None,
+    plugins=None,
+    on_conflict="raise",
+    dialect=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
+```
+
+| Parameter | Description |
+|---|---|
+| `plugins` | Optional sequence of `SQLRulesPlugin` objects registered at init |
+| `on_conflict` | Default conflict policy for plugin `register()`: `"raise"`, `"replace"`, or `"ignore"` |
+| `dialect` | Optional string hint stored on `CompilationContext` (never auto-detected) |
+| `registry` | Optional base `TranslatorRegistry`; copied when `plugins` is non-empty |
+
+Reusable compiler instance with a fixed unsupported-constraint policy,
+optional plugins, 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.
+
+## Plugins
+
+```python
+from sqlrules import PLUGIN_API_VERSION, Compiler
+
+class MyPlugin:
+    name = "my-plugin"
+    api_version = PLUGIN_API_VERSION
+
+    def register(self, registry):
+        registry.register_constraint(
+            "pattern",
+            lambda c, col, ctx: col.op("~")(c.value),
+            on_conflict="replace",
+        )
+
+compiler = Compiler(plugins=[MyPlugin()])
+```
+
+See [PLUGIN_SYSTEM.md](PLUGIN_SYSTEM.md). Conformance helpers live in
+`sqlrules.conformance`.
+
+## Other exports
+
+Also exported for advanced use and typing:
+
+- `__version__`
+- `PLUGIN_API_VERSION`, `SQLRulesPlugin`
+- `SQLRulesWarning`
+- `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
+
+All public exceptions inherit from `SQLRulesError`:
+
+- `InvalidModelError`
+- `MissingColumnError`
+- `UnsupportedConstraintError`
+- `TranslatorError`
+- `InvalidTranslatorError`
+- `RegistryError`
+- `ConfigurationError`
+- `PluginError`
+- `InternalCompilerError` (reserved)
+
+See [ERRORS.md](ERRORS.md) for details.

sqlrules-0.3.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.3.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,17 +134,25 @@ 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
 
-Future plugin hooks:
+Available today:
+
+-   Inject a custom `TranslatorRegistry` via `Compiler(registry=...)`
+-   Register versioned plugins via `Compiler(plugins=[...])`
+-   Override operators with `register_constraint(..., on_conflict=...)`
+-   Optional `dialect=` hint on `CompilationContext`
+
+Reserved for later:
 
--   Register custom translators.
--   Register dialect-specific translators.
--   Override built-in mappings.
--   Add new IR transforms.
+-   Compiler pass plugins
+-   Entry-point / auto-discovery
 
 ## Design Principles