ci: add GitHub Actions workflow with pytest suite and consumer integration

Validates the library end-to-end without publishing:

Test job (matrix 3.12 / 3.13 / 3.14)
  - Installs the project with [dev] extras into an isolated venv
  - Runs pytest covering smoke imports, basic CRUD, and the STI
    default-isolation regression

Consumer-integration job (matrix 3.12 / 3.13 / 3.14)
  - Builds wheel + sdist via python -m build
  - Installs the wheel (only + aiosqlite) into a clean venv with no
    dev dependencies, mimicking a PyPI consumer
  - Runs examples/consumer_integration/run.py which exercises STI
    behaviour against async SQLite and fails fast on any assertion

Regression coverage for the 0.3.2 fix (clearing SA defaults on STI
shared columns) is asserted at both metadata and runtime layers so any
reintroduction of the leak breaks CI on every PR.

Author: Foxerine

.github/workflows/ci.yml

@@ -0,0 +1,100 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # -------------------------------------------------------------------
+  # Job 1: source-tree tests across supported Python versions.
+  # Uses uv sync so the lockfile is honoured and runs are reproducible.
+  # -------------------------------------------------------------------
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Create venv and install project with dev extras
+        # Dev extras: pytest, pytest-asyncio, aiosqlite, ruff. Editable install
+        # keeps the wheel build separate for the consumer-integration job.
+        run: |
+          uv venv --python ${{ matrix.python-version }} .venv
+          uv pip install --python .venv/bin/python -e ".[dev]"
+
+      - name: Run pytest
+        run: .venv/bin/python -m pytest tests/ -v
+
+  # -------------------------------------------------------------------
+  # Job 2: build wheel + sdist, then install the wheel into a clean
+  # virtualenv with zero dev deps and run the consumer integration
+  # script. This simulates an external PyPI consumer.
+  # -------------------------------------------------------------------
+  consumer-integration:
+    name: consumer integration (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    needs: test
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Build wheel and sdist
+        run: uv tool run --from build python -m build
+
+      - name: Create isolated consumer venv
+        run: uv venv --python ${{ matrix.python-version }} /tmp/consumer-env
+
+      - name: Install built wheel (no dev deps, only the wheel + aiosqlite driver)
+        run: uv pip install --python /tmp/consumer-env/bin/python dist/*.whl aiosqlite
+
+      - name: Confirm installed version matches wheel
+        run: |
+          /tmp/consumer-env/bin/python -c "import sqlmodel_ext; print('installed:', sqlmodel_ext.__version__ if hasattr(sqlmodel_ext, '__version__') else '(no __version__)')"
+
+      - name: Run consumer integration scenario
+        run: /tmp/consumer-env/bin/python examples/consumer_integration/run.py
+
+      - name: Upload distribution artifacts
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+          retention-days: 14

examples/consumer_integration/run.py

@@ -0,0 +1,148 @@
+"""
+Consumer-side integration test.
+
+Runs from a clean virtualenv that has ONLY the built sqlmodel-ext wheel
+installed (plus aiosqlite for the async SQLite driver). Simulates what an
+external PyPI consumer experiences: if this script passes, the wheel is
+well-formed and the STI default-isolation fix behaves end-to-end.
+
+Exits with status 0 on success, non-zero on any failed assertion. Intended
+to be invoked directly by CI:
+
+    python -m pip install dist/*.whl aiosqlite
+    python examples/consumer_integration/run.py
+"""
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlalchemy.orm import configure_mappers
+from sqlmodel import SQLModel
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from sqlmodel_ext import (
+    AutoPolymorphicIdentityMixin,
+    PolymorphicBaseMixin,
+    SQLModelBase,
+    UUIDTableBaseMixin,
+    register_sti_column_properties_for_all_subclasses,
+    register_sti_columns_for_all_subclasses,
+)
+
+
+# ---------- STI model hierarchy ----------
+
+class Tool(SQLModelBase, UUIDTableBaseMixin, PolymorphicBaseMixin, table=True):
+    """Shared STI parent table."""
+    name: str
+
+
+class ExportFunction(Tool, AutoPolymorphicIdentityMixin, table=True):
+    """Declares ``max_size`` with a large realistic default."""
+    # 5 GiB chosen because the real-world production bug used exactly this value.
+    max_size: int = 5 * 1024 * 1024 * 1024
+
+
+class UploadFunction(Tool, AutoPolymorphicIdentityMixin, table=True):
+    """Declares a different default for a different field."""
+    allow_overwrite: bool = True
+
+
+class NoOpFunction(Tool, AutoPolymorphicIdentityMixin, table=True):
+    """The sibling with zero own fields - the purest victim of default leaks."""
+    pass
+
+
+# ---------- Integration scenario ----------
+
+FIVE_GIB = 5 * 1024 * 1024 * 1024
+
+
+def fail(msg: str) -> None:
+    print(f"[FAIL] {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+async def main() -> None:
+    # STI two-phase registration (public API contract).
+    register_sti_columns_for_all_subclasses()
+    configure_mappers()
+    register_sti_column_properties_for_all_subclasses()
+
+    # --- Layer 1: metadata assertions ---
+    shared = Tool.__table__.columns
+    if shared["max_size"].default is not None:
+        fail(
+            f"tool.max_size.default should be None (fix cleared the shared SA "
+            f"default). Got: {shared['max_size'].default!r}"
+        )
+    if shared["max_size"].server_default is not None:
+        fail(f"tool.max_size.server_default should be None")
+    if shared["allow_overwrite"].default is not None:
+        fail(
+            f"tool.allow_overwrite.default should be None. "
+            f"Got: {shared['allow_overwrite'].default!r}"
+        )
+
+    # Pydantic field-level defaults must still be intact.
+    if ExportFunction.model_fields["max_size"].default != FIVE_GIB:
+        fail(
+            f"Pydantic default for ExportFunction.max_size was wiped by the fix: "
+            f"{ExportFunction.model_fields['max_size'].default!r}"
+        )
+
+    # --- Layer 2: behavioural assertions via real async SQLite ---
+    engine = create_async_engine("sqlite+aiosqlite:///:memory:")
+    try:
+        async with engine.begin() as conn:
+            await conn.run_sync(SQLModel.metadata.create_all)
+
+        async with AsyncSession(engine) as session:
+            # NoOpFunction does not declare max_size; the shared column must be NULL.
+            noop = NoOpFunction(name="noop")
+            noop = await noop.save(session)
+            result = await session.execute(
+                select(Tool.__table__.c.max_size).where(Tool.__table__.c.id == noop.id)
+            )
+            stored = result.scalar_one()
+            if stored is not None:
+                fail(
+                    f"NoOpFunction.max_size should be NULL (bug: sibling default "
+                    f"leaked from ExportFunction). Got: {stored!r}"
+                )
+
+            # UploadFunction also does not declare max_size.
+            upload = UploadFunction(name="upload")
+            upload = await upload.save(session)
+            result = await session.execute(
+                select(Tool.__table__.c.max_size).where(Tool.__table__.c.id == upload.id)
+            )
+            stored = result.scalar_one()
+            if stored is not None:
+                fail(
+                    f"UploadFunction.max_size should be NULL. Got: {stored!r}"
+                )
+
+            # Happy path: declaring subclass still persists its own Pydantic default.
+            export = ExportFunction(name="export")
+            export = await export.save(session)
+            result = await session.execute(
+                select(Tool.__table__.c.max_size).where(Tool.__table__.c.id == export.id)
+            )
+            stored = result.scalar_one()
+            if stored != FIVE_GIB:
+                fail(
+                    f"ExportFunction.max_size should be {FIVE_GIB}. Got: {stored!r} "
+                    f"- fix may have broken the declaring subclass's default path."
+                )
+    finally:
+        await engine.dispose()
+
+    print("[OK] sqlmodel-ext consumer integration test passed")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

tests/__init__.py

@@ -0,0 +1,45 @@
+"""
+Synthetic STI hierarchy used by regression tests.
+
+Intentionally placed outside any test function so the polymorphic metaclass
+queues the classes onto ``_sti_subclasses_to_register`` at import time. The
+conftest fixture drives the two-phase registration and schema creation.
+
+Hierarchy:
+    Tool (STI root, has its own table)
+    +-- FunctionA   - declares ``max_files`` with default 100
+    +-- FunctionB   - declares ``timeout`` with default 30
+    +-- FunctionC   - declares nothing extra (sibling with no own fields)
+
+The STI bug under regression: FunctionA's Pydantic default 100 would leak
+into the shared ``tool.max_files`` SA Column.default. Inserting a FunctionB
+or FunctionC row would then silently materialise ``max_files = 100`` in
+the sibling row because the ORM falls back to ``Column.default`` when the
+attribute is absent from the sibling's ``__dict__``.
+"""
+from sqlmodel_ext import (
+    AutoPolymorphicIdentityMixin,
+    PolymorphicBaseMixin,
+    SQLModelBase,
+    UUIDTableBaseMixin,
+)
+
+
+class Tool(SQLModelBase, UUIDTableBaseMixin, PolymorphicBaseMixin, table=True):
+    """STI root: all subclasses share this single ``tool`` table."""
+    name: str
+
+
+class FunctionA(Tool, AutoPolymorphicIdentityMixin, table=True):
+    """Sibling with a field carrying a non-None Pydantic default."""
+    max_files: int = 100
+
+
+class FunctionB(Tool, AutoPolymorphicIdentityMixin, table=True):
+    """Sibling with its own non-overlapping field + default."""
+    timeout: int = 30
+
+
+class FunctionC(Tool, AutoPolymorphicIdentityMixin, table=True):
+    """Sibling with no additional fields - the purest victim of default leaks."""
+    pass

tests/_models.py

@@ -0,0 +1,58 @@
+"""
+Pytest fixtures for sqlmodel-ext tests.
+
+Uses aiosqlite (in-memory) so tests never touch a real database.
+"""
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+
+import pytest
+import pytest_asyncio
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
+from sqlalchemy.orm import configure_mappers
+from sqlmodel import SQLModel
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from sqlmodel_ext import (
+    register_sti_column_properties_for_all_subclasses,
+    register_sti_columns_for_all_subclasses,
+)
+
+# Import test models so the STI metaclass queues them before phase 1 runs.
+from tests import _models  # noqa: F401  -- imported for side effects
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _register_sti() -> None:
+    """Run the STI two-phase registration exactly once per session.
+
+    Phase 1 must run before ``configure_mappers()``, phase 2 after.
+    Calling this more than once is idempotent because the queue is drained
+    but SA mapper configuration short-circuits already-configured mappers.
+    """
+    register_sti_columns_for_all_subclasses()
+    configure_mappers()
+    register_sti_column_properties_for_all_subclasses()
+
+
+@pytest_asyncio.fixture
+async def engine() -> AsyncIterator[AsyncEngine]:
+    """Fresh in-memory async SQLite engine per test.
+
+    Each test gets a brand-new database so state never leaks between tests.
+    """
+    eng = create_async_engine("sqlite+aiosqlite:///:memory:", future=True)
+    async with eng.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+    try:
+        yield eng
+    finally:
+        await eng.dispose()
+
+
+@pytest_asyncio.fixture
+async def session(engine: AsyncEngine) -> AsyncIterator[AsyncSession]:
+    """Async session bound to the fresh engine."""
+    async with AsyncSession(engine) as s:
+        yield s