pyrsql 0.0.2__tar.gz → 0.0.4__tar.gz

{pyrsql-0.0.2 → pyrsql-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyrsql
-Version: 0.0.2
+Version: 0.0.4
 Summary: Compiler-oriented RSQL query engine for safe, typed, and extensible Python ORM-backed APIs.
 Keywords: rsql,orm,filter,pagination,sort,sqlalchemy,fastapi,rest
 License-Expression: MIT
@@ -14,12 +14,12 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Free Threading
 Classifier: Framework :: FastAPI
 Classifier: Topic :: Database
 Classifier: Topic :: Software Development :: Compilers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
-Requires-Dist: ciso8601>=2.3,<3.0
 Requires-Dist: msgspec>=0.18,<1.0
 Requires-Dist: typing-extensions>=4.10.0 ; python_full_version < '3.11'
 Requires-Dist: fastapi>=0.110,<1.0 ; extra == 'fastapi'
@@ -38,13 +38,18 @@ Description-Content-Type: text/markdown
 A compiler-oriented RSQL query engine for safe, typed, and extensible
 filtering, sorting, and pagination in Python APIs.
 
-[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue?logo=python)](https://pypi.org/project/pyrsql/)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14%20%7C%203.14t-blue?logo=python)](https://pypi.org/project/pyrsql/)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
 pyrsql compiles RSQL query strings into ORM-specific statement objects
-through a language frontend, semantic binder, logical IR, and pluggable
-backend lowering - making it easy to expose complex query capabilities in
-your API without coupling to a specific ORM or framework.
+through a language frontend, semantic binding, and pluggable backend
+lowering - making it easy to expose complex query capabilities in your API
+without coupling to a specific ORM or framework.
+
+For FastAPI applications using SQLAlchemy, the recommended entry point is
+`FastAPISQLAlchemyIntegration`. It provides route-ready dependencies and
+declarative resources; the lower-level query, adapter, and ORM APIs remain
+available when more control is needed.
 
 **Current backends:** SQLAlchemy 2.0  
 **Current framework adapters:** FastAPI  
@@ -53,9 +58,10 @@ your API without coupling to a specific ORM or framework.
 ## Why pyrsql?
 
 Most API filtering libraries are tightly coupled to one ORM or one framework.
-pyrsql is built as a **compiler pipeline** - parsing, semantic analysis, and
-IR lowering are separate stages. Adding a new ORM backend means implementing
-one interface (`ORM`), not rewriting the parser or query language.
+pyrsql is built as a **compiler pipeline**. Parsing, semantic analysis, and
+backend lowering are separate stages. Adding a new ORM backend means
+implementing one interface (`ORM`), not rewriting the parser or query
+language.
 
 - **ORM-neutral core** - `Query`, `Sort`, `PageRequest` have zero ORM dependencies
 - **Pluggable backends** - implement `compile_query` / `compile_sort` /
@@ -64,13 +70,49 @@ one interface (`ORM`), not rewriting the parser or query language.
 - **Custom operators** - define your own RSQL operators with per-ORM lowering
 - **Field policies** - whitelist, blacklist, aliases at global and per-model level
 - **Type-safe** - strict mypy, Google-style docstrings, immutable value objects
+- **Performance-oriented internals** - immutable `msgspec` models across the
+  core pipeline and configuration objects
+- **Security-oriented request handling** - parser/sort limits, structural
+  allowlists/blocklists, sanitized FastAPI error payloads
 
 ## Quickstart
 
 ```bash
-pip install pyrsql[sqlalchemy]
+pip install pyrsql[fastapi,sqlalchemy]
 ```
 
+```python
+from typing import Annotated, Any
+
+from fastapi import Depends, FastAPI
+
+from pyrsql.integrations.fastapi import FastAPISQLAlchemyIntegration
+
+app = FastAPI()
+integration = FastAPISQLAlchemyIntegration()
+users = integration.resource(
+    User,
+    filterable_fields={"id", "name"},
+    sortable_fields={"name"},
+    default_sort="name,asc",
+    max_page_size=100,
+)
+
+@app.get("/users")
+def list_users(
+    stmt: Annotated[Any, Depends(users.select_dependency())],
+):
+    return {"sql": str(stmt)}
+```
+
+Clients can now use `filter`, `sort`, `page`, and `size` query parameters.
+See [FastAPI + SQLAlchemy](https://wskr00.github.io/pyrsql/usage/fastapi-sqlalchemy/)
+for count, pagination, custom base statements, error behavior, and async use.
+
+### Lower-level SQLAlchemy API
+
+Use the direct API when you do not need a FastAPI route dependency:
+
 ```python
 import pyrsql
 from sqlalchemy import select
@@ -79,13 +121,13 @@ from pyrsql.orms.sqlalchemy import SQLAlchemyORM
 orm = SQLAlchemyORM()
 stmt = select(User)
 
-# Filter: name equals "demo", company name contains "acme"
-stmt = pyrsql.parse("name==demo;company.name==acme*").apply(stmt, User, orm=orm)
+stmt = pyrsql.parse("name==demo;company.name==acme*").apply(
+    stmt,
+    User,
+    orm=orm,
+)
 
-# Sort: by name ascending, then company name descending
 stmt = pyrsql.Sort.parse("name,asc;company.name,desc").apply(stmt, User, orm=orm)
-
-# Paginate: page 0, 25 items per page
 stmt = pyrsql.PageRequest.of(0, 25).apply(stmt, User, orm=orm)
 ```
 
@@ -163,6 +205,9 @@ options = QueryOptions(join_hints={"User.company": JoinHint.LEFT})
 
 ### FastAPI Integration
 
+Use this adapter directly when you need only parsed `RequestCriteria`; for
+SQLAlchemy routes, prefer the integration below.
+
 ```python
 from fastapi import Depends, FastAPI
 from pyrsql.adapters.fastapi import criteria_dependency
@@ -176,10 +221,11 @@ def list_items(criteria = Depends(dependency)):
 ```
 
 - Auto-extracts `filter`, `sort`, `page`, `size` from query params
-- `HTTP 422` with structured diagnostics on parse/semantic errors
+- Structured `HTTP 400` parse errors and `HTTP 422` semantic errors
 - OpenAPI examples from configuration
 - One-based paging support
 - Custom query parameter names
+- Optional repeated sort parameters through `SortParameterFormat.REPEATED`
 
 ### FastAPI + SQLAlchemy Integration
 
@@ -194,8 +240,17 @@ def list_users(stmt = Depends(integration.select_dependency(User))):
 ```
 
 - `select_dependency`, `count_select_dependency`, `paginated_select_dependency`
-- Declarative `resource()` with auto-generated OpenAPI examples
+- Declarative `resource()` with auto-generated OpenAPI examples and field policies
 - `applier_dependency` for custom base statements
+- Compatible with both sync `Session` and async `AsyncSession` execution
+- FastAPI parse and page-validation failures become structured `HTTP 400` payloads
+- FastAPI semantic and backend integration failures become structured `HTTP 422` payloads
+
+### Concurrency and Validation
+
+- Shared base-select and ORM metadata caches are protected for free-threaded execution
+- Async support is validated for adapter, ORM, and integration flows
+- Dedicated async, free-threaded, and security test suites validate these flows
 
 ## Documentation
 
@@ -204,12 +259,13 @@ Full documentation at **[wskr00.github.io/pyrsql](https://wskr00.github.io/pyrsq
 | Section | Description |
 |---------|-------------|
 | [Quickstart](https://wskr00.github.io/pyrsql/quickstart/) | One-minute primer |
-| [Usage](https://wskr00.github.io/pyrsql/usage/query/) | Filter, sort, page, JSON, FastAPI, custom predicates |
+| [Usage](https://wskr00.github.io/pyrsql/usage/query/) | Filter, sort, page, JSON, FastAPI, async flows, custom predicates |
 | [API Reference](https://wskr00.github.io/pyrsql/reference/api/) | Auto-generated from docstrings |
 | [Operators](https://wskr00.github.io/pyrsql/reference/operators/) | Complete operator table |
 | [Options](https://wskr00.github.io/pyrsql/reference/options/) | QueryOptions, SortOptions, JSONOptions |
 | [Architecture](https://wskr00.github.io/pyrsql/explanation/architecture/) | Pipeline, modules, design |
 | [Extensibility](https://wskr00.github.io/pyrsql/explanation/extensibility/) | Adding backends and adapters |
+| [Testing](https://wskr00.github.io/pyrsql/testing/) | Test layers, async, security, free-threaded validation |
 | [Contributing](https://wskr00.github.io/pyrsql/contributing/) | Setup, workflow, standards |
 
 ## Development Principles

{pyrsql-0.0.2 → pyrsql-0.0.4}/README.md

@@ -3,13 +3,18 @@
 A compiler-oriented RSQL query engine for safe, typed, and extensible
 filtering, sorting, and pagination in Python APIs.
 
-[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue?logo=python)](https://pypi.org/project/pyrsql/)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14%20%7C%203.14t-blue?logo=python)](https://pypi.org/project/pyrsql/)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
 pyrsql compiles RSQL query strings into ORM-specific statement objects
-through a language frontend, semantic binder, logical IR, and pluggable
-backend lowering - making it easy to expose complex query capabilities in
-your API without coupling to a specific ORM or framework.
+through a language frontend, semantic binding, and pluggable backend
+lowering - making it easy to expose complex query capabilities in your API
+without coupling to a specific ORM or framework.
+
+For FastAPI applications using SQLAlchemy, the recommended entry point is
+`FastAPISQLAlchemyIntegration`. It provides route-ready dependencies and
+declarative resources; the lower-level query, adapter, and ORM APIs remain
+available when more control is needed.
 
 **Current backends:** SQLAlchemy 2.0  
 **Current framework adapters:** FastAPI  
@@ -18,9 +23,10 @@ your API without coupling to a specific ORM or framework.
 ## Why pyrsql?
 
 Most API filtering libraries are tightly coupled to one ORM or one framework.
-pyrsql is built as a **compiler pipeline** - parsing, semantic analysis, and
-IR lowering are separate stages. Adding a new ORM backend means implementing
-one interface (`ORM`), not rewriting the parser or query language.
+pyrsql is built as a **compiler pipeline**. Parsing, semantic analysis, and
+backend lowering are separate stages. Adding a new ORM backend means
+implementing one interface (`ORM`), not rewriting the parser or query
+language.
 
 - **ORM-neutral core** - `Query`, `Sort`, `PageRequest` have zero ORM dependencies
 - **Pluggable backends** - implement `compile_query` / `compile_sort` /
@@ -29,13 +35,49 @@ one interface (`ORM`), not rewriting the parser or query language.
 - **Custom operators** - define your own RSQL operators with per-ORM lowering
 - **Field policies** - whitelist, blacklist, aliases at global and per-model level
 - **Type-safe** - strict mypy, Google-style docstrings, immutable value objects
+- **Performance-oriented internals** - immutable `msgspec` models across the
+  core pipeline and configuration objects
+- **Security-oriented request handling** - parser/sort limits, structural
+  allowlists/blocklists, sanitized FastAPI error payloads
 
 ## Quickstart
 
 ```bash
-pip install pyrsql[sqlalchemy]
+pip install pyrsql[fastapi,sqlalchemy]
 ```
 
+```python
+from typing import Annotated, Any
+
+from fastapi import Depends, FastAPI
+
+from pyrsql.integrations.fastapi import FastAPISQLAlchemyIntegration
+
+app = FastAPI()
+integration = FastAPISQLAlchemyIntegration()
+users = integration.resource(
+    User,
+    filterable_fields={"id", "name"},
+    sortable_fields={"name"},
+    default_sort="name,asc",
+    max_page_size=100,
+)
+
+@app.get("/users")
+def list_users(
+    stmt: Annotated[Any, Depends(users.select_dependency())],
+):
+    return {"sql": str(stmt)}
+```
+
+Clients can now use `filter`, `sort`, `page`, and `size` query parameters.
+See [FastAPI + SQLAlchemy](https://wskr00.github.io/pyrsql/usage/fastapi-sqlalchemy/)
+for count, pagination, custom base statements, error behavior, and async use.
+
+### Lower-level SQLAlchemy API
+
+Use the direct API when you do not need a FastAPI route dependency:
+
 ```python
 import pyrsql
 from sqlalchemy import select
@@ -44,13 +86,13 @@ from pyrsql.orms.sqlalchemy import SQLAlchemyORM
 orm = SQLAlchemyORM()
 stmt = select(User)
 
-# Filter: name equals "demo", company name contains "acme"
-stmt = pyrsql.parse("name==demo;company.name==acme*").apply(stmt, User, orm=orm)
+stmt = pyrsql.parse("name==demo;company.name==acme*").apply(
+    stmt,
+    User,
+    orm=orm,
+)
 
-# Sort: by name ascending, then company name descending
 stmt = pyrsql.Sort.parse("name,asc;company.name,desc").apply(stmt, User, orm=orm)
-
-# Paginate: page 0, 25 items per page
 stmt = pyrsql.PageRequest.of(0, 25).apply(stmt, User, orm=orm)
 ```
 
@@ -128,6 +170,9 @@ options = QueryOptions(join_hints={"User.company": JoinHint.LEFT})
 
 ### FastAPI Integration
 
+Use this adapter directly when you need only parsed `RequestCriteria`; for
+SQLAlchemy routes, prefer the integration below.
+
 ```python
 from fastapi import Depends, FastAPI
 from pyrsql.adapters.fastapi import criteria_dependency
@@ -141,10 +186,11 @@ def list_items(criteria = Depends(dependency)):
 ```
 
 - Auto-extracts `filter`, `sort`, `page`, `size` from query params
-- `HTTP 422` with structured diagnostics on parse/semantic errors
+- Structured `HTTP 400` parse errors and `HTTP 422` semantic errors
 - OpenAPI examples from configuration
 - One-based paging support
 - Custom query parameter names
+- Optional repeated sort parameters through `SortParameterFormat.REPEATED`
 
 ### FastAPI + SQLAlchemy Integration
 
@@ -159,8 +205,17 @@ def list_users(stmt = Depends(integration.select_dependency(User))):
 ```
 
 - `select_dependency`, `count_select_dependency`, `paginated_select_dependency`
-- Declarative `resource()` with auto-generated OpenAPI examples
+- Declarative `resource()` with auto-generated OpenAPI examples and field policies
 - `applier_dependency` for custom base statements
+- Compatible with both sync `Session` and async `AsyncSession` execution
+- FastAPI parse and page-validation failures become structured `HTTP 400` payloads
+- FastAPI semantic and backend integration failures become structured `HTTP 422` payloads
+
+### Concurrency and Validation
+
+- Shared base-select and ORM metadata caches are protected for free-threaded execution
+- Async support is validated for adapter, ORM, and integration flows
+- Dedicated async, free-threaded, and security test suites validate these flows
 
 ## Documentation
 
@@ -169,12 +224,13 @@ Full documentation at **[wskr00.github.io/pyrsql](https://wskr00.github.io/pyrsq
 | Section | Description |
 |---------|-------------|
 | [Quickstart](https://wskr00.github.io/pyrsql/quickstart/) | One-minute primer |
-| [Usage](https://wskr00.github.io/pyrsql/usage/query/) | Filter, sort, page, JSON, FastAPI, custom predicates |
+| [Usage](https://wskr00.github.io/pyrsql/usage/query/) | Filter, sort, page, JSON, FastAPI, async flows, custom predicates |
 | [API Reference](https://wskr00.github.io/pyrsql/reference/api/) | Auto-generated from docstrings |
 | [Operators](https://wskr00.github.io/pyrsql/reference/operators/) | Complete operator table |
 | [Options](https://wskr00.github.io/pyrsql/reference/options/) | QueryOptions, SortOptions, JSONOptions |
 | [Architecture](https://wskr00.github.io/pyrsql/explanation/architecture/) | Pipeline, modules, design |
 | [Extensibility](https://wskr00.github.io/pyrsql/explanation/extensibility/) | Adding backends and adapters |
+| [Testing](https://wskr00.github.io/pyrsql/testing/) | Test layers, async, security, free-threaded validation |
 | [Contributing](https://wskr00.github.io/pyrsql/contributing/) | Setup, workflow, standards |
 
 ## Development Principles

{pyrsql-0.0.2 → pyrsql-0.0.4}/docs/contributing.md

@@ -23,7 +23,7 @@ uv run pytest                # tests
 - strict mypy type checking
 - ruff for linting and formatting
 - pytest with `unit`, `integration`, `functional`, `performance` layers
-- ORM-neutral core - zero ORM imports in `pyrsql.core`, `pyrsql.ir`, `pyrsql.parsing`, `pyrsql.semantic`
+- ORM-neutral core - zero ORM imports in `pyrsql.core`, `pyrsql.parsing`, `pyrsql.semantic`, `pyrsql.sorting`
 
 ## Test layers
 

pyrsql-0.0.4/docs/explanation/architecture.md

@@ -0,0 +1,244 @@
+# pyrsql Architecture
+
+## Identity
+
+`pyrsql` is a compiler-oriented RSQL query engine. It turns RSQL-like filter
+and sort expressions into ORM-specific statement updates through a staged
+pipeline:
+
+```text
+query text
+-> parsing
+-> selector AST
+-> semantic binding
+-> backend lowering
+-> ORM-specific statement
+```
+
+The core is deliberately ORM-neutral. Adding a new backend means implementing
+the `ORM` interface, not rewriting the parser, selector grammar, or semantic
+rules.
+
+## Purpose
+
+The project is designed around four major responsibilities:
+
+- language frontend: parse text into syntax trees
+- semantic binding: resolve fields, functions, and access policies
+- backend lowering: turn validated query objects into ORM-specific statements
+- optional framework adapters and integrations: expose the core in HTTP stacks
+
+The current production backend is SQLAlchemy 2.0. The current framework
+adapter is FastAPI.
+
+## Current Pipeline
+
+More concretely, the runtime flow looks like this:
+
+```text
+RSQL string
+-> parsing AST
+-> selector nodes
+-> SemanticBinder / SortBinder
+-> Query / Sort / PageRequest application
+-> SQLAlchemyORM lowering
+-> SQLAlchemy Select
+```
+
+For pagination-only flows, `PageRequest` goes directly to backend lowering.
+
+## Module Boundaries
+
+The project is split into these main modules:
+
+- `parsing`
+- `selector`
+- `semantic`
+- `sorting`
+- `core`
+- `orms`
+- `adapters`
+- `integrations`
+- `api`
+
+### `parsing`
+
+Owns:
+
+- source spans
+- tokens
+- parser AST
+- parser limits
+- parse diagnostics and errors
+
+### `selector`
+
+Owns selector syntax only:
+
+- `FieldSelector`
+- `LiteralSelector`
+- `FunctionSelector`
+
+It does not own semantic meaning.
+
+### `semantic`
+
+Owns semantic binding:
+
+- field policy checks
+- function policy checks
+- field mapping
+- semantic diagnostics and errors
+- normalization for backend lowering
+
+### `sorting`
+
+Owns sort syntax and sort binding.
+
+### `core`
+
+Owns user-facing ORM-agnostic objects:
+
+- `Query`, `Sort`, `PageRequest`
+- `QueryOptions`, `SortOptions`
+- `FieldPolicySet`, `ProcedureAccessPolicy`
+- `CustomPredicateDefinition`
+- `ValueConverterRegistry`, `FieldValueConverterSet`
+- `JSONOptions`, `JSONSortScalarType`
+- `JSONPath`, `JSONPathComparison`
+- `JSONScalarNormalizer`, `JSONScalarValue`
+- `JoinHint`
+
+The `core/json/` package owns JSON-aware comparison models and value
+normalization, keeping JSON semantics ORM-neutral.
+
+### `orms`
+
+Owns backend lowering.
+
+Current production backend:
+
+- `orms.sqlalchemy`
+
+Its job is:
+
+- consume normalized query, sort, and page objects
+- resolve model metadata
+- coerce values
+- lower to SQLAlchemy statements
+
+It should not redo semantic interpretation already handled upstream.
+
+For PostgreSQL JSON/JSONB lowering, the current design separates:
+
+- whole-document JSON predicates
+- nested JSON path predicates
+- JSON sort extraction rules
+
+This keeps the backend close to SQLAlchemy and PostgreSQL primitives instead of
+forcing every JSON case through one generic lowering path.
+
+### `adapters`
+
+Own framework-level request and error adaptation.
+
+Current adapter:
+
+- `adapters.fastapi`
+
+It is responsible for:
+
+- extracting query params
+- building `RequestCriteria`
+- translating pyrsql failures into framework-native HTTP errors
+- adding OpenAPI metadata
+
+### `integrations`
+
+Own stack-specific orchestration across adapter + backend.
+
+Current integration:
+
+- `integrations.fastapi.sqlalchemy`
+
+It is responsible for:
+
+- request criteria application helpers
+- route-ready dependencies
+- declarative resource configuration
+- stack-specific DX
+
+### `api`
+
+Owns the smallest public helper surface:
+
+- `parse(...)`
+- `compile(...)`
+- `apply(...)`
+
+## Extensibility
+
+### Adding a new ORM backend
+
+Implement `pyrsql.orms.base.ORM`:
+
+```python
+class ORM(ABC):
+    def compile_query(self, query: Query) -> CompiledArtifact: ...
+    def compile_sort(self, sort: Sort) -> CompiledArtifact: ...
+    def compile_page_request(self, page_request: PageRequest) -> CompiledArtifact: ...
+```
+
+Each method receives one ORM-neutral core object and returns a compiled object
+with an `apply(target, model)` method.
+
+### Adding a new framework adapter
+
+Implement `pyrsql.adapters.*` to extract query parameters from requests and
+translate pyrsql failures into framework-native HTTP responses.
+
+The FastAPI adapter is the reference implementation.
+
+## Design Principles
+
+The project follows:
+
+- object-oriented design
+- SOLID
+- strong typing
+- backend-independent core semantics
+- performance-oriented data modeling
+- explicit concurrency boundaries
+
+### Practical interpretation
+
+- semantic work should happen before the ORM backend
+- ORMs should do lowering, not semantic analysis
+- adapters should do transport adaptation, not query semantics
+- integrations should provide DX, not execution frameworks
+
+## Performance Direction
+
+The project uses `msgspec` where it improves compactness and immutable data
+modeling:
+
+- diagnostics
+- parser/source structures
+- adapter and integration payloads
+- core query/sort/options/value-policy models
+
+Other performance principles:
+
+- cache repeated base statements when safe
+- avoid repeating semantic work in the ORM backend
+- keep shared cache lock scope small in concurrency-sensitive paths
+
+## Async and Free-Threaded Support
+
+These are related but separate concerns:
+
+- async support means generated SQLAlchemy statements work with both `Session`
+  and `AsyncSession`
+- free-threaded support means shared mutable caches are synchronized explicitly
+
+The core query pipeline stays synchronous and ORM-neutral in both cases.

pyrsql-0.0.4/docs/explanation/extensibility.md

@@ -0,0 +1,82 @@
+# Extensibility
+
+`pyrsql` is designed to support multiple ORM backends and framework adapters.
+The core (`pyrsql.core`, `pyrsql.parsing`, `pyrsql.semantic`,
+`pyrsql.sorting`) has zero dependencies on any ORM or framework.
+
+## Adding a new ORM backend
+
+Implement the `ORM` abstract base class:
+
+```python
+from pyrsql.core.compiler import CompiledArtifact
+from pyrsql.orms.base import ORM
+
+class MyORM(ORM):
+    def compile_query(self, query: Query) -> CompiledArtifact:
+        ...
+
+    def compile_sort(self, sort: Sort) -> CompiledArtifact:
+        ...
+
+    def compile_page_request(self, page_request: PageRequest) -> CompiledArtifact:
+        ...
+```
+
+Each `compile_*` method receives one ORM-neutral core object (`Query`, `Sort`,
+or `PageRequest`) and returns a compiled object with an `apply(target, model)`
+method.
+
+The current reference implementation is `SQLAlchemyORM` in
+`pyrsql.orms.sqlalchemy`.
+
+## Adding a new framework adapter
+
+Create a module under `pyrsql.adapters` that:
+
+1. extracts query parameters from requests
+2. builds `RequestCriteria`
+3. translates parse, semantic, and page-validation failures into
+   framework-appropriate error responses
+
+The FastAPI adapter (`pyrsql.adapters.fastapi`) is the reference:
+
+- `FastAPICriteriaConfig` holds public parameter names and defaults
+- `criteria_dependency()` returns a FastAPI dependency callable
+
+## Backend contract in detail
+
+### `CompiledArtifact`
+
+```python
+class CompiledArtifact(Protocol):
+    def apply(self, target: _TargetT, model: type[_ModelT]) -> _TargetT: ...
+```
+
+Receives an ORM-specific target and model class, then returns the modified
+target with query conditions applied.
+
+The same contract applies to query, sort, and pagination artifacts such as
+`LIMIT` and `OFFSET`.
+
+## Integration layer
+
+Adapters and ORMs can stay independent. The `integrations/` package is where
+stack-specific DX belongs.
+
+For example, `integrations.fastapi.sqlalchemy` is allowed to know both:
+
+- the FastAPI adapter contract
+- the SQLAlchemy backend contract
+
+That is the right place for:
+
+- route-ready dependencies
+- paginated statement bundles
+- OpenAPI example generation tied to SQLAlchemy model metadata
+
+## Planned backends and adapters
+
+- **Django ORM** - compile to Django `QuerySet`
+- **SQLModel** - likely reuse most SQLAlchemy lowering
+- **Flask** - request adapter for `request.args`