ferro-orm 0.13.0__tar.gz → 0.15.0__tar.gz

{ferro_orm-0.13.0 → ferro_orm-0.15.0}/.github/workflows/ci.yml

@@ -15,33 +15,6 @@ permissions:
   contents: read
 
 jobs:
-  changed-shadow-paths:
-    name: Detect Shadow-Report Paths
-    runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request'
-    outputs:
-      requires_shadow_reports: ${{ steps.filter.outputs.shadow }}
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Detect planner/IR path changes
-        id: filter
-        uses: dorny/paths-filter@v3
-        with:
-          filters: |
-            shadow:
-              - 'src/operations.rs'
-              - 'src/query.rs'
-              - 'src/schema.rs'
-              - 'src/migrate.rs'
-              - 'src/backend.rs'
-              - 'src/connection.rs'
-              - 'src/ferro/ir/**'
-              - 'crates/ferro-schema-ir/**'
-              - 'tests/test_shadow_reports.py'
-              - 'tests/fixtures/shadow_reports/**'
-
   lint-and-format:
     name: Lint & Format (Pre-commit / Prek)
     runs-on: ubuntu-latest
@@ -152,6 +125,10 @@ jobs:
         run: |
           uv run maturin develop
 
+      - name: Static type gate (ty, scoped)
+        run: |
+          uv run ty check src/ferro/query tests/test_query_typing.py tests/test_static_contracts.py
+
       - name: Run IR vector contract harness
         run: |
           uv run pytest -v tests/test_ir_vectors_contract.py
@@ -270,64 +247,6 @@ jobs:
         run: |
           uv run pytest -v -m "backend_matrix or postgres_only" --db-backends=sqlite,postgres
 
-  test-shadow-reports-pr:
-    name: Shadow reports (touched paths)
-    runs-on: ubuntu-latest
-    needs: [changed-shadow-paths]
-    if: github.event_name == 'pull_request' && needs.changed-shadow-paths.outputs.requires_shadow_reports == 'true'
-    services:
-      postgres:
-        image: postgres:17
-        env:
-          POSTGRES_USER: ferro
-          POSTGRES_PASSWORD: ferro
-          POSTGRES_DB: ferro
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd "pg_isready -U ferro -d ferro"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-    env:
-      FERRO_SUPABASE_URL: postgresql://ferro:ferro@127.0.0.1:5432/ferro?sslmode=disable
-      FERRO_SHADOW_RUNTIME: "1"
-      FERRO_SHADOW_RUNTIME_STRICT: "1"
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.13'
-
-      - name: Install UV
-        uses: astral-sh/setup-uv@v5
-        with:
-          enable-cache: true
-
-      - name: Set up Rust
-        uses: dtolnay/rust-toolchain@stable
-
-      - name: Cache Rust build
-        uses: Swatinem/rust-cache@v2
-        with:
-          prefix-key: v1
-          cache-on-failure: true
-
-      - name: Install dependencies
-        run: |
-          uv sync --only-group ci-test --no-install-project --python 3.13
-
-      - name: Build Rust extension
-        run: |
-          uv run maturin develop
-
-      - name: Verify stable shadow reports
-        run: |
-          uv run pytest -v tests/test_shadow_reports.py::test_shadow_report_fixture_stable --db-backends=sqlite,postgres
-
   check-conventional-commits:
     name: Check Conventional Commits
     runs-on: ubuntu-latest
@@ -377,7 +296,7 @@ jobs:
 
   all-checks:
     name: All Checks Passed
-    needs: [changed-shadow-paths, lint-and-format, test-python-pr, test-python-main, test-python-backend-matrix, test-shadow-reports-pr, test-rust]
+    needs: [lint-and-format, test-python-pr, test-python-main, test-python-backend-matrix, test-rust]
     runs-on: ubuntu-latest
     if: always()
     steps:
@@ -386,15 +305,10 @@ jobs:
         run: |
           ok() { [[ "$1" == "success" || "$1" == "skipped" ]]; }
 
-          if [[ "${{ needs.changed-shadow-paths.result }}" == "failure" ]]; then
-            echo "Shadow path detection failed; refusing to treat shadow gate as passed."
-            exit 1
-          fi
           if ! ok "${{ needs.lint-and-format.result }}"; then exit 1; fi
           if ! ok "${{ needs.test-python-pr.result }}"; then exit 1; fi
           if ! ok "${{ needs.test-python-main.result }}"; then exit 1; fi
           if ! ok "${{ needs.test-python-backend-matrix.result }}"; then exit 1; fi
-          if ! ok "${{ needs.test-shadow-reports-pr.result }}"; then exit 1; fi
           if ! ok "${{ needs.test-rust.result }}"; then exit 1; fi
 
           echo "All checks passed!"

{ferro_orm-0.13.0 → ferro_orm-0.15.0}/.github/workflows/release.yml

@@ -8,6 +8,11 @@ on:
         required: false
         type: boolean
         default: false
+      highlights:
+        description: 'Markdown prepended to the top of the GitHub Release body'
+        required: false
+        type: string
+        default: ''
 
 concurrency:
   group: release-${{ github.workflow }}-${{ github.ref }}
@@ -185,6 +190,20 @@ jobs:
           echo "release_ref=$RELEASE_TAG" >> "$GITHUB_OUTPUT"
           echo "Using release ref: $RELEASE_TAG"
 
+      - name: Prepend highlights to GitHub Release
+        if: steps.verify_release.outputs.release_created == 'true' && inputs.highlights != ''
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
+          # Passed via env (not inline ${{ }}) so backticks, $, and quotes in the
+          # prose can't break the script or inject shell.
+          HIGHLIGHTS: ${{ inputs.highlights }}
+        shell: bash
+        run: |
+          TAG="${{ steps.release_ref.outputs.release_ref }}"
+          BODY="$(gh release view "$TAG" --json body -q .body)"
+          { printf '%s\n' "$HIGHLIGHTS"; printf '\n---\n\n'; printf '%s\n' "$BODY"; } > /tmp/notes.md
+          gh release edit "$TAG" --notes-file /tmp/notes.md
+
       - name: Release summary
         if: always()
         shell: bash

{ferro_orm-0.13.0 → ferro_orm-0.15.0}/AGENTS.md

@@ -27,18 +27,23 @@ For a single model, every emitter must agree on:
 
 1. **Table name** — already handled by `model_name.lower()`.
 2. **Column names** — including shadow `*_id` columns from `ForeignKey`.
-3. **Column types** — pydantic JSON schema → SQL type mapping must be one
-   function (or two functions whose outputs are tested for parity). This
-   includes the canonical `db_type` vocabulary (`text`, `varchar(N)`,
-   `smallint`, `int`, `bigint`, `uuid`, `timestamp`, `timestamptz`, `date`,
-   `time`) — duplicated in `_db_type_to_sa_type` (Python) and
-   `db_type_token_to_canonical` (Rust), pinned by
-   `tests/test_db_type_cross_emitter_parity.py`.
+3. **Column types** — decided by ONE function:
+   `ferro_ddl_lowering::resolve_column_storage` (explicit `db_type` token →
+   native-enum resolution → the `canonical_from_parts` cascade). The Alembic
+   bridge consumes it mechanically over FFI (`_core._resolve_storage_type`)
+   and `_db_type_to_sa_type` is only the SA *rendering* of the shared token
+   vocabulary — never a second decision table. Pinned exhaustively by
+   `tests/test_db_type_cross_emitter_parity.py` (every token and every
+   derived annotation × both dialects). See
+   `docs/solutions/patterns/derived-type-and-naming-decision-table.md`.
 4. **Index names** — `idx_<table>_<col>` for single-column indexes,
    `idx_<table>_<col1>_<col2>...` for composite indexes.
 5. **Unique constraint names** — `uq_<table>_<col>` for single-column,
    `uq_<table>_<col1>_<col2>...` for composite.
-6. **Foreign key constraint names** — when explicitly named.
+6. **Foreign key constraint names** — `fk_<table>_<col>_<to_table>`, always
+   emitted (both emitters render `SchemaForeignKey.name`; single-sourced in
+   `ferro_ddl_lowering::fk_name`). See
+   `docs/solutions/patterns/derived-type-and-naming-decision-table.md`.
 7. **Primary key constraint names** — when explicitly named.
 8. **Check constraint names** — `ck_<table>_<col>` for the single-column
    `db_check=True` constraint; generated by `_ck_constraint_name` (Python)
@@ -244,9 +249,12 @@ Rules:
   checking (`User.age >= 18` types as `bool`; `where()` expects
   `QueryNode | Predicate`). Docs say so explicitly wherever the style is
   shown.
-- **`order_by` is not a predicate** and keeps attribute style
-  (`order_by(User.age, "desc")`). Passing a lambda to `order_by` silently
-  produces a junk column name — never show it.
+- **`order_by` is not a predicate**, but its lambda selector
+  (`order_by(lambda u: u.age, "desc")`) is validated and is the documented
+  style — and it is the ONLY way to order by a related column
+  (`order_by(lambda t: t.account.label)`), which relation traversal requires.
+  Attribute style is not accepted — `order_by` takes a column-name string or
+  a lambda selector (anything else raises `TypeError`).
 
 The canonical comparisons live in `docs/pages/guide/queries.md`
 ("Predicate Styles") and `docs/pages/concepts/query-typing.md`; everywhere
@@ -313,3 +321,19 @@ Rules:
 This applies to brainstorming, design discussions, PR descriptions, issue
 comments, and any explanation directed at the maintainer. It governs how work is
 communicated, not what gets built.
+
+---
+
+## Agent skills
+
+### Issue tracker
+
+GitHub Issues on `syn54x/ferro-orm`; external PRs are a triage surface. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Canonical five-role vocabulary (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context — `CONTEXT.md` at repo root, ADRs in `docs/adr/`. See `docs/agents/domain.md`.

{ferro_orm-0.13.0 → ferro_orm-0.15.0}/CHANGELOG.md

@@ -1,6 +1,206 @@
 # CHANGELOG
 
 
+## v0.15.0 (2026-07-11)
+
+### Chores
+
+- ADR-0008 populated relations + include/populated-relation glossary
+  ([`a1b273d`](https://github.com/syn54x/ferro-orm/commit/a1b273dc71b2b0f77e08e69808281ab5c25ffaea))
+
+- Amend registration adr with review outcomes (operation-seam sync, build-then-swap, deregistration)
+  ([`fcb8db3`](https://github.com/syn54x/ferro-orm/commit/fcb8db385ef5c835121420b0d90c4a9bbfd8a1f8))
+
+- New adrs and context
+  ([`3ea617c`](https://github.com/syn54x/ferro-orm/commit/3ea617c2ff418aa91fdf2d72470826b0aeec7242))
+
+- Pin failed-resolve retryability in registration adr
+  ([`d5895ba`](https://github.com/syn54x/ferro-orm/commit/d5895bae311cf9a2cff230b16a975aa1a1e9a2ad))
+
+- Pin zero-DDL, single-flight, and pure-Python clean-path invariants in registration adr
+  ([`09673f3`](https://github.com/syn54x/ferro-orm/commit/09673f334128cba7af7d94db38c6f43acd241d37))
+
+- Registration adr
+  ([`05c5732`](https://github.com/syn54x/ferro-orm/commit/05c5732125370d1e2b539f83f89e200190c67bd0))
+
+- Relation traversal ADR and context
+  ([`9151856`](https://github.com/syn54x/ferro-orm/commit/9151856364ea6ccc8ca125102302b5115e6a9ae0))
+
+- Triage and update old plan statuses
+  ([`2f3e3c0`](https://github.com/syn54x/ferro-orm/commit/2f3e3c0584eec37815e2520852077b9c08885546))
+
+### Continuous Integration
+
+- **release**: Custom highlights atop the GitHub Release notes
+  ([#275](https://github.com/syn54x/ferro-orm/pull/275),
+  [`f705938`](https://github.com/syn54x/ferro-orm/commit/f70593839af93ec902a0537f0f1ae73a34c425c2))
+
+### Documentation
+
+- ADR-0007 materialization plan + complete-instance glossary
+  ([`4acc879`](https://github.com/syn54x/ferro-orm/commit/4acc879b23fcd5bc540b5ed7ee7129d95124ec77))
+
+### Features
+
+- Atomic bulk registration install with fingerprint gate (#244)
+  ([#251](https://github.com/syn54x/ferro-orm/pull/251),
+  [`20c6061`](https://github.com/syn54x/ferro-orm/commit/20c6061c376faab78a7e3dc2496e5dd3cc123115))
+
+- Compile ModelCodecPlan from SchemaIR at registration
+  ([#239](https://github.com/syn54x/ferro-orm/pull/239),
+  [`7e15fdc`](https://github.com/syn54x/ferro-orm/commit/7e15fdcb9f32938857ad21838feca978591fd044))
+
+- Generation-counter dirty tracking with assemble-not-recompile (#245)
+  ([#252](https://github.com/syn54x/ferro-orm/pull/252),
+  [`2790e56`](https://github.com/syn54x/ferro-orm/commit/2790e566437d6e67f1f5c3abe555162ebb62598d))
+
+- Joined-row hydration — QueryIR v4 + populated relations via include()
+  ([#289](https://github.com/syn54x/ferro-orm/pull/289),
+  [`4335417`](https://github.com/syn54x/ferro-orm/commit/4335417cbfd33da95b6ea52971d6f5e805af9ad7))
+
+- JSONB column support (#260) ([#266](https://github.com/syn54x/ferro-orm/pull/266),
+  [`19f8cee`](https://github.com/syn54x/ferro-orm/commit/19f8cee3b7be3a570265f1269c735ac9093ab16a))
+
+- Partial materialization — QueryIR v3 + partial selects (Rows/Row)
+  ([#283](https://github.com/syn54x/ferro-orm/pull/283),
+  [`e44129b`](https://github.com/syn54x/ferro-orm/commit/e44129bf966fa349b5bf637a5976c99b88c644b2))
+
+- Query-time joins — relation traversal for filter and sort (stage 1)
+  ([#276](https://github.com/syn54x/ferro-orm/pull/276),
+  [`55dc386`](https://github.com/syn54x/ferro-orm/commit/55dc386f087fd6506d1713c9333bc11103bc96ac))
+
+- Sync registration at ORM operation seam (#247)
+  ([#254](https://github.com/syn54x/ferro-orm/pull/254),
+  [`8409322`](https://github.com/syn54x/ferro-orm/commit/84093226a86b2cdc17afdce00d36fc4782c614c4))
+
+### Refactoring
+
+- Canonicalize registry keys — derive register_model key from model identity
+  ([#250](https://github.com/syn54x/ferro-orm/pull/250),
+  [`d835c96`](https://github.com/syn54x/ferro-orm/commit/d835c96f08094ca0a8f7df0947ba9440f956edc9))
+
+- Centralize register/deregister registry entrypoints (#243)
+  ([#248](https://github.com/syn54x/ferro-orm/pull/248),
+  [`2f2be69`](https://github.com/syn54x/ferro-orm/commit/2f2be69ac9dc859621afa5938f08b7f167af1870))
+
+- Compile ColumnSpec column facts once (#255) ([#256](https://github.com/syn54x/ferro-orm/pull/256),
+  [`75fe1de`](https://github.com/syn54x/ferro-orm/commit/75fe1de5f3aee8f870e1e189f639b7466445c6dd))
+
+- Drop RegisteredModel.schema — IR-first registry cleanup
+  ([#241](https://github.com/syn54x/ferro-orm/pull/241),
+  [`fc3b9f9`](https://github.com/syn54x/ferro-orm/commit/fc3b9f9c50bbd80f3915663e6278712df35fee96))
+
+- Remove legacy migration shims and shadow runtime
+  ([#237](https://github.com/syn54x/ferro-orm/pull/237),
+  [`c2117b3`](https://github.com/syn54x/ferro-orm/commit/c2117b3351189912436c90552e127018db438c34))
+
+### Testing
+
+- Pin provisional import — Python-only registration until connect (#246)
+  ([#253](https://github.com/syn54x/ferro-orm/pull/253),
+  [`ca111b5`](https://github.com/syn54x/ferro-orm/commit/ca111b5672c647cbb021fd63bf59038f0028f303))
+
+
+## v0.14.0 (2026-07-07)
+
+### Bug Fixes
+
+- **ff-g**: Make Postgres db_check ADD CONSTRAINT idempotent (G6, #176)
+  ([#181](https://github.com/syn54x/ferro-orm/pull/181),
+  [`2c0e4cf`](https://github.com/syn54x/ferro-orm/commit/2c0e4cf6c922a73454198f6aa0aa75b30eb1f0c8))
+
+### Chores
+
+- **benchmarks**: Pinned async benchmark suite over the rich-type hot path
+  ([#196](https://github.com/syn54x/ferro-orm/pull/196),
+  [`d9a656b`](https://github.com/syn54x/ferro-orm/commit/d9a656b320bd7fb6b613f4408a796161e9badc41))
+
+### Documentation
+
+- Consolidate migration guides into one evergreen upgrade guide
+  ([#234](https://github.com/syn54x/ferro-orm/pull/234),
+  [`15c83db`](https://github.com/syn54x/ferro-orm/commit/15c83dbc6b1c057a78dfc425d70441e50c359f5d))
+
+- Fixes roadmap
+  ([`5718d02`](https://github.com/syn54x/ferro-orm/commit/5718d02630b6c84d3ced6f8a3080adf4e7fe2383))
+
+- **fable-fixes**: Fold #176 into Epic FF-G as sub-task G6
+  ([`b966e65`](https://github.com/syn54x/ferro-orm/commit/b966e65739d7c33ed666a7fd14086a27688516dd))
+
+- **ff-a**: A5 — docs & migration guide for the mutation-surface changes
+  ([#180](https://github.com/syn54x/ferro-orm/pull/180),
+  [`ffc5476`](https://github.com/syn54x/ferro-orm/commit/ffc5476f9ba72f03a35048f283b11390f813856b))
+
+- **ff-b**: Tick FF-B sub-task and exit-gate boxes in the fable-fixes roadmap
+  ([`29f9172`](https://github.com/syn54x/ferro-orm/commit/29f91724e2b6886f8299bbb42940c804c8e88141))
+
+### Features
+
+- **ff-a**: Create() is a real INSERT; save() distinguishes INSERT from UPDATE (A3+A4)
+  ([#179](https://github.com/syn54x/ferro-orm/pull/179),
+  [`de3ec30`](https://github.com/syn54x/ferro-orm/commit/de3ec30196202ee14c42afc5b02f163f82a68451))
+
+- **ff-a**: Reject limit/offset on mutating queries
+  ([#178](https://github.com/syn54x/ferro-orm/pull/178),
+  [`67faf42`](https://github.com/syn54x/ferro-orm/commit/67faf421d49984c5be16d2163982f13ab86cc5e4))
+
+- **ff-a**: Typed DBAPI-shaped exception hierarchy mapped from sqlx errors
+  ([#177](https://github.com/syn54x/ferro-orm/pull/177),
+  [`9c306c5`](https://github.com/syn54x/ferro-orm/commit/9c306c549e716dd4a5158d655265aa7890e63c0b))
+
+- **ff-b**: B1 canonical derived-type & naming decision table + refusal-rail scaffolding
+  ([`8c879f7`](https://github.com/syn54x/ferro-orm/commit/8c879f77833a7e5a983d53012efc8332cca5b852))
+
+- **ff-b**: B2+B6 one derived-type decision table; native PG enums + timestamptz/time parity; delete
+  bridge mirrors
+  ([`bfdc1fd`](https://github.com/syn54x/ferro-orm/commit/bfdc1fda1eceebe70ae711e38b785af88b46e11e))
+
+- **ff-b**: B3+B4 single-source artifact naming; both emitters emit named fk_/uq_ artifacts
+  ([`6b771f3`](https://github.com/syn54x/ferro-orm/commit/6b771f38933c72e8f848013a5ae93708fabf5c7a))
+
+- **ff-c**: C1 — per-model ColumnCodec plan; delete codec.rs schema sniffing (F5)
+  ([#197](https://github.com/syn54x/ferro-orm/pull/197),
+  [`0e8e572`](https://github.com/syn54x/ferro-orm/commit/0e8e57252f4cca2d2bc9fffd06d9155338056cf3))
+
+- **ff-c**: C2 — schema-epoch catalog cache; zero catalog queries on steady-state CRUD
+  ([#200](https://github.com/syn54x/ferro-orm/pull/200),
+  [`8c6d6ed`](https://github.com/syn54x/ferro-orm/commit/8c6d6edf578cf55ed7ada0d49359a7e09528da1e))
+
+- **ff-c**: C3+C4 — native typed Postgres decode; plan-driven enum hydration replaces _fix_types
+  ([#198](https://github.com/syn54x/ferro-orm/pull/198),
+  [`05a008c`](https://github.com/syn54x/ferro-orm/commit/05a008cb73f6c4dc8b2478a441c99282d07bd41d))
+
+- **ff-d**: Session-scoped weak identity map with refresh-on-load; single-handle routing
+  ([#201](https://github.com/syn54x/ferro-orm/pull/201),
+  [`a328cfc`](https://github.com/syn54x/ferro-orm/commit/a328cfcd107e2cac998ddc8af50845857ec669a5))
+
+- **ff-e**: Registry & model identity — qualified keys, configurable tables, O(N) import
+  ([#209](https://github.com/syn54x/ferro-orm/pull/209),
+  [`6391805`](https://github.com/syn54x/ferro-orm/commit/6391805c1b4ee46c0590513ac6684237c18f7430))
+
+- **ff-f**: Query builder 1.0 shape — immutable chaining, build-time column validation, lambda-only
+  predicates, QueryIR-only Rust ([#223](https://github.com/syn54x/ferro-orm/pull/223),
+  [`eb7fece`](https://github.com/syn54x/ferro-orm/commit/eb7fece8fbc2231220ecf9111616f803f2f987eb))
+
+- **ff-g-a**: Hardening — hydration ABI guard, transactional PG migrate, correctness edges,
+  decode-path caching ([#232](https://github.com/syn54x/ferro-orm/pull/232),
+  [`22617e1`](https://github.com/syn54x/ferro-orm/commit/22617e1cfe5e2bc9d0a3d7a1fed5acf4d8589cef))
+
+### Refactoring
+
+- **ff-g-b**: Operations.rs dedup — ModelMeta + Executor (G2)
+  ([#233](https://github.com/syn54x/ferro-orm/pull/233),
+  [`09c2c62`](https://github.com/syn54x/ferro-orm/commit/09c2c6214af9e2f9510d39d037935c53bd2e796d))
+
+### Testing
+
+- **ff-b**: B5 I-1 sentinel on the full backend matrix with a full-type fixture, zero filters
+  ([`1141eb4`](https://github.com/syn54x/ferro-orm/commit/1141eb437b4843303e01556a5b24ddee9d0e0279))
+
+- **ff-b**: Force psycopg v3 driver in the Postgres sentinel regardless of URL scheme
+  ([`64f9845`](https://github.com/syn54x/ferro-orm/commit/64f98454bdb5e090a41bd214de06b7670974f4eb))
+
+
 ## v0.13.0 (2026-07-02)
 
 ### Bug Fixes

ferro_orm-0.15.0/CONTEXT.md

@@ -0,0 +1,89 @@
+# Ferro ORM
+
+A Python ORM with a Rust core. Models are Pydantic subclasses; schema compiles to SchemaIR and fans out to runtime DDL and the Alembic bridge.
+
+## Language
+
+**Materialized View**:
+A PostgreSQL database object that stores the result of a query and is refreshed on demand. In Ferro it is a read-only `MaterializedView` subclass — queryable through the normal ORM, not writable.
+_Avoid_: Snapshot table, cache table, denormalized table
+
+**Refresh**:
+The explicit operation that repopulates a materialized view from its defining SELECT. Ferro never refreshes at connect time; the user calls `refresh()` when they want updated data.
+_Avoid_: Auto-refresh, sync, rebuild
+
+**Postgres-only schema object**:
+A model artifact that Ferro emits only on PostgreSQL. On SQLite the class still registers for imports and typing, but DDL is skipped and querying raises a clear error.
+_Avoid_: Dialect-specific model, PG-only table
+
+**Redefine**:
+Replacing an existing materialized view by dropping and recreating it when its defining SELECT changes. Authorized by `migrate_materialized_redefine=True`; otherwise connect fails loudly on drift.
+_Avoid_: Alter, migrate, update
+
+**Materialized view column**:
+A flat, typed field on a `MaterializedView` — same declarations as `Model` fields, but no `ForeignKey`, `BackRef`, or `ManyToMany`. Reference related entities by scalar columns (`order_id: int`), not relations.
+_Avoid_: Relation column, FK field
+
+**Materialized query**:
+The `ClassVar` SQL string (`__materialized_query__`) that defines what rows a materialized view stores. Declared alongside typed fields; Ferro validates that SELECT output matches the field contract.
+_Avoid_: Select SQL, view definition, query body
+
+**Read-only view**:
+A `MaterializedView` that can be queried but never mutated. `save()`, `delete()`, and `create()` raise a clear error.
+_Avoid_: Immutable model, snapshot model
+
+**Storage token**:
+A word in the canonical `db_type` vocabulary (`text`, `bigint`, `timestamptz`, `jsonb`, …) naming how a column is stored. One shared vocabulary feeds every emitter; a token never means different things to different emitters.
+_Avoid_: SQL type string, dialect type, column type name
+
+**Storage lowering**:
+The dialect-side degrade of a storage token to the nearest type a backend supports (e.g. `jsonb` stores as plain JSON on SQLite). Lowering is silent and documented; it never changes value semantics — only the on-disk representation.
+_Avoid_: Fallback type, emulation, downgrade
+
+**Json-family field**:
+A field whose values Ferro stores as JSON documents: `dict`, `list` (any element type, including nested models), or a nested Pydantic model. Only json-family fields may opt into JSON storage tokens such as `jsonb`.
+_Avoid_: Object field, blob field, document column
+
+**Column spec**:
+The single authoritative record of one column's facts — identity, type, and constraints — derived exactly once from the field declaration. Provisional at class-body time; authoritative once relationship resolution completes.
+_Avoid_: Column metadata, enriched schema property, field dict
+
+**Relation traversal**:
+Attribute access on a declared forward-FK field inside a query lambda (`lambda t: t.account.ledger_id`), reaching a related model's columns from the root. Traversal narrows the result to rows where the relation exists; keeping rows without the relation requires an explicit left join.
+_Avoid_: Join inference, nested filter, path lookup, string path
+
+**Relation path**:
+The ordered sequence of forward-FK hops a traversal walks (`account`, or `account → owner`). A path is the identity of a join: the same path referenced anywhere in a query is one join, and distinct paths to the same model are distinct joins. Left-join requests apply to a whole path.
+_Avoid_: Join alias, lookup chain, dotted path string
+
+**Shape-preserving query**:
+The invariant that filtering and ordering never change what a query returns — a query over Transaction yields Transaction instances regardless of which relations its predicates traverse. Only an explicit projection operation may change the result shape.
+_Avoid_: Implicit projection, row narrowing
+
+**Complete-instance invariant**:
+A model instance always carries a complete row — there is no such thing as a partial or deferred-field model instance, anywhere. Anything narrower than a full row (a column subset, an aggregate) comes back as a projected record, never as the model type.
+_Avoid_: Partial instance, deferred field, lightweight model, .only()
+
+**Projected record**:
+The result of an explicit projection — a typed record of named values that is not a model instance and cannot be saved, refreshed, or identity-mapped. Column subsets and aggregation results are projected records; complete model rows are not. Realized as `Row`, delivered in the list-like `Rows` container.
+_Avoid_: Partial model, row dict, value tuple
+
+**Include**:
+The explicit request (`.include(lambda t: t.account.owner)`) that a query populate a forward-FK relation path — the data axis of a query, distinct from joins (membership) and projection (shape). Including a path populates every hop along it and never changes which rows come back.
+_Avoid_: Eager load, select_related, prefetch, join-fetch
+
+**Populated relation**:
+A forward-FK field carrying its complete related instance, attached by an explicit include on the query. Attribute access returns the instance directly — no await, no query — matching the field's declared type. An unpopulated relation keeps the awaitable contract; population changes cost and attached data, never the result type (there is no separate "loaded" model type).
+_Avoid_: Eager-loaded field, select_related, prefetched attribute, joined attribute
+
+**Materialization plan**:
+A query's declaration of what its result columns become: complete root instances (every query today), a projected record of named fields, or — in the future — a populated instance graph. Every query carries exactly one plan; the plan travels with the query rather than being inferred from its column list.
+_Avoid_: Select list, projection spec, hydration mode flag
+
+**Provisional registration**:
+The per-model state installed when a class body finishes executing — enough for runtime codec and PK metadata, but relationships may still be pending and the modelset is not yet authoritative for DDL.
+_Avoid_: Import-time registration, partial registry
+
+**Resolved registration**:
+The registry epoch after relationship resolution completes — join tables exist, shadow FK columns are wired, and the SchemaIR modelset is authoritative for DDL and auto-migrate.
+_Avoid_: Final registration, committed registry