ferro-orm 0.2.1__tar.gz → 0.3.0__tar.gz

ferro_orm-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,491 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      prerelease:
+        description: 'Create a pre-release'
+        required: false
+        type: boolean
+        default: false
+
+concurrency:
+  group: release-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  ci-gate:
+    name: CI Gate
+    uses: ./.github/workflows/ci.yml
+
+  packaging-smoke:
+    name: Packaging Smoke Gate
+    uses: ./.github/workflows/packaging-smoke.yml
+
+  # Bump versions and changelog locally only; export a patch so every later job
+  # validates the exact tree that would be released. Nothing is pushed until
+  # publish-github-release after wheels, sdist, tests, and docs all pass.
+  prepare-release:
+    name: Prepare release (no push)
+    needs: [ci-gate, packaging-smoke]
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.verify_release.outputs.release_created }}
+      release_base_sha: ${{ steps.base_sha.outputs.release_base_sha }}
+      release_tag: ${{ steps.verify_release.outputs.release_tag }}
+      release_version: ${{ steps.verify_release.outputs.release_version }}
+    permissions:
+      contents: read
+      issues: read
+      pull-requests: read
+
+    steps:
+      - name: Record workflow base SHA
+        id: base_sha
+        run: echo "release_base_sha=${{ github.sha }}" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - 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: Install dependencies
+        run: |
+          uv sync --only-group release --no-install-project --python 3.13
+
+      - name: Run semantic-release (local bump only)
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
+        run: |
+          PRERELEASE_FLAG=""
+          if [ "${{ github.event.inputs.prerelease }}" == "true" ]; then
+            PRERELEASE_FLAG="--prerelease"
+          fi
+
+          # Writes version files + CHANGELOG only; no commit, push, tag, or VCS
+          # release. --skip-build defers packaging to validation jobs.
+          uv run semantic-release version $PRERELEASE_FLAG \
+            --no-vcs-release --no-tag --no-commit --no-push --skip-build
+
+      - name: Verify release candidate and write patch
+        id: verify_release
+        shell: bash
+        run: |
+          set -euo pipefail
+          # Normalize to a single index-vs-HEAD patch (stable for git apply on runners).
+          git add -A
+          git diff --cached HEAD > release.patch
+
+          if [[ ! -s release.patch ]]; then
+            echo "No semantic version bump in this run (index matches HEAD)."
+            echo "release_created=false" >> "$GITHUB_OUTPUT"
+            echo "changelog_validated=skipped" >> "$GITHUB_OUTPUT"
+            echo "release_tag=" >> "$GITHUB_OUTPUT"
+            echo "release_version=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          if ! grep -qE '^diff --git a/CHANGELOG\.md b/CHANGELOG\.md' release.patch; then
+            echo "WARNING: expected CHANGELOG.md to change for a release bump."
+            echo "release_created=false" >> "$GITHUB_OUTPUT"
+            echo "changelog_validated=missing" >> "$GITHUB_OUTPUT"
+            echo "release_tag=" >> "$GITHUB_OUTPUT"
+            echo "release_version=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          VERSION="$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")"
+          echo "release_created=true" >> "$GITHUB_OUTPUT"
+          echo "changelog_validated=passed" >> "$GITHUB_OUTPUT"
+          echo "release_tag=v${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "release_version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Prepared v${VERSION} as patch against ${{ github.sha }}"
+
+      - name: Upload release patch
+        if: steps.verify_release.outputs.release_created == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-patch
+          path: release.patch
+
+      - name: Release summary
+        if: always()
+        shell: bash
+        run: |
+          {
+            echo "## Release workflow summary"
+            echo ""
+            echo "- Trigger: \`${{ github.event_name }}\`"
+            echo "- Base ref: \`${{ github.ref_name }}\` @ \`${{ github.sha }}\`"
+            echo "- Release candidate prepared: \`${{ steps.verify_release.outputs.release_created || 'unknown' }}\`"
+            echo "- Changelog validation: \`${{ steps.verify_release.outputs.changelog_validated || 'unknown' }}\`"
+            echo "- Tag if published: \`${{ steps.verify_release.outputs.release_tag || 'n/a' }}\`"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  # Build and publish jobs are inlined here (not in a reusable workflow) so that
+  # PyPI Trusted Publishing sees workflow_ref = release.yml. Reusable workflows
+  # are not supported by PyPI Trusted Publishing.
+  build-wheels:
+    name: Build wheels (${{ matrix.platform.name }})
+    needs: [prepare-release]
+    if: needs.prepare-release.outputs.release_created == 'true'
+    runs-on: ${{ matrix.platform.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        platform:
+          - name: linux-x86_64
+            runner: ubuntu-latest
+            target: x86_64
+            manylinux: auto
+          - name: linux-aarch64
+            runner: ubuntu-latest
+            target: aarch64
+            manylinux: auto
+          - name: macos-aarch64
+            runner: macos-latest
+            target: aarch64
+            manylinux: ''
+          - name: windows-x64
+            runner: windows-latest
+            target: x64
+            manylinux: ''
+
+    steps:
+      - name: Disable Git CRLF conversion before checkout
+        shell: bash
+        run: git config --global core.autocrlf false
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.prepare-release.outputs.release_base_sha }}
+
+      - name: Download release patch
+        uses: actions/download-artifact@v4
+        with:
+          name: release-patch
+          path: release-patch
+
+      - name: Apply release patch
+        shell: bash
+        run: |
+          git config core.autocrlf false
+          git apply release-patch/release.patch
+          rm -rf release-patch
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Build wheels
+        uses: PyO3/maturin-action@v1.48.0
+        with:
+          target: ${{ matrix.platform.target }}
+          args: --release --out dist --find-interpreter
+          manylinux: ${{ matrix.platform.manylinux }}
+          sccache: 'true'
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.platform.name }}
+          path: dist/*.whl
+
+  build-sdist:
+    name: Build sdist
+    needs: [prepare-release]
+    if: needs.prepare-release.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Disable Git CRLF conversion before checkout
+        shell: bash
+        run: git config --global core.autocrlf false
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.prepare-release.outputs.release_base_sha }}
+
+      - name: Download release patch
+        uses: actions/download-artifact@v4
+        with:
+          name: release-patch
+          path: release-patch
+
+      - name: Apply release patch
+        shell: bash
+        run: |
+          git config core.autocrlf false
+          git apply release-patch/release.patch
+          rm -rf release-patch
+
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1.48.0
+        with:
+          command: sdist
+          args: --out dist
+
+      - name: Upload sdist
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  test-wheels:
+    name: Test wheels (${{ matrix.os }})
+    needs: [prepare-release, build-wheels]
+    if: needs.prepare-release.outputs.release_created == 'true'
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    steps:
+      - name: Disable Git CRLF conversion before checkout
+        shell: bash
+        run: git config --global core.autocrlf false
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.prepare-release.outputs.release_base_sha }}
+
+      - name: Download release patch
+        uses: actions/download-artifact@v4
+        with:
+          name: release-patch
+          path: release-patch
+
+      - name: Apply release patch
+        shell: bash
+        run: |
+          git config core.autocrlf false
+          git apply release-patch/release.patch
+          rm -rf release-patch
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Download wheels
+        uses: actions/download-artifact@v4
+        with:
+          path: dist
+          pattern: wheels-*
+          merge-multiple: true
+
+      - name: Install wheel
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --find-links dist ferro-orm
+
+      - name: Test import
+        shell: bash
+        run: |
+          python -c "import ferro; print('Ferro imported successfully')"
+
+      - name: Run basic smoke test
+        shell: bash
+        run: |
+          python -c "
+          import asyncio
+          from ferro import Model, FerroField, connect
+          from typing import Annotated
+
+          class TestModel(Model):
+              id: Annotated[int, FerroField(primary_key=True)]
+              name: str
+
+          async def test():
+              await connect('sqlite::memory:')
+              print('Connection test passed')
+
+          asyncio.run(test())
+          "
+
+  verify-docs:
+    name: Verify documentation build
+    needs: [prepare-release]
+    if: needs.prepare-release.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Disable Git CRLF conversion before checkout
+        shell: bash
+        run: git config --global core.autocrlf false
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.prepare-release.outputs.release_base_sha }}
+
+      - name: Download release patch
+        uses: actions/download-artifact@v4
+        with:
+          name: release-patch
+          path: release-patch
+
+      - name: Apply release patch
+        shell: bash
+        run: |
+          git config core.autocrlf false
+          git apply release-patch/release.patch
+          rm -rf release-patch
+
+      - 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: Install documentation dependencies
+        run: |
+          uv sync --only-group docs --no-install-project --python 3.13
+
+      - name: Build MkDocs site
+        run: |
+          uv run --no-sync mkdocs build
+
+  publish-github-release:
+    name: Commit, tag, and create GitHub Release
+    needs: [prepare-release, build-wheels, build-sdist, test-wheels, verify-docs]
+    if: needs.prepare-release.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Disable Git CRLF conversion before checkout
+        shell: bash
+        run: git config --global core.autocrlf false
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.prepare-release.outputs.release_base_sha }}
+          fetch-depth: 0
+          ssh-key: ${{ secrets.RELEASE_DEPLOY_KEY }}
+          # Required so the deploy key stays loaded for git push in the next step.
+          persist-credentials: true
+
+      - name: Download release patch
+        uses: actions/download-artifact@v4
+        with:
+          name: release-patch
+          path: release-patch
+
+      - name: Apply release patch and push release commit
+        env:
+          VERSION: ${{ needs.prepare-release.outputs.release_version }}
+          TAG: ${{ needs.prepare-release.outputs.release_tag }}
+        run: |
+          set -euo pipefail
+          git config core.autocrlf false
+          git apply release-patch/release.patch
+          rm -rf release-patch
+
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git config user.name "github-actions[bot]"
+          git remote set-url origin "git@github.com:${{ github.repository }}.git"
+
+          if git ls-remote --tags origin "refs/tags/${TAG}" | grep -q .; then
+            echo "ERROR: tag ${TAG} already exists on the remote."
+            exit 1
+          fi
+
+          git add -A
+          git commit --author="semantic-release <semantic-release@github.com>" \
+            -m "chore(release): ${VERSION}" \
+            -m "Automatically generated by python-semantic-release"
+          git push origin "HEAD:refs/heads/${{ github.ref_name }}"
+
+          git tag "${TAG}"
+          git push origin "refs/tags/${TAG}"
+
+      # semantic-release matches branch config (e.g. branches.main); detached HEAD fails with
+      # "Detached HEAD state cannot match any release groups".
+      - name: Attach HEAD to branch for semantic-release
+        run: git switch -C "${{ github.ref_name }}"
+
+      - 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 dependencies
+        uses: Swatinem/rust-cache@v2
+        with:
+          prefix-key: "v1-rust"
+
+      - name: Install dependencies
+        run: |
+          uv sync --only-group release --no-install-project --python 3.13
+
+      - name: Publish GitHub release (assets + VCS release)
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
+        run: |
+          uv run semantic-release publish --tag "${{ needs.prepare-release.outputs.release_tag }}"
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [prepare-release, publish-github-release]
+    if: needs.prepare-release.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ferro-orm
+    permissions:
+      id-token: write
+    steps:
+      - name: Download sdist
+        uses: actions/download-artifact@v4
+        with:
+          name: sdist
+          path: dist
+
+      - name: Download wheels
+        uses: actions/download-artifact@v4
+        with:
+          pattern: wheels-*
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+          verbose: true
+
+  deploy-docs:
+    name: Deploy Documentation
+    needs: [prepare-release, publish-pypi]
+    if: needs.prepare-release.outputs.release_created == 'true'
+    uses: ./.github/workflows/publish-docs.yml
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    with:
+      ref: ${{ needs.prepare-release.outputs.release_tag }}

{ferro_orm-0.2.1 → ferro_orm-0.3.0}/.gitignore

@@ -243,3 +243,5 @@ playground.ipynb
 IMPLEMENTATION.md
 Cargo.lock
 demo.db
+docs/superpowers/plans/2026-04-22-shadow-fk-types.md
+docs/superpowers/specs/2026-04-22-shadow-fk-types-design.md

{ferro_orm-0.2.1 → ferro_orm-0.3.0}/CHANGELOG.md

@@ -1,6 +1,60 @@
 # CHANGELOG
 
 
+## v0.3.0 (2026-04-22)
+
+### Bug Fixes
+
+- Align composite unique index names and harden Alembic/Rust handling
+  ([`3350481`](https://github.com/syn54x/ferro-orm/commit/33504812d37d93bf69c2be8f6bee6f390803a460))
+
+- Refresh Pydantic FieldInfo when reconciling shadow FK types
+  ([`6cf1ac8`](https://github.com/syn54x/ferro-orm/commit/6cf1ac8c2e361df8de11795a8151c34d17a39445))
+
+### Chores
+
+- Remove doc
+  ([`16e4028`](https://github.com/syn54x/ferro-orm/commit/16e4028f72fc47109b2511d1feb23811c831f32c))
+
+### Continuous Integration
+
+- Fix release
+  ([`688d01b`](https://github.com/syn54x/ferro-orm/commit/688d01bdae0aff1f82e4a1bb60dd1b8ab35e1d01))
+
+- Fix release
+  ([`249e460`](https://github.com/syn54x/ferro-orm/commit/249e46058bac87215920083a9d45557f3c58b62f))
+
+- Fix release
+  ([`888e15e`](https://github.com/syn54x/ferro-orm/commit/888e15eff693d1e1bfa279d809e790e52cd7ce25))
+
+- Fix release
+  ([`58bb5b2`](https://github.com/syn54x/ferro-orm/commit/58bb5b2b0962481b3cfbf3ffbe6c6a2653b213c0))
+
+- Reorder release steps to prevent tagging before checks are complete
+  ([`ad1fd8d`](https://github.com/syn54x/ferro-orm/commit/ad1fd8d5ba08bdd7a1bcd257fff3fc12ff458c12))
+
+### Documentation
+
+- Complete documentation restructure and implementation summary
+  ([`937e75e`](https://github.com/syn54x/ferro-orm/commit/937e75ee7b5c526aca776dd8409f9e0df5f0e892))
+
+- Enhance shadow field documentation and clarify relationship resolution process
+  ([`1d350fd`](https://github.com/syn54x/ferro-orm/commit/1d350fd728310a5b9a24f129986f873a84a8592f))
+
+### Features
+
+- Composite unique constraints and default M2M pair uniqueness
+  ([`dc12880`](https://github.com/syn54x/ferro-orm/commit/dc12880b7b8676c088183edf1f32b48a36314448))
+
+- Derive shadow FK types from related PK and reconcile after resolve
+  ([`d3ae486`](https://github.com/syn54x/ferro-orm/commit/d3ae4862858ccd51f62d62a939e6a90b8efb8980))
+
+### Testing
+
+- UUID FK save reparenting and bulk_create coverage
+  ([`6c93cea`](https://github.com/syn54x/ferro-orm/commit/6c93cea7906ac264b266342ecf71602c7aff6ed6))
+
+
 ## v0.2.1 (2026-04-20)
 
 ### Bug Fixes

{ferro_orm-0.2.1 → ferro_orm-0.3.0}/Cargo.lock

@@ -294,7 +294,7 @@ dependencies = [
 
 [[package]]
 name = "ferro"
-version = "0.2.1"
+version = "0.3.0"
 dependencies = [
  "dashmap",
  "once_cell",

{ferro_orm-0.2.1 → ferro_orm-0.3.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ferro"
-version = "0.2.1"
+version = "0.3.0"
 edition = "2024"
 readme = "README.md"
 

{ferro_orm-0.2.1 → ferro_orm-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ferro-orm
-Version: 0.2.1
+Version: 0.3.0
 Requires-Dist: pydantic>=2.0
 License-File: LICENSE
 Summary: A high-performance, Rust-backed ORM for Python.

{ferro_orm-0.2.1 → ferro_orm-0.3.0}/docs/concepts/architecture.md

@@ -68,7 +68,7 @@ graph TB
 - Async runtime integration
 
 **Data formats:**
-- JSON schema (models → Rust)
+- JSON schema (models → Rust), including Ferro-specific table-level keys such as `ferro_composite_uniques` alongside per-column metadata in `properties`
 - Query AST (filters, joins → Rust)
 - Binary rows (Rust → Python)
 

{ferro_orm-0.2.1 → ferro_orm-0.3.0}/docs/guide/migrations.md

@@ -61,6 +61,10 @@ alembic revision --autogenerate -m "Initial schema"
 
 Alembic compares your models to the database and generates a migration script in `migrations/versions/`.
 
+### Composite uniques and Alembic
+
+When you declare `__ferro_composite_uniques__` on a model, Ferro’s `get_metadata()` bridge adds matching SQLAlchemy `UniqueConstraint` objects to the reflected `Table`. Autogenerated revisions will therefore include those constraints (and the same for default many-to-many join tables, which get a composite unique on the two FK columns). Review generated migrations as usual before applying them in production.
+
 ### 4. Review the Migration
 
 Open the generated file in `migrations/versions/xxxx_initial_schema.py`:

{ferro_orm-0.2.1 → ferro_orm-0.3.0}/docs/guide/models-and-fields.md

@@ -76,7 +76,7 @@ Both styles support the same database constraint parameters:
 | :--- | :--- | :--- | :--- |
 | `primary_key` | `bool` | `False` | Marks the field as the primary key for the table. |
 | `autoincrement` | `bool \| None` | `None` | If `True`, the database generates values automatically. Defaults to `True` for integer primary keys. |
-| `unique` | `bool` | `False` | Enforces a uniqueness constraint on the column. |
+| `unique` | `bool` | `False` | Enforces a **single-column** uniqueness constraint on that column only. For uniqueness on a combination of columns, see [Composite unique constraints](#composite-unique-constraints) below. |
 | `index` | `bool` | `False` | Creates a database index for this column to improve query performance. |
 
 #### Examples
@@ -113,6 +113,40 @@ slug: str = Field(unique=True, index=True)
 email: Annotated[str, FerroField(unique=True)]
 ```
 
+### Composite unique constraints
+
+Sometimes a row should be unique **across several columns together** (for example one membership per `(user_id, org_id)` pair). That is a *composite* unique: in SQL this is typically expressed as `UNIQUE (user_id, org_id)` on the table, or an equivalent unique index on those columns.
+
+Ferro does **not** use `FerroField(unique=True)` for that case (`unique=True` is only per column). Instead, set the **`typing.ClassVar`** `__ferro_composite_uniques__` on your model (the base `Model` defines it as `()` so IDEs and type checkers know the hook exists; subclasses override when needed):
+
+```python
+from typing import Annotated, ClassVar
+import uuid
+
+from ferro import Model, FerroField
+
+class OrgMembership(Model):
+    __ferro_composite_uniques__: ClassVar[tuple[tuple[str, ...], ...]] = (
+        ("user_id", "org_id"),
+    )
+
+    id: Annotated[uuid.UUID | None, FerroField(primary_key=True)] = None
+    user_id: Annotated[uuid.UUID, FerroField()]
+    org_id: Annotated[uuid.UUID, FerroField()]
+```
+
+- Each inner tuple lists **database column names** as they appear in the generated schema (the same names as your Pydantic fields for scalar columns; for `ForeignKey("user")` use `user_id` in the tuple).
+- You can list several groups for multiple composite uniques on one model.
+- Invalid or unknown column names raise when the model is registered.
+
+**Null semantics (SQLite):** With the default local SQLite engine, `UNIQUE` treats `NULL` as distinct from other `NULL` values for multi-column constraints unless columns are `NOT NULL`. Ferro maps nullability from your types and defaults like other fields; optional composite columns can therefore allow multiple rows that differ only by `NULL` in a nullable column. Prefer `NOT NULL` on composite members when you need strict “at most one row per pair” semantics. Other databases can differ; consult your backend’s documentation when you target PostgreSQL, MySQL, and so on.
+
+**Wire format:** Declarations use nested tuples in Python; the schema JSON sent to the Rust engine uses nested lists (`ferro_composite_uniques`) because JSON has no tuple type.
+
+**Many-to-many join tables:** When you use `ManyToManyField` without a custom `through` table, Ferro creates a default join table with two foreign-key columns. That table automatically gets a composite unique on those two columns so the same link cannot be stored twice. If you already have duplicate rows in such a table, adding this constraint in a migration may require a data cleanup step first.
+
+See also [Schema management / migrations](migrations.md) for how composite uniques appear in Alembic metadata.
+
 **Indexes:**
 
 ```python
@@ -171,7 +205,7 @@ class Product(Model):
 Ferro uses a custom `ModelMetaclass` to bridge Python and Rust:
 
 1. **Schema Capture**: When you define a class, the metaclass inspects its fields and constraints.
-2. **Rust Registration**: The schema is serialized to a JSON-AST and passed to the Rust core's `MODEL_REGISTRY`.
+2. **Rust Registration**: The schema is serialized to a JSON-AST (including Ferro-specific keys such as `ferro_composite_uniques` when declared) and passed to the Rust core's `MODEL_REGISTRY`.
 3. **Table Generation**: When `auto_migrate=True` is used or `create_tables()` is called, the Rust engine generates the appropriate SQL `CREATE TABLE` statements.
 
 This architecture allows Ferro to leverage Rust's performance for SQL generation and row hydration while maintaining a pure Python interface.