ferro-orm 0.10.5__tar.gz → 0.12.0__tar.gz

{ferro_orm-0.10.5 → ferro_orm-0.12.0}/.github/PERMISSIONS.md

@@ -133,12 +133,12 @@ permissions:
 
 **Why These Permissions:**
 - `pages: write` - Allows the workflow to:
-  - Deploy the generated MkDocs static site to GitHub Pages
+  - Deploy the generated Zensical static site to GitHub Pages
   - Update the Pages deployment for the repository
 - `id-token: write` - Allows secure OIDC auth for Pages deployment
 
 **What It Does:**
-- Builds MkDocs docs
+- Builds Zensical docs
 - Deploys docs to GitHub Pages
 
 ---

{ferro_orm-0.10.5 → ferro_orm-0.12.0}/.github/pull_request_template.md

@@ -33,4 +33,12 @@
 
 ## Related Issues
 
-<!-- Example: Closes #123 -->
+- Closes #
+- Closes #
+
+<!-- Use one line per completed issue: Closes #123 / Fixes #123 / Resolves #123 -->
+
+## Exit Steps
+
+- [ ] Related completed issues are linked above with Closes/Fixes/Resolves
+- [ ] Issue statuses are updated/auto-close on merge

{ferro_orm-0.10.5 → ferro_orm-0.12.0}/.github/workflows/ci.yml

@@ -3,9 +3,9 @@ name: CI
 on:
   workflow_call:
   pull_request:
-    branches: [main]
+    branches: [main, feat/ir-first]
   push:
-    branches: [main]
+    branches: [main, feat/ir-first]
   workflow_dispatch:
 
 concurrency:
@@ -16,6 +16,33 @@ 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
@@ -126,6 +153,10 @@ jobs:
         run: |
           uv run maturin develop
 
+      - name: Run IR vector contract harness
+        run: |
+          uv run pytest -v tests/test_ir_vectors_contract.py
+
       - name: Run pytest
         run: |
           uv run pytest -v --cov=src --cov-report=xml --cov-report=term
@@ -169,6 +200,10 @@ jobs:
         run: |
           uv run maturin develop
 
+      - name: Run IR vector contract harness
+        run: |
+          uv run pytest -v tests/test_ir_vectors_contract.py
+
       - name: Run pytest
         run: |
           uv run pytest -v --cov=src --cov-report=xml --cov-report=term
@@ -236,6 +271,64 @@ 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
@@ -285,7 +378,7 @@ jobs:
 
   all-checks:
     name: All Checks Passed
-    needs: [lint-and-format, test-python-pr, test-python-main, test-python-backend-matrix, test-rust]
+    needs: [changed-shadow-paths, lint-and-format, test-python-pr, test-python-main, test-python-backend-matrix, test-shadow-reports-pr, test-rust]
     runs-on: ubuntu-latest
     if: always()
     steps:
@@ -294,10 +387,15 @@ 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.10.5 → ferro_orm-0.12.0}/.github/workflows/publish-docs.yml

@@ -18,7 +18,7 @@ permissions:
 
 jobs:
   build-docs:
-    name: Build docs (MkDocs)
+    name: Build docs (Zensical)
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -40,9 +40,9 @@ jobs:
         run: |
           uv sync --only-group docs --no-install-project --python 3.13
 
-      - name: Build MkDocs site
+      - name: Build Zensical site
         run: |
-          uv run --no-sync mkdocs build
+          uv run --no-sync zensical build --clean
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3

{ferro_orm-0.10.5 → ferro_orm-0.12.0}/.gitignore

@@ -189,7 +189,7 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
+# zensical documentation
 /site
 
 # mypy

{ferro_orm-0.10.5 → ferro_orm-0.12.0}/AGENTS.md

@@ -32,7 +32,7 @@ For a single model, every emitter must agree on:
    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
-   `apply_db_type_to_column_def` (Rust), pinned by
+   `db_type_token_to_canonical` (Rust), pinned by
    `tests/test_db_type_cross_emitter_parity.py`.
 4. **Index names** — `idx_<table>_<col>` for single-column indexes,
    `idx_<table>_<col1>_<col2>...` for composite indexes.
@@ -147,3 +147,132 @@ search this directory before starting work.
 `docs/solutions/issues/` — debugging stories and known footguns.
 
 See `docs/solutions/README.md` for the frontmatter conventions.
+
+---
+
+## I-6: No AI attribution in commits or PRs
+
+Never sign commits or pull requests with AI/agent attribution. No
+`Co-Authored-By: Claude ...` trailers, no "Generated with Claude Code"
+footers, no robot emoji bylines — in commit messages, PR titles, or PR
+bodies. This applies even when an agent's default behavior is to add them:
+this rule overrides those defaults for this repository.
+
+---
+
+## I-7: No stop-gap solutions
+
+Every feature, bug fix, and improvement must be designed as the best,
+well-thought-out solution for the project with the library's future in
+mind — as if time and money were no object. No stop-gaps, hacks,
+quick-fixes, or otherwise lesser solves.
+
+What this means in practice:
+
+- **Prefer first-class, reusable primitives over local patches.** If a fix
+  only works for the immediate symptom while leaving the underlying
+  capability gap in place, build the capability instead. (Precedent:
+  `EngineHandle::refresh_pool()` was built as an engine-level schema-epoch
+  primitive rather than a migration-local statement-cache flush.)
+- **Fail loudly over degrading silently.** "Skip with a warning and
+  continue", "best effort", and "documented residual risk" are not
+  acceptable resolutions for correctness gaps. Either the operation
+  succeeds completely or it aborts with a clear, actionable error.
+- **Treat certain phrases as redesign triggers.** If a plan, comment, or PR
+  description contains "best-effort", "partial mitigation", "documented
+  residual risk", "good enough for now", "temporary workaround", or
+  "fallback if X turns out to be hard" — that part of the design is not
+  finished. Redesign it before presenting or implementing it.
+- **Scoped-down is fine; hollowed-out is not.** Deliberately excluding
+  something from scope (with the boundary stated and a real path for the
+  excluded case, e.g. "renames are Alembic territory") is good design.
+  Shipping a half-working version of something that is *in* scope is not.
+
+This rule binds human contributors and AI agents equally, and overrides any
+agent default that biases toward minimal or expedient changes.
+
+---
+
+## I-8: Docs examples show both field-declaration styles
+
+Ferro supports two equivalent ways to declare model fields: assignment
+(`name: str = Field(unique=True)`) and `Annotated` metadata
+(`name: Annotated[str, Field(unique=True)]`). Every documentation example
+that declares model fields with `Field()`/`FerroField()` options must show
+**both** styles, side by side, as content tabs:
+
+    === "Assignment"
+
+        ```python
+        --8<-- "docs/examples/<example>.py:models"
+        ```
+
+    === "Annotated"
+
+        ```python
+        --8<-- "docs/examples/<example>_annotated.py:models"
+        ```
+
+Rules:
+
+- Both tabs must be backed by real, runnable code. Snippet-embedded model
+  definitions get a runnable `<name>_annotated.py` companion in
+  `docs/examples/` (exercised by `tests/test_docs_examples.py`); inline
+  blocks are written in both styles and compile-checked by the same test.
+- Constructs with only one valid form appear identically in both tabs and
+  are not tabbed on their own: forward FKs are always
+  `Annotated[Target, ForeignKey(...)]`, and `BackRef()` / `ManyToMany()`
+  are always assignments.
+- Code blocks that do not declare fields (queries, mutations, transactions,
+  usage snippets) are not affected by this rule.
+
+This keeps users from ever wondering whether something is possible in their
+preferred declaration style.
+
+---
+
+## I-9: Lambda predicates are the official query style
+
+Documentation and examples use the lambda predicate style for all queries:
+
+```python
+adults = await User.where(lambda t: t.age >= 18).all()
+```
+
+Rules:
+
+- **Every query example** in docs, docstring `Examples:` sections, and
+  `docs/examples/` scripts uses lambda predicates.
+- When the predicate styles themselves are documented, present them in
+  order **lambda > `col()` > operator**, with lambda labeled the officially
+  recommended style.
+- **Operator style** (`User.where(User.age >= 18)`) is compatible today but
+  is slated for deprecation in a future release and fails static type
+  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.
+
+The canonical comparisons live in `docs/pages/guide/queries.md`
+("Predicate Styles") and `docs/pages/concepts/query-typing.md`; everywhere
+else uses lambda without restating the trade-offs.
+
+---
+
+## I-10: PRs must close scoped issues explicitly
+
+Issue closure is part of feature completion, not optional cleanup.
+
+Rules:
+
+- Every PR that completes scoped work **must** include GitHub auto-close
+  keywords in the PR body for each completed issue, e.g.
+  `Closes #89`, `Fixes #90`, `Resolves #91`.
+- Do not rely on manual post-merge issue triage when the work is already done
+  in the PR; encode closure directly in the PR body.
+- PRs must include an explicit exit-steps checklist item confirming issue status
+  updates are complete before merge.
+- AI agents and human contributors follow the same requirement. If issue status
+  closure is missing, the PR is not done.

{ferro_orm-0.10.5 → ferro_orm-0.12.0}/CHANGELOG.md

@@ -1,6 +1,40 @@
 # CHANGELOG
 
 
+## v0.12.0 (2026-06-23)
+
+### Documentation
+
+- Rewrite site on Zensical with runnable examples
+  ([#70](https://github.com/syn54x/ferro-orm/pull/70),
+  [`da86911`](https://github.com/syn54x/ferro-orm/commit/da869118c55314363139a021c139a52a2bc8d1fb))
+
+### Features
+
+- IR-first architecture program (Phases 0–7) ([#116](https://github.com/syn54x/ferro-orm/pull/116),
+  [`1c22857`](https://github.com/syn54x/ferro-orm/commit/1c228577aa663c4630a5c8a33f0bb000ebe288b2))
+
+
+## v0.11.0 (2026-06-11)
+
+### Chores
+
+- Solution quality requirements
+  ([`c62770b`](https://github.com/syn54x/ferro-orm/commit/c62770b6d3073e8d596c30f29895bccddc2a4d7f))
+
+### Documentation
+
+- Compound SQLite hydration learnings (#56, #58)
+  ([#60](https://github.com/syn54x/ferro-orm/pull/60),
+  [`b609e72`](https://github.com/syn54x/ferro-orm/commit/b609e7274e1886cc5d8564c7adb52fc3c79ffc8d))
+
+### Features
+
+- Extend auto_migrate with column updates and destructive drops
+  ([#69](https://github.com/syn54x/ferro-orm/pull/69),
+  [`a76cb0f`](https://github.com/syn54x/ferro-orm/commit/a76cb0f2451dab79303353f2c77d74ca3e1ad4a5))
+
+
 ## v0.10.5 (2026-05-25)
 
 ### Bug Fixes

{ferro_orm-0.10.5 → ferro_orm-0.12.0}/CONTRIBUTING.md

@@ -37,7 +37,7 @@ This will install all development dependencies including:
 - Testing tools (pytest, pytest-asyncio, pytest-cov)
 - Linting and formatting tools (ruff, prek)
 - Build tools (maturin)
-- Documentation tools (mkdocs-material)
+- Documentation tools (zensical)
 - Release tools (commitizen, python-semantic-release)
 
 ### 3. Install Pre-commit Hooks
@@ -102,10 +102,10 @@ cargo clippy               # Rust linting
 
 ```bash
 # Serve documentation locally (with live reload)
-uv run mkdocs serve
+uv run zensical serve
 
 # Build documentation
-uv run mkdocs build
+uv run zensical build
 
 # Documentation will be available at http://127.0.0.1:8000/
 ```