loom-kernel 0.0.0__tar.gz → 0.2.0__tar.gz

loom_kernel-0.2.0/.github/workflows/ci-main.yml

@@ -0,0 +1,113 @@
+name: ci-main
+
+on:
+  push:
+    branches: ["master"]
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    env:
+      SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
+      SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+      SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
+      SONAR_PROJECT_KEY: ${{ vars.SONAR_PROJECT_KEY }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.11"
+
+      - uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3
+
+      - name: Quality report (strict)
+        uses: the-reacher-data/loom-actions/actions/python/quality-report@e731576f4f9cf4ec2b36fddfc895d328c856d29f # v1
+        with:
+          src-dir: src
+          test-dir: tests
+          coverage-threshold: "80"
+          fail-on-quality: "any"
+          fail-on-security: "high"
+          include-security: "true"
+
+      - name: Run pytest with coverage and JUnit output
+        shell: bash
+        run: |
+          set -euo pipefail
+          uv run --with pytest-cov pytest --cov --junitxml=junit.xml -o junit_family=legacy
+
+      - name: Upload coverage to Codecov
+        if: ${{ hashFiles('coverage.xml') != '' }}
+        uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de # v5
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Upload test results to Codecov
+        if: ${{ !cancelled() && hashFiles('junit.xml') != '' }}
+        uses: codecov/test-results-action@0fa95f0e1eeaafde2c782583b36b28ad0d8c77d3 # v1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: SonarQube scan
+        if: ${{ env.SONAR_TOKEN != '' && env.SONAR_HOST_URL != '' && env.SONAR_PROJECT_KEY != '' }}
+        uses: SonarSource/sonarqube-scan-action@2f77a1ec69fb1d595b06f35ab27e97605bdef703 # v5
+        with:
+          args: >
+            -Dsonar.projectKey=${{ env.SONAR_PROJECT_KEY }}
+        env:
+          SONAR_TOKEN: ${{ env.SONAR_TOKEN }}
+          SONAR_HOST_URL: ${{ env.SONAR_HOST_URL }}
+
+      - name: Snyk dependency monitor
+        if: ${{ env.SNYK_TOKEN != '' }}
+        uses: snyk/actions/setup@9adf32b1121593767fc3c057af55b55db032dc04 # master
+        env:
+          SNYK_TOKEN: ${{ env.SNYK_TOKEN }}
+
+      - name: Snyk monitor by dependency scope (core/dev/extras)
+        if: ${{ env.SNYK_TOKEN != '' }}
+        shell: bash
+        env:
+          SNYK_TOKEN: ${{ env.SNYK_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          MANIFEST_DIR="$RUNNER_TEMP/snyk-manifests"
+          mkdir -p "$MANIFEST_DIR"
+
+          uv export --frozen --no-default-groups --no-dev --no-hashes --no-emit-project \
+            -o "$MANIFEST_DIR/requirements-core.txt"
+          uv export --frozen --only-group dev --no-hashes --no-emit-project \
+            -o "$MANIFEST_DIR/requirements-dev.txt"
+
+          for extra in rest sqlalchemy config cache pyspark prometheus celery; do
+            uv export --frozen --no-default-groups --no-dev --extra "$extra" \
+              --no-hashes --no-emit-project \
+              -o "$MANIFEST_DIR/requirements-extra-${extra}.txt"
+          done
+
+          python -m pip install -r "$MANIFEST_DIR/requirements-core.txt"
+          snyk monitor --skip-unresolved \
+            --file="$MANIFEST_DIR/requirements-core.txt" --package-manager=pip \
+            --project-name="loom-py/core" --target-reference="${GITHUB_REF_NAME:-master}"
+          python -m pip install -r "$MANIFEST_DIR/requirements-dev.txt"
+          snyk monitor --skip-unresolved \
+            --file="$MANIFEST_DIR/requirements-dev.txt" --package-manager=pip \
+            --project-name="loom-py/dev" --target-reference="${GITHUB_REF_NAME:-master}"
+
+          for extra in rest sqlalchemy config cache pyspark prometheus celery; do
+            python -m pip install -r "$MANIFEST_DIR/requirements-extra-${extra}.txt"
+            snyk monitor --skip-unresolved \
+              --file="$MANIFEST_DIR/requirements-extra-${extra}.txt" \
+              --package-manager=pip \
+              --project-name="loom-py/extra-${extra}" \
+              --target-reference="${GITHUB_REF_NAME:-master}"
+          done

{loom_kernel-0.0.0 → loom_kernel-0.2.0}/.github/workflows/ci-pr.yml

@@ -15,17 +15,20 @@ jobs:
     env:
       SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
       TEST_PYPI_API_TOKEN: ${{ secrets.TEST_PYPI_API_TOKEN }}
+      SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+      SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
+      SONAR_PROJECT_KEY: ${{ vars.SONAR_PROJECT_KEY }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           fetch-depth: 0
           ref: ${{ github.event.pull_request.head.sha }}
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: "3.11"
 
-      - uses: astral-sh/setup-uv@v3
+      - uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3
 
       - name: Configure uv environment path
         shell: bash
@@ -43,7 +46,7 @@ jobs:
       - name: Quality report (strict gate)
         id: quality
         continue-on-error: true
-        uses: the-reacher-data/loom-actions/actions/python/quality-report@v1
+        uses: the-reacher-data/loom-actions/actions/python/quality-report@e731576f4f9cf4ec2b36fddfc895d328c856d29f # v1
         with:
           src-dir: src
           test-dir: tests
@@ -54,7 +57,7 @@ jobs:
 
       - name: Publish PR quality comment
         if: ${{ always() && steps.quality.outputs.report-file != '' }}
-        uses: the-reacher-data/loom-actions/actions/core/pr-comment-update@v1
+        uses: the-reacher-data/loom-actions/actions/core/pr-comment-update@e731576f4f9cf4ec2b36fddfc895d328c856d29f # v1
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           tags: "<!-- loom-quality-report -->"
@@ -62,7 +65,7 @@ jobs:
 
       - name: Compute candidate prerelease version
         id: version
-        uses: the-reacher-data/loom-actions/actions/release/versioning-branch-semantic@v1
+        uses: the-reacher-data/loom-actions/actions/release/versioning-branch-semantic@e731576f4f9cf4ec2b36fddfc895d328c856d29f # v1
         with:
           branch: ${{ github.head_ref }}
           prerelease: "true"
@@ -70,7 +73,7 @@ jobs:
       - name: Generate changelog preview
         id: changelog
         continue-on-error: true
-        uses: the-reacher-data/loom-actions/actions/release/changelog-conventional-commit@v1
+        uses: the-reacher-data/loom-actions/actions/release/changelog-conventional-commit@e731576f4f9cf4ec2b36fddfc895d328c856d29f # v1
         with:
           mode: "pr"
           branch: ${{ github.event.pull_request.head.sha }}
@@ -81,36 +84,92 @@ jobs:
 
       - name: Publish PR changelog comment
         if: ${{ steps.changelog.outcome == 'success' && steps.changelog.outputs.output_path != '' }}
-        uses: the-reacher-data/loom-actions/actions/core/pr-comment-update@v1
+        uses: the-reacher-data/loom-actions/actions/core/pr-comment-update@e731576f4f9cf4ec2b36fddfc895d328c856d29f # v1
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           tags: "<!-- changelog-preview -->,<!-- branch-source:${{ github.head_ref }} -->"
           body-file: ${{ steps.changelog.outputs.output_path }}
 
+      - name: Run pytest with coverage and JUnit output
+        shell: bash
+        run: |
+          set -euo pipefail
+          uv run --with pytest-cov pytest --cov --junitxml=junit.xml -o junit_family=legacy
+
       - name: Upload coverage to Codecov
         if: ${{ always() && hashFiles('coverage.xml') != '' }}
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de # v5
         with:
           files: ./coverage.xml
           fail_ci_if_error: false
           token: ${{ secrets.CODECOV_TOKEN }}
 
-      - name: Snyk dependency scan
+      - name: Upload test results to Codecov
+        if: ${{ !cancelled() && hashFiles('junit.xml') != '' }}
+        uses: codecov/test-results-action@0fa95f0e1eeaafde2c782583b36b28ad0d8c77d3 # v1
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: SonarQube scan
+        if: ${{ env.SONAR_TOKEN != '' && env.SONAR_HOST_URL != '' && env.SONAR_PROJECT_KEY != '' }}
+        uses: SonarSource/sonarqube-scan-action@2f77a1ec69fb1d595b06f35ab27e97605bdef703 # v5
+        with:
+          args: >
+            -Dsonar.projectKey=${{ env.SONAR_PROJECT_KEY }}
+        env:
+          SONAR_TOKEN: ${{ env.SONAR_TOKEN }}
+          SONAR_HOST_URL: ${{ env.SONAR_HOST_URL }}
+
+      - name: Setup Snyk CLI
+        if: ${{ env.SNYK_TOKEN != '' }}
+        uses: snyk/actions/setup@9adf32b1121593767fc3c057af55b55db032dc04 # master
+
+      - name: Snyk dependency scan by scope (core/dev/extras)
         id: snyk
         if: ${{ env.SNYK_TOKEN != '' }}
         continue-on-error: true
-        uses: snyk/actions/python@master
-        with:
-          command: test
-          args: --severity-threshold=high --all-projects --sarif-file-output=snyk.sarif
+        shell: bash
         env:
           SNYK_TOKEN: ${{ env.SNYK_TOKEN }}
+        run: |
+          set -euo pipefail
 
-      - name: Upload Snyk SARIF to GitHub Security
-        if: ${{ always() && env.SNYK_TOKEN != '' && hashFiles('snyk.sarif') != '' }}
-        uses: github/codeql-action/upload-sarif@v3
-        with:
-          sarif_file: snyk.sarif
+          MANIFEST_DIR="$RUNNER_TEMP/snyk-manifests"
+          mkdir -p "$MANIFEST_DIR"
+
+          uv export --frozen --no-default-groups --no-dev --no-hashes --no-emit-project \
+            -o "$MANIFEST_DIR/requirements-core.txt"
+          uv export --frozen --only-group dev --no-hashes --no-emit-project \
+            -o "$MANIFEST_DIR/requirements-dev.txt"
+
+          for extra in rest sqlalchemy config cache pyspark prometheus celery; do
+            uv export --frozen --no-default-groups --no-dev --extra "$extra" \
+              --no-hashes --no-emit-project \
+              -o "$MANIFEST_DIR/requirements-extra-${extra}.txt"
+          done
+
+          python -m pip install -r "$MANIFEST_DIR/requirements-core.txt"
+          snyk test --severity-threshold=high \
+            --skip-unresolved \
+            --file="$MANIFEST_DIR/requirements-core.txt" \
+            --package-manager=pip \
+            --project-name="loom-py/core"
+
+          python -m pip install -r "$MANIFEST_DIR/requirements-dev.txt"
+          snyk test --severity-threshold=high \
+            --skip-unresolved \
+            --file="$MANIFEST_DIR/requirements-dev.txt" \
+            --package-manager=pip \
+            --project-name="loom-py/dev"
+
+          for extra in rest sqlalchemy config cache pyspark prometheus celery; do
+            python -m pip install -r "$MANIFEST_DIR/requirements-extra-${extra}.txt"
+            snyk test --severity-threshold=high \
+              --skip-unresolved \
+              --file="$MANIFEST_DIR/requirements-extra-${extra}.txt" \
+              --package-manager=pip \
+              --project-name="loom-py/extra-${extra}"
+          done
 
       - name: Publish prerelease package to TestPyPI
         if: ${{ github.event.pull_request.head.repo.full_name == github.repository && env.TEST_PYPI_API_TOKEN != '' && steps.version.outputs.deploy == 'true' }}

loom_kernel-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,82 @@
+name: docs
+
+on:
+  pull_request:
+    branches: ["master"]
+    paths:
+      - "docs/**"
+      - "src/**/*.py"
+      - "README.md"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  push:
+    branches: ["master"]
+    paths:
+      - "docs/**"
+      - "src/**/*.py"
+      - "README.md"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+# Prevent concurrent deploys; let an in-progress run finish.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    # contents: read is scoped here — build does not need pages or id-token.
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.11"
+
+      - uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3
+
+      - name: Build docs (strict)
+        shell: bash
+        run: |
+          set -euo pipefail
+          uv run \
+            --extra rest \
+            --extra sqlalchemy \
+            --extra cache \
+            --extra config \
+            --extra prometheus \
+            --with 'sphinx>=8.0' \
+            --with 'furo>=2024.8.6' \
+            --with 'myst-parser>=3.0' \
+            --with 'sphinx-copybutton>=0.5' \
+            --with 'sphinx-design>=0.6' \
+            sphinx-build -W -b html docs docs/_build/html
+
+      # upload-pages-artifact creates the zip format required by deploy-pages.
+      # Used instead of upload-artifact so the deploy job can consume it directly.
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    # Only deploy on push to master, not on PRs.
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+    # pages: write + id-token: write are required for OIDC-based Pages deployment.
+    # Scoped here — deploy does not need contents read.
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v4

{loom_kernel-0.0.0 → loom_kernel-0.2.0}/.github/workflows/release.yml

@@ -27,15 +27,15 @@ jobs:
       PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
       RELEASE_BRANCH: ${{ github.event_name == 'workflow_dispatch' && inputs.source_branch || github.event.pull_request.head.ref }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: "3.11"
 
-      - uses: astral-sh/setup-uv@v3
+      - uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3
 
       - name: Configure uv environment path
         shell: bash
@@ -45,7 +45,7 @@ jobs:
 
       - name: Compute release version from merged branch
         id: version
-        uses: the-reacher-data/loom-actions/actions/release/versioning-branch-semantic@v1
+        uses: the-reacher-data/loom-actions/actions/release/versioning-branch-semantic@e731576f4f9cf4ec2b36fddfc895d328c856d29f # v1
         with:
           branch: ${{ env.RELEASE_BRANCH }}
           prerelease: "false"
@@ -53,7 +53,7 @@ jobs:
       - name: Generate release changelog
         id: changelog
         if: ${{ steps.version.outputs.deploy == 'true' && github.event_name != 'workflow_dispatch' }}
-        uses: the-reacher-data/loom-actions/actions/release/changelog-conventional-commit@v1
+        uses: the-reacher-data/loom-actions/actions/release/changelog-conventional-commit@e731576f4f9cf4ec2b36fddfc895d328c856d29f # v1
         with:
           mode: "release"
           branch: ${{ env.RELEASE_BRANCH }}
@@ -94,13 +94,13 @@ jobs:
 
       - name: Publish package to PyPI (token mode)
         if: ${{ steps.version.outputs.deploy == 'true' && env.PYPI_API_TOKEN != '' }}
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # release/v1
         with:
           password: ${{ env.PYPI_API_TOKEN }}
 
       - name: Publish package to PyPI (trusted publisher)
         if: ${{ steps.version.outputs.deploy == 'true' && env.PYPI_API_TOKEN == '' }}
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # release/v1
 
       - name: Create and push tags
         if: ${{ steps.version.outputs.deploy == 'true' }}
@@ -127,7 +127,7 @@ jobs:
 
       - name: Create GitHub release
         if: ${{ steps.version.outputs.deploy == 'true' }}
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2
         with:
           tag_name: v${{ steps.version.outputs.version }}
           name: v${{ steps.version.outputs.version }}

{loom_kernel-0.0.0 → loom_kernel-0.2.0}/.gitignore

@@ -8,7 +8,6 @@ wheels/
 
 # Virtual environments
 .venv
-
 # Local/editor/cache noise
 .mypy_cache/
 .pytest_cache/
@@ -17,10 +16,16 @@ wheels/
 coverage.xml
 htmlcov/
 .vscode/
-docs/
+docs/__pycache__/
 .claude/
 .claude.md
 AGENTS.md
 
 # Internal discussion docs (not part of distributable source)
 specs/
+
+# Sphinx build output — generated by ReadTheDocs, never commit
+docs/_build/
+
+# autosummary stubs — regenerated by Sphinx on every build
+docs/reference/api/generated/

{loom_kernel-0.0.0 → loom_kernel-0.2.0}/.pre-commit-config.yaml

@@ -24,6 +24,13 @@ repos:
 
       - id: mypy
         name: mypy strict
-        entry: uv run mypy --no-incremental src tests
+        entry: uv run mypy --no-incremental src
         language: system
         pass_filenames: false
+
+      - id: pyright
+        name: pyright
+        entry: uv run pyright
+        language: system
+        pass_filenames: false
+        types: [python]

loom_kernel-0.2.0/.readthedocs.yaml

@@ -0,0 +1,15 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .

loom_kernel-0.2.0/CHANGELOG.md

@@ -0,0 +1,120 @@
+# 🚀 Release 0.2.0 ([#9](https://github.com/the-reacher-data/loom-py/pull/9)) ([`2f669ab`](https://github.com/the-reacher-data/loom-py/commit/2f669ab205c7255eb6494e4cdb8ab8092817af62))
+
+
+## ✨ Features
+### core
+- **core:** typed repository abstractions and SQLAlchemy backend<br>
+  > Async repository protocol (RepositoryRead, RepositoryWrite, RepoFor) backed
+  > by SQLAlchemy 2.0 async session. Struct-based model system using
+  > msgspec.Struct
+  > as the single source of truth — models compile to SA mapped classes at startup
+  > via compile_all(). count() and UPDATE RETURNING included as first-class
+  > operations.
+
+- **core:** use-case DSL with field refs, compute, rules and typed markers<br>
+  > Declarative use-case definition via Input, Load, LoadById, Exists, Compute and
+  > Rule markers. Signature inspection runs once at compile time; RuntimeExecutor
+  > drives execution from an immutable ExecutionPlan. No per-request reflection.
+
+- **core:** ApplicationInvoker and named use-case registry<br>
+  > Use cases and job callbacks invoke other use cases by type through
+  > ApplicationInvoker without direct coupling. A named registry maps use-case
+  > keys to compiled instances at bootstrap, providing a stable cross-invocation
+  > contract.
+
+- **core:** compiled model artifact and cache entity keys<br>
+  > compile_all() produces a typed CompiledCore artifact exposing stable entity
+  > keys used by the cache layer for deterministic repository-level invalidation
+  > across reads and writes.
+
+- **core:** executor skips UoW for read-only use cases and GET routes<br>
+  > UseCase.read_only=True and all GET routes bypass UoW.begin/commit, removing
+  > at minimum one BEGIN+COMMIT round-trip from every read request on PostgreSQL.
+
+
+### projection
+- **projection:** compiler-driven memory/SQL routing<br>
+  > Projections are source-agnostic at declaration time. The backend compiler
+  > decides at compile_all() whether each projection runs in-memory (relation
+  > already loaded in the active profile) or via SQL. Users declare only
+  > CountLoader, ExistsLoader, or JoinFieldsLoader — no source= parameter.
+  > Internal _Memory* and _Sql* loaders are synthesized at compile time.
+
+
+### cache
+- **cache:** aiocache gateway with auto-inferred invalidation specs<br>
+  > CachedRepository wraps any repository with read-through/write-through caching.
+  > ONE_TO_MANY depends_on specs are auto-generated from field annotations — no
+  > explicit declaration needed. Explicit depends_on always wins.
+
+
+### job
+- **job:** async job domain model and orchestration primitives<br>
+  > Job[ResultT] base class with Celery routing ClassVars. JobHandle / JobGroup
+  > with dual-mode waiting (Celery + inline). JobCallback lifecycle with
+  > on_success/on_failure. Dispatch is transactionally safe — jobs flush on
+  > UoW commit and are cleared on rollback.
+
+
+### celery
+- **celery:** production-ready Celery integration layer<br>
+  > CeleryJobService, persistent worker event loop, trace propagation, eager
+  > fallback, and task_default_queue routing so callbacks land on the correct
+  > consumed queue. bootstrap_worker compiles use cases, repositories, and
+  > registers Celery tasks in a single call.
+
+- **celery:** worker job discovery from modules or manifest<br>
+  > bootstrap_worker discovers and registers Job classes automatically from
+  > module include paths (mode: modules) or from a typed WorkerManifest
+  > (mode: manifest). WorkerManifest replaces scattered JOBS/USE_CASES/INTERFACES
+  > module attributes with a single typed contract.
+
+- **celery:** interfaces= and use_cases= on bootstrap_worker<br>
+  > Callbacks that call ApplicationInvoker need matching use-case keys compiled
+  > in the worker. interfaces= extracts use-case types from RestInterface route
+  > declarations (including AutoCRUD-generated ones). use_cases= handles
+  > non-AutoCRUD scenarios. Both can be combined with discovery mode.
+
+
+### rest
+- **rest:** AutoCRUD and FastAPI adapter<br>
+  > RestInterface.auto=True generates full CRUD routes at class definition time
+  > via build_auto_routes(). OpenAPI contracts expose query params, pagination
+  > defaults, and decoupled CreateInput/UpdateInput write DTOs. Discovery engine
+  > mounts all declared interfaces at bootstrap.
+
+
+### observability
+- **observability:** trace_id propagation and Prometheus adapter<br>
+  > trace_id injected into every request context and propagated to job callbacks.
+  > MetricsAdapter protocol emits execution events; PrometheusAdapter records
+  > latency histograms and error counters with low cardinality labels.
+
+
+
+
+## 📖 Documentation
+- Sphinx documentation platform with full public guides<br>
+  > Quickstart, use-case DSL reference, AutoCRUD guide, Celery integration guide
+  > (job definition, dispatch, callbacks, YAML reference, bootstrap options,
+  > ApplicationInvoker, Docker-compose stack), and dummy-loom examples-repo
+  > walkthrough. Deployed to Read the Docs.
+
+
+
+
+
+## ⚡ Performance
+### repository
+- **repository:** single-query total count for offset pagination<br>
+  > list_with_query with PaginationMode.OFFSET issues a single SELECT COUNT(*)
+  > instead of a separate full-table scan, eliminating one round-trip per
+  > paginated list operation.
+
+
+### engine
+- **engine:** UPDATE RETURNING replaces SELECT + flush + refresh<br>
+  > SQLAlchemyUpdateMixin.update() issues a single UPDATE ... RETURNING
+  > round-trip.
+  > Server-side onupdate expressions are pre-computed at init time and injected
+  > into the SET clause automatically.