snake-orm 0.1.0b1__tar.gz

snake_orm-0.1.0b1/.gitignore

@@ -0,0 +1,71 @@
+# Venv / UV
+.venv/
+venv/
+
+# Python cache / compile
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+
+# Python packaging, ANCHORED to the root with a leading slash. Without it these are not "the build/
+# directory of the project": a pattern with no `/` matches at ANY depth, and `lib/` swallowed
+# `frameworks/react_front/src/core/lib/` — two real modules that CI could not find and this machine
+# could, because they were on disk and never in the index.
+/build/
+/develop-eggs/
+/dist/
+/downloads/
+/eggs/
+/.eggs/
+/env/
+/lib/
+/lib64/
+/parts/
+/sdist/
+/var/
+/wheels/
+/share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Testing & Linting
+.mypy_cache/
+.pytest_cache/
+.hypothesis/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# IDE / Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Environment variables
+.env
+
+# Built, never versioned. These names ARE meant to match at any depth: a `node_modules` is a
+# `node_modules` wherever it turns up.
+site/
+node_modules/
+*.tsbuildinfo
+
+# The Vite bundle. Named in full because `/dist/` above is anchored and this one is not at the root.
+frameworks/react_front/dist/
+
+# Databases the docs and the demos leave behind when somebody RUNS them
+*.sqlite
+*.db
+
+# Plans and internal notes: local only. `docs/features.md` is the feature index, not a plan.
+docs/planning/
+docs/interno/

snake_orm-0.1.0b1/CHANGELOG.md

@@ -0,0 +1,166 @@
+# Changelog
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+**No dates yet, and that is the convention rather than an omission.** `Unreleased` carries no date
+because the date is what a release stamps on it. The repository holds no tag, the package is not on
+PyPI, and `docs/contributors/release.md` says what the first release would still take. When the first
+tag lands, this section gets a heading with its version and its day, and a new `Unreleased` opens
+above it.
+
+**One language, and it is English.** The prose under `docs/` is mirrored in Spanish because it
+teaches; this file records what changed, and it is read beside a tag and a package page — the same
+audience the code, the docstrings and every message the ORM emits already speak to.
+
+**What this is not.** Not a list of commits. What survived here is what changed for somebody USING
+the ORM: the defects that produced wrong data or wrong SQL, and the reversals of decisions already
+made. Ordered by weight inside each group, because that is how somebody reads a changelog they have
+never seen before.
+
+## 0.1.0b1
+
+The first published version, and a beta on purpose: `pip install snake-orm` does not
+install it — a preliminary is only picked up when it is asked for by name or with `--pre`.
+Everything below is what the repository already carried before it had a version number.
+
+### Security
+
+**Remote code execution in the scaffolder.** `scaffold create` reads table names, column names and
+comments FROM THE DATABASE and writes them into a `models.py` the user imports; they went in raw
+through f-strings. Confirmed with a real payload: a `COMMENT ON COLUMN` that closes the
+`db_comment="..."`, puts an `__import__(...).system(...)` on its line and reopens a literal. The file
+compiled and ran the command on import — whoever controlled a legacy schema controlled the machine of
+whoever scaffolded it. The migration renderer was already escaping the same field correctly.
+
+### Fixed — wrong data
+
+**A JOIN resolved by CLASS NAME and went to the wrong table.** Two models with the same class name in
+different modules resolved to whichever the global index happened to hold. The query ran and returned
+rows. It took three passes to close: first a foreign key pointing at another model's table, then a
+`through=` chain that still went to the global index, and finally the relationship resolution itself.
+A class name does not identify a model.
+
+**A `NULL` in a column with a converter became `False`, and was persisted.**
+
+**A UNION with narrowed branches put values in the wrong field.** SQLite REGROUPED a compound's
+operators and nobody noticed, and a compound's `ORDER BY` lost the relation jump and sorted by
+another column.
+
+**The fifteen paths where the ORM stayed quiet and returned wrong data.** Reported as one sweep
+because they shared a shape: a guard that answered instead of refusing.
+
+**`col == None` emitted `= NULL`** instead of `IS NULL`.
+
+**Row values were not coerced to the declared `python_type`** — psycopg2 handed back a UUID as a
+string, a `time` column came back from MySQL as a `timedelta`, and `annotate()` scalars were not
+coerced at all.
+
+**Four knobs fell silently, `refresh` degraded a `Decimal`, and `add_all` dropped data.** Same pass:
+the debug panel rendered in production and the async pool did not clean up.
+
+**The same DSN named two databases depending on which door you came in by**, and a `file:` DSN was
+read as a FILENAME at both ends.
+
+### Fixed — SQLite and MySQL
+
+**SQLite had no transactions.** `rollback()` was a no-op and everything ran in autocommit. Foreign
+keys did not exist either, migrations died on the first statement, `WITH RECURSIVE` was broken
+entirely, and `.any()`, `.count()` and the four collection aggregates were broken too.
+
+**MySQL ignored the declared date precision** and said nothing. An enum knows its own width and the
+ORM threw it away, so MySQL stored TEXT. It has no partial indexes, and the ORM sent it the `WHERE`
+all the same. `nulls_last()` emitted syntax it rejects — and that was the guide's own example.
+
+**A model with only an autoincrement PK could not be inserted on ANY engine.**
+
+**`datetime` mapped to a column without a zone**, which drops `tzinfo`.
+
+### Fixed — migrations
+
+**Unique constraints were created and dropped under different names.** The index diff never ran, so
+adding an index migrated nothing. `db_comment` was dead metadata that nothing ever emitted. Foreign
+keys were diffed by name rather than by definition.
+
+**A `DropForeignKey` vanished silently and tables were dropped in alphabetical order.** A rebuild ate
+its table's trigger, and `BIGSERIAL` — which exists only in `CREATE TABLE` — was written into the
+`ALTER` too.
+
+**The diff compared `python_type` by IDENTITY** and demanded an empty table rewrite. Only `dict` is
+normalised: `list[int]` and `list[str]` land on different SQL types, so unwrapping every origin would
+have hidden a real change.
+
+**`snakeorm fresh` worked by luck**, and the pragmas that claimed to save it did nothing.
+
+### Fixed — the scaffolder
+
+**It stopped parsing at a non-English table name** and lost columns without saying so. It mirrored
+against `public` and threw away half of what it had already read. It validated the name that comes IN
+and wrote the one it DERIVES.
+
+### Changed — breaking
+
+**Each engine gets the DDL grammar it actually speaks.** A capability catalogue answers for the whole
+thing, and what an engine cannot do is declared and said out loud rather than stored worse in
+silence. A type the engine lacks falls back to TEXT, and the value knows how to come home.
+
+**`snake_column` splits into per-type specifiers**, with two date declarators so the model says which
+column it creates, and `SnakeUtc`: an instant that cannot be built wrong.
+
+**A nullable FK demands an optional relationship**, a relation points at ONE model, and a collection
+is never optional. `SnakeToOne[Card | Transfer | None]` used to discard `Transfer` in silence.
+
+**Assigning a relation no longer fails silently**, and a missing value shouts instead of vanishing.
+
+**Async reaches the three engines**, with the same protocol and the same composition root. Both
+sessions consume the same Plan and the same words, and the drift between them got a test.
+
+**The repository speaks English** — the package, the test suite, and the ORM's own messages to the
+user. The prose under `docs/` is bilingual; nothing else is.
+
+### Changed
+
+**The demos declare their shapes and the generator writes them.** Migrating one module surfaced nine
+discrepancies between what the dict built and what the model declares. The injection of the model
+graph into the globals of eleven foreign modules is gone: the linker reads the `TYPE_CHECKING` block
+instead.
+
+**The annotation quoting rule climbs the WHOLE tree, and there are four situations.** Only what does
+not exist yet gets quoted, and nothing else. A relative import inside a `TYPE_CHECKING` block is read
+now, and six more spellings besides.
+
+**SQL literal formatting moved to the dialect**, which is what made a second engine possible at all.
+
+**The `src/` layout**, zero cycles between packages, and the loose modules at the root grouped into
+`core/` and `helpers/`.
+
+### Performance
+
+**The hot path 4.9x**, hydration roughly 2x, and the async streaming that had been crossing the
+thread PER ROW.
+
+**The select-in splits by the engine's placeholder ceiling.**
+
+### Fixed — the gates
+
+Listed apart because they break something else: not the user, but the reason to trust a green run.
+
+**`make audit` had been red for pyright** since an unrelated fix, unnoticed. **The gate switch was a
+blacklist**, so `off` turned the gates ON. **The MySQL gate sent you to look at Postgres' variables.**
+**The type-check of the demos' shared layer measured `Any` and reported Success.** **The integration
+tests were skipping silently, and pyright never ran at all.**
+
+## Writing an entry
+
+One line per change somebody using the ORM would notice, under `Added`, `Changed`, `Deprecated`,
+`Removed`, `Fixed` or `Security` — only the groups with something in them. Two rules this repository
+already applies everywhere else apply here too:
+
+- **Say what changed for the reader, not what was edited.** "`count()` no longer drops `limit()`"
+  beats "refactored the query planner".
+- **No counts of what the repository IS** — tests, files, supported features. A number nobody
+  re-reads goes stale the same day and then lies with authority. A number the entry MEASURED stays,
+  because a past measurement does not drift: "the hot path 4.9x" is a fact and will read the same in
+  a decade.
+
+A change that alters SQL on one engine and not the others names the engine, because that is the
+difference somebody will hit.

snake_orm-0.1.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anthony Velez Tapia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

snake_orm-0.1.0b1/PKG-INFO

@@ -0,0 +1,366 @@
+Metadata-Version: 2.5
+Name: snake-orm
+Version: 0.1.0b1
+Summary: Fully typed deep relationship navigation in Python. No codegen, no type-checker plugin.
+Project-URL: Homepage, https://github.com/velezanthony/snake-orm
+Project-URL: Documentation, https://velezanthony.github.io/snake-orm/
+Project-URL: Source, https://github.com/velezanthony/snake-orm
+Project-URL: Issues, https://github.com/velezanthony/snake-orm/issues
+Project-URL: Changelog, https://github.com/velezanthony/snake-orm/blob/main/CHANGELOG.md
+Author-email: Anthony Velez Tapia <velezanthony2000@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: dataclasses,mysql,orm,postgresql,sql,sqlite,typing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Implementation :: CPython
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: psycopg2-binary>=2.9.9
+Requires-Dist: python-dotenv>=1.2.2
+Provides-Extra: async
+Requires-Dist: psycopg[binary]>=3.2; extra == 'async'
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.1; extra == 'mysql'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.27; extra == 'otel'
+Description-Content-Type: text/markdown
+
+# 🐍 SnakeORM
+
+[![CI](https://github.com/velezanthony/snake-orm/actions/workflows/ci.yml/badge.svg)](https://github.com/velezanthony/snake-orm/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)
+![Engines](https://img.shields.io/badge/engines-PostgreSQL%20%7C%20MySQL%20%7C%20SQLite-336791)
+![Typing](https://img.shields.io/badge/typing-mypy%20%2B%20pyright-2ea44f)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Fully typed deep relationship navigation in Python. No codegen. No type-checker plugin.**
+
+Docs (English and Spanish): <https://velezanthony.github.io/snake-orm/>
+
+```python
+Truck.maker.nation.name == "España"   # SnakeExpr[str] -> SnakeCondition
+```
+
+```sql
+SELECT t0."id", t0."model", t0."maker_id" FROM "public"."trucks" AS t0
+JOIN "public"."makers" AS t1  ON t0."maker_id" = t1."id"
+JOIN "public"."nations" AS t2 ON t1."nation_id" = t2."id"
+WHERE t2."name" = %s
+```
+
+Mypy checks it. Pyright checks it. Pylance autocompletes it. The Django equivalent,
+`filter(maker__nation__name="España")`, is a string: no autocomplete, no check, and renaming
+`nation` fails in production.
+
+---
+
+## Install
+
+Requires Python 3.11+. SQLite ships with the standard library, so nothing needs to be running to
+start.
+
+```bash
+pip install snake-orm==0.1.0b1   # or: pip install --pre snake-orm
+```
+
+The distribution is `snake-orm` and the package is `snakeorm`: `import snakeorm`.
+
+The version is a **beta**, and the pin is the point: a preliminary is not picked up by a plain
+`pip install snake-orm`, so nobody upgrades into it by accident while the API is still moving.
+
+From a checkout, to work on the ORM itself:
+
+```bash
+uv sync --all-extras --all-groups
+uv run pytest          # suite
+uv run mypy .          # must pass
+uv run ruff check .    # must pass
+```
+
+[Installation](docs/users/getting-started/installation.md) →
+[first model](docs/users/getting-started/first-model.md) →
+[migrations](docs/users/getting-started/migrations.md).
+
+```python
+@snake_model(table="makers")
+class Maker(SnakeModel):
+    id: SnakeColumn[int] = snake_auto()
+    name: SnakeColumn[str] = snake_str(unique=True)
+    nation_id: SnakeColumn[int] = snake_int()
+    nation: SnakeToOne[Nation] = snake_to_one(nation_id)
+    trucks: SnakeToMany[Truck] = snake_to_many("maker")
+
+snake_link()   # once, after importing every model
+```
+
+The type always comes from the annotation. `snake_column()` only adds SQL information.
+
+```bash
+uv run snakeorm makemigrations --models myapp.models --name initial
+uv run snakeorm migrate --models myapp.models --dsn "host=... dbname=..."
+uv run snakeorm rollback --models myapp.models --dsn "..."
+```
+
+---
+
+## The mechanism
+
+**Recursive descriptors** whose `__get__` returns a different type depending on the access:
+
+```python
+user.car.name               # instance -> the value           -> str
+User.car.brand.name == "x"  # class    -> a SQL expression     -> SnakeCondition
+```
+
+`User.car` returns `type[Car]`, so `.brand.name` re-triggers the class overload of `Car`'s
+descriptors. `@dataclass_transform` on the decorator types `__init__`. It is the manual equivalent
+of TypeScript's mapped types.
+
+The type system is the single source of truth: the class is compiled **once** into an immutable
+metadata graph, and the runtime never reflects on it again.
+
+---
+
+## Why Django returns `Any`
+
+```python
+User.objects.annotate(num_posts=Count("posts"))
+user.num_posts   # -> Any
+```
+
+`annotate` returns "a `User` **plus** a `num_posts: int`". That is an intersection type. TypeScript
+has it; Python does not. So there are three paths, and only three:
+
+| Path | Dynamic names | Real typing | IntelliSense |
+|---|---|---|---|
+| `__getattr__ -> Any` | ✅ | ❌ | ❌ |
+| Declared names | ❌ | ✅ | ✅ |
+| Type-checker plugin | ✅ | ✅ | partial |
+
+Django took the first and patched it with the third (`django-stubs`). SnakeORM forbids the third by
+thesis and takes the second, with a typed escape hatch.
+
+`Any` is not typing, it is switching the checker off:
+
+```python
+def __getattr__(self, name: str) -> Any: ...
+u.agg.count_children * 2           # mypy: 0 errors
+other: str = u.agg.count_children  # mypy: 0 errors  <- same value, as a str
+```
+
+`object` keeps the dynamic name and wakes the checker up:
+
+```python
+def __getattr__(self, name: str) -> object: ...
+u.agg.count_children * 2           # error: unsupported operand types for *
+count: int = cast("int", u.agg.count_children)   # explicit, and signed with your name
+```
+
+---
+
+## Illegal states you cannot write
+
+```python
+SnakeQuery(Nation).filter(Nation.makers.name == "SEAT")
+# error: "SnakeCollection[Maker]" has no attribute "name"  [attr-defined]
+```
+
+In Django that compiles, runs and silently duplicates rows — which is what `.distinct()` is for. A
+to-many exposes **collection operations**, not the child's columns:
+
+```python
+q.filter(Nation.makers.any(Maker.name == "SEAT"))  # any?   -> correlated EXISTS
+q.filter(~Nation.makers.any())                     # none?  -> NOT EXISTS
+q.filter(Nation.makers.count() > 3)                # how many? -> scalar subquery
+q.include(Nation.makers)                           # load them -> select-in, 2 queries
+
+q.include(SnakePrefetch(Nation.makers).then(Maker.trucks))
+# one query per LEVEL (root + makers + trucks = 3), never one per parent
+```
+
+One row per parent. `DISTINCT` is never needed.
+
+```sql
+-- Nation.makers.any(Maker.trucks.any(Truck.model == "Ibiza"))
+SELECT "id", "name" FROM "public"."nations" WHERE EXISTS (
+  SELECT 1 FROM "public"."makers" AS e0 WHERE e0."nation_id" = "nations"."id" AND EXISTS (
+    SELECT 1 FROM "public"."trucks" AS e1 WHERE e1."maker_id" = e0."id" AND e1."model" = %s))
+```
+
+> **Implicit when the answer is unique. Explicit when there is more than one correct answer.**
+
+A to-one never changes the row count, so the `JOIN` is inferred. A to-many does, so the ORM does not
+guess.
+
+---
+
+## What the thesis gives for free
+
+**No silent N+1.** An unloaded relation raises instead of querying:
+
+```python
+truck.maker
+# SnakeRelationshipNotLoaded: Relation 'maker' was not loaded.
+#                             Use .include(Truck.maker) in the query.
+```
+
+**No `F()`.** Class access already is an expression:
+
+```python
+session.update_where(query, [(Counter.views, Counter.views + 1)])
+# UPDATE "counters" SET "views" = ("views" + %s) WHERE ...
+```
+
+Pairs, not a dict: `SnakeExpr` is unhashable because its `__eq__` returns a `SnakeCondition`.
+
+**Many-to-many crosses a real model**, never an implicit table:
+
+```python
+tags: SnakeToMany["Tag"] = snake_to_many_through(through="PostTag", via="post", to="tag")
+```
+
+The bridge is an ordinary model, so extra columns on it are ordinary fields from day one.
+
+**A bulk `UPDATE`/`DELETE` uses the filter and nothing else.** With no `WHERE` it is refused, and
+so is any other knob you set on the same query — `limit()`, `order_by()`, `only()`. Dropping what
+you asked for would answer a different question without saying so: select the rows first, then
+write by primary key.
+
+**`annotate()` counts with a correlated subquery, not a `LEFT JOIN`** — a parent with no children
+comes out `0` instead of disappearing.
+
+**A view is a read-only model, and navigable.** `@snake_view` maps a `VIEW` with typed columns,
+navigable both ways; `session.add/update/delete` reject it in the **type**, because writing requires
+a `SnakeModel`. `CreateView`/`AlterView`/`DropView` live in the migrations.
+
+**Migration history is `.py`**, because `python_type` is a Python `type`. JSON would need a
+name↔type registry: a second type system, parallel to Python's and worse.
+
+---
+
+## Typed annotations
+
+Declare the result class — you choose the name, Python chooses the type:
+
+```python
+@snake_result
+class RealmStats(SnakeResult[Realm]):
+    realm: Realm
+    forge_count: int
+
+rows = session.annotate(query, RealmStats, forge_count=Realm.forges.count())
+rows[0].forge_count  # int, with IntelliSense
+rows[0].realm.name   # str, navigation intact
+```
+
+For genuinely dynamic names, the escape hatch is explicit:
+
+```python
+count = cast("int", realm.aggregate.forge_count)   # object -> the cast is mandatory
+```
+
+Without the cast it does not compile. Without annotating, it raises `SnakeAggregateNotLoaded` naming
+the aggregates it does have.
+
+---
+
+## What is inside
+
+| | |
+|---|---|
+| **Queries** | filter · order/limit/offset · group by/having · aggregates · `annotate` · explicit joins · `include` (to-one and to-many) · deep navigation · `.any()` · correlated subqueries · composite `IN` · `only`/`defer` · `iterate` (server cursor) · `for_update` · `raw` |
+| **SQL** | window functions with frame · `UNION`/`INTERSECT`/`EXCEPT` · `WITH RECURSIVE` · `CASE`/`COALESCE`/`NULLIF` · text, date and math functions · `json_get` · `ILIKE` |
+| **Writes** | insert/update/delete · upsert · bulk · `RETURNING` · savepoints · isolation levels · retry on transient conflict · `refresh` |
+| **Schema** | composite PK and FK · polymorphic inheritance · views · triggers · indexes (partial, functional, `GIN`/`GIST`/`BRIN`) · checks · comments · enums · custom converters |
+| **Engines** | PostgreSQL · MySQL/MariaDB · SQLite, all first class · `Cap` catalogue (`Full`/`Degraded`/`Nope`) · sync and async drivers · pool with `pre_ping`/`recycle`/timeout · statement timeout · `EXPLAIN` |
+| **Migrations** | autodetected diff · atomic runner · `RebuildTable` for SQLite · `RunPython` with reverse · squash · cross-app dependencies · drift detection against the live database |
+| **Tooling** | introspection and scaffold for the three engines · debug panel (`ssr`, `envelope`, `timing`, `sidecar`, `otel`) · index advisor · WSGI/ASGI/Django contrib · CLI |
+
+Row by row, with links to the code, the test and the page: [feature index](docs/features.md).
+
+---
+
+## Architecture
+
+```
+Python class → Model Compiler → immutable metadata graph
+                                        ↓
+        SQL · migrations · query · session · CLI
+```
+
+```
+decorators/  metadata/  compiler/  registry/  linker/
+query/  expressions/  sql/  dialects/  drivers/  session/  migration/  cli/
+```
+
+Two axes that never mix: the **dialect** decides how SQL is *written* (placeholders, quoting,
+`RETURNING`, `ON CONFLICT`); the **driver** decides how it is *executed*. Models and graph are
+engine-agnostic — anything Postgres-specific reaching the model is a bug.
+
+SQL is always parameterised: emission returns `(sql, params)` and values never enter the string.
+That kills injection, and it is what makes multi-engine possible.
+
+Async reuses the whole core: SQL generation does not execute, so it has no colour.
+
+Details in [architecture](docs/contributors/architecture.md); how to work here in
+[CONTRIBUTING](CONTRIBUTING.md).
+
+---
+
+## The type contract is a test
+
+In `test/typing/`:
+
+- `cases_positive.py` — what **must** type, with `assert_type`.
+- `cases_negative.py` — what **must not compile**, each line carrying its `# EXPECT: <code>`.
+- The runner requires mypy to report exactly those errors on exactly those lines, and pyright to
+  reject the same ones.
+
+Break `Truck.maker.nation.name` and the suite fails.
+
+---
+
+## Deliberately not built
+
+- **Identity map and unit of work.** Two queries to the same row return two objects. Writes are
+  explicit; nothing is flushed behind your back.
+- **Lazy loading.** Touching an unloaded relation raises. This is what makes N+1 impossible by
+  default.
+- **Joined-table inheritance.** Single table with a discriminator covers the polymorphism, and its
+  price is one rule: a child's own columns must allow `NULL`.
+- **Model default ordering.** A hidden `ORDER BY` you did not write.
+
+## Known limits
+
+- `storage=NATIVE` in `snake_enum` (Postgres `CREATE TYPE`) is not built: `ALTER TYPE ... ADD VALUE`
+  has no inverse, so its `down_sql` would be a lie. The default `CHECK` is reversible.
+- CHECKs are declared outside the class body (`snake_checks(User, ...)`). Inside it, `__set_name__`
+  has not run and the column does not know its own name.
+- An expression does not carry its owning model in the type: `Maker.id` and `Truck.id` are twins to
+  the checker. Encoding the owner would break deep navigation and condition composition; where it
+  matters (aggregates, `.any()`) it is validated at runtime.
+- No lazy loading, full-text search, JSON containment operators or array operators with a typed API.
+
+The complete, current list is [known limits](docs/users/reference/limits.md) — part of the contract,
+not a list of apologies.
+
+---
+
+## Status
+
+Not published on PyPI. The distribution is named `snake-orm`, the import name is
+`snakeorm`; both are explained in [release](docs/contributors/release.md).
+
+Everything above is implemented and tested against real PostgreSQL, MySQL/MariaDB and SQLite. It has
+not run in production yet, and that is the one thing a repository cannot give itself.