feat(introspection)!: the dialect owns the SQL, and capability predicates answer before adaptation

.claude/architecture.md

@@ -316,14 +316,23 @@ data at construction time. String scanning of SQL is also a classic injection su
 mismatch between the scanner's assumptions (quote states, escape rules, placeholder characters)
 and the real dialect syntax silently corrupts the statement.
 
-**The single exception — inline-literal resolution.** When a statement
-(`requires_inline_literals() == True`, trusted developer-declared DDL) renders its literal
-values inline, the dialect's `format_literal` produces **escaped, quoted atoms**; these are
-concatenated directly during formatting and never require re-scanning the assembled SQL.
-Because this exception deals with splicing raw values into SQL text, it is a **SQL-injection
-hazard by nature**: developers must be highly alert that inline content is trusted-only and
-never reachable by end users. `Literal.requires_inline_literals` / the statement-level switch
-must default to `False` (bind parameters) for exactly this reason.
+**The single exception — inline literals.** A value can be spliced into the SQL text
+instead of bound, and the call site asks for that per value:
+`Literal(dialect, value, inline=True)`. The dialect then produces **escaped, quoted atoms**
+(`inline_sql_literal`), concatenated directly during formatting; nothing re-scans the
+assembled SQL.
+
+Whether to inline is **the caller's decision, not the framework's**. Some engines reject a
+statement that carries a bind parameter in a position with no room for one, and a statement
+built for such an engine has to inline the values in those positions. That is why the switch
+lives on the literal the caller constructs: the developer knows which engine the statement
+is for, and the framework cannot infer it.
+
+The default is bind parameters (`inline=False`), because inlining is a **SQL-injection hazard
+by nature**: it splices raw values into SQL text, so inline content must be trusted-only and
+never reachable by end users. A formatter must not turn a bound value into text on its own
+initiative, and must not refuse a statement merely because it binds where an engine would
+prefer text — the caller's choice is the contract.
 
 **What happens if you break it (harm):** a scanner (e.g. walking the assembled SQL to replace
 `?` placeholders) mis-fires on placeholders that appear *inside* string literals, breaks the

.claude/code_style.md

@@ -655,9 +655,9 @@ def transaction(backend: StorageBackend):
 - [ ] Expression-dialect separation maintained
 - [ ] Expression system module organization followed
 
-### RawSQLPredicate / RawSQLExpression
+### RawSQLPredicate / RawSQL
 
-`RawSQLExpression` and `RawSQLPredicate` (`backend/expression/operators.py`) embed a raw SQL
+`RawSQL` and `RawSQLPredicate` (`backend/expression/operators.py`) embed a raw SQL
 fragment directly into the query, bypassing the typed expression building mechanism. They are
 **used internally by the core query builder** and therefore are not categorically forbidden.
 
@@ -677,7 +677,7 @@ SQL fragment strings relies on `RawSQLPredicate` under the hood.
 
 #### Security analysis
 
-- **Values are still parameterized.** `RawSQLPredicate`/`RawSQLExpression` bind parameters via
+- **Values are still parameterized.** `RawSQLPredicate`/`RawSQL` bind parameters via
   a separate params tuple, so values are always sent through placeholders and never
   naively concatenated. The SQL string itself, however, is embedded verbatim.
 - **The SQL fragment string is trusted input.** The security boundary is: the SQL structure

.claude/commands/lint.md

@@ -3,7 +3,22 @@ Run code linting with ruff
 Run code linting and formatting checks for the project.
 
 Execute the following commands:
-1. ruff check src/ - Check code style
-2. ruff format --check src/ - Check code formatting
+1. `ruff check src/` — lint only. `[tool.ruff]` selects E/F/B at line-length 120.
+2. Do NOT run `ruff format`. The project has no `[tool.ruff.format]` section, and
+   formatting is owned by black (`[tool.black]`, line-length 100) plus isort
+   (`profile = "black"`). `ruff format` would reformat at 120 and fight black.
+
+On Windows, use the wrapper, which resolves the virtualenv and locates ruff:
+
+```powershell
+./scripts/dev.ps1 lint              # ruff check src
+./scripts/dev.ps1 lint src tests    # explicit targets
+./scripts/dev.ps1 fmt               # ruff check --fix
+./scripts/dev.ps1 fmt --with-black --with-isort
+./scripts/dev.ps1 type              # mypy src ([tool.mypy] pins python_version = 3.8)
+```
+
+`ruff`, `mypy`, `black` and `isort` are not installed by default; install them with
+`uv tool install ruff mypy black isort` (or add to the virtualenv).
 
 Show any violations and suggest fixes.

.claude/commands/test.md

@@ -1,12 +1,18 @@
 Run the full test suite for rhosocial-activerecord.
 
-Before running tests, ensure PYTHONPATH is set:
-```bash
-export PYTHONPATH=src  # Linux/macOS
-# OR
-$env:PYTHONPATH="src"  # PowerShell
+Before running tests, ensure PYTHONPATH is set (note the `tests` half — it makes
+`providers/registry.py` importable; see .claude/testing.md §2):
+
+```powershell
+$env:PYTHONPATH="src;tests"   # Windows PowerShell 7
 ```
 
-Then run: pytest tests/ -v
+On Windows, prefer the wrapper, which resolves the virtualenv and sets PYTHONPATH for you:
+
+```powershell
+./scripts/dev.ps1 test              # serial (AGENTS.md iron rule 1)
+./scripts/dev.ps1 test -Parallel    # opt-in, mirrors CI: -n auto --dist=loadgroup + plugin
+./scripts/dev.ps1 collect           # import check only, no tests executed
+```
 
-Show test results and any failures. Focus on failing tests and suggest fixes.
+Show the complete unfiltered output. Do not filter with grep or truncate with head/tail.

.claude/rules/README.md

@@ -6,10 +6,13 @@ stands alone; read the one that concerns the change in front of you.
 | Rule | Covers |
 |---|---|
 | [expression-direction.md](expression-direction.md) | `expr -> format` and why the reverse direction is where injection and unreviewable inference live. What a factory signature may accept. |
+| [expression-node-design.md](expression-node-design.md) | When a grammar construct is a clause node and when it is a parameter. One expression one formatter; counting paths rather than keywords; the four parameter shapes; why a constraint clause is two levels, not a class hierarchy. |
 | [column-and-result-types.md](column-and-result-types.md) | Designing column classes; the core / backend / user layering; stating a result type the source cannot settle, and why it is a mixin rather than a keyword. |
 | [operation-contracts.md](operation-contracts.md) | What each operation promises once the ten-backend survey measured it: the string boundary refusals, the rendering-name contracts, the temporal result types, the value-layer echo, and where version gates refuse. |
 | [static-analysis.md](static-analysis.md) | Making a checker actually check: `py.typed`, a configuration that loads, and the defects that opt out of checking silently. |
 | [anti-patterns.md](anti-patterns.md) | The catalogue, with what each one cost. Read this before adding a runtime lookup, a coercion helper, or a `__getattr__`. |
+| [python-hazards.md](python-hazards.md) | Python spelling and measured surface for the organisation's language-neutral clauses on override order, reflection and enums (expression-dialect.md §11). |
+| [introspection.md](introspection.md) | The four introspection rules: nobody spells SQL; core keeps the smallest set and does not arbitrate capability; each backend completes its own semantics; each CLI introspects one connection. |
 
 Two rules decide most of the rest:
 
@@ -25,3 +28,4 @@ A third applies to the checks themselves, and it is the one most often skipped:
 afternoon — four version gates that could not say no, an argument inserted into
 the wrong call — were all in files that had been edited and not tested. Run the
 directory.
+