loom-kernel 0.1.0__tar.gz → 0.2.1__tar.gz

loom_kernel-0.2.1/CHANGELOG.md

@@ -0,0 +1,105 @@
+# 🚀 Release 0.2.1 ([#12](https://github.com/the-reacher-data/loom-py/pull/12)) ([`87f7d1f`](https://github.com/the-reacher-data/loom-py/commit/87f7d1f1eb1ccde71d0aca1c5584b83317e30707))
+
+
+## ✨ Features
+### logger
+- **logger:** support per-logger levels from config
+
+### repository
+- **repository:** generalize main repo registration for loom structs
+
+
+## 🐛 Fixes
+### rest
+- **rest:** serialize pagination envelopes in camel case
+- **rest:** support loom structs in autocrud tests
+
+### prometheus
+- **prometheus:** expose metrics at exact path
+
+### review
+- **review:** apply quick-fix pass from code review
+
+
+## 📖 Documentation
+### repository
+- **repository:** align custom repo examples
+
+
+
+## ♻️ Refactor
+### repository
+- **repository:** clarify sqlalchemy registration builder
+- **repository:** inject default repository builder
+- **repository:** simplify registration module
+
+
+
+
+
+
+
+# 🚀 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
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+### 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.
+
+## 📖 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
+
+### 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.
+
+### 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.

loom_kernel-0.2.1/CHANGELOG_RELEASE.md

@@ -0,0 +1,39 @@
+# 🚀 Release 0.2.1 ([#12](https://github.com/the-reacher-data/loom-py/pull/12)) ([`87f7d1f`](https://github.com/the-reacher-data/loom-py/commit/87f7d1f1eb1ccde71d0aca1c5584b83317e30707))
+
+
+## ✨ Features
+### logger
+- **logger:** support per-logger levels from config
+
+### repository
+- **repository:** generalize main repo registration for loom structs
+
+
+## 🐛 Fixes
+### rest
+- **rest:** serialize pagination envelopes in camel case
+- **rest:** support loom structs in autocrud tests
+
+### prometheus
+- **prometheus:** expose metrics at exact path
+
+### review
+- **review:** apply quick-fix pass from code review
+
+
+## 📖 Documentation
+### repository
+- **repository:** align custom repo examples
+
+
+
+## ♻️ Refactor
+### repository
+- **repository:** clarify sqlalchemy registration builder
+- **repository:** inject default repository builder
+- **repository:** simplify registration module
+
+
+
+
+

loom_kernel-0.2.1/PKG-INFO

@@ -0,0 +1,457 @@
+Metadata-Version: 2.4
+Name: loom-kernel
+Version: 0.2.1
+Summary: Loom Python project
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: aiocache<1.0,>=0.12
+Requires-Dist: msgspec<1.0,>=0.18
+Requires-Dist: omegaconf<3.0,>=2.3
+Requires-Dist: prometheus-client>=0.20
+Requires-Dist: structlog<26.0,>=24.4
+Provides-Extra: cache
+Requires-Dist: aiocache<1.0,>=0.12; extra == 'cache'
+Requires-Dist: omegaconf<3.0,>=2.3; extra == 'cache'
+Provides-Extra: celery
+Requires-Dist: celery<6.0,>=5.3; extra == 'celery'
+Requires-Dist: kombu<6.0,>=5.3; extra == 'celery'
+Requires-Dist: redis<6.0,>=5.0; extra == 'celery'
+Provides-Extra: config
+Requires-Dist: omegaconf<3.0,>=2.3; extra == 'config'
+Provides-Extra: prometheus
+Requires-Dist: prometheus-client>=0.20; extra == 'prometheus'
+Provides-Extra: pyspark
+Requires-Dist: pyspark<4.0,>=3.5; extra == 'pyspark'
+Provides-Extra: rest
+Requires-Dist: fastapi<1.0,>=0.115; extra == 'rest'
+Requires-Dist: httptools<1.0,>=0.6; extra == 'rest'
+Requires-Dist: prometheus-client>=0.20; extra == 'rest'
+Requires-Dist: pydantic<3.0,>=2.0; extra == 'rest'
+Requires-Dist: uvicorn<1.0,>=0.30; extra == 'rest'
+Requires-Dist: uvloop<1.0,>=0.21; (sys_platform != 'win32') and extra == 'rest'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy<3.0,>=2.0; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/_static/logo-transparent.png" alt="loom-kernel" width="160" style="background:#ffffff;border-radius:6px;padding:8px 20px;" />
+</p>
+
+# loom-kernel
+
+[![CI](https://img.shields.io/github/actions/workflow/status/the-reacher-data/loom-py/ci-main.yml?branch=master&label=ci)](https://github.com/the-reacher-data/loom-py/actions/workflows/ci-main.yml)
+[![Docs](https://img.shields.io/github/actions/workflow/status/the-reacher-data/loom-py/docs.yml?branch=master&label=docs)](https://github.com/the-reacher-data/loom-py/actions/workflows/docs.yml)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=the-reacher-data_loom-py&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=the-reacher-data_loom-py)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=the-reacher-data_loom-py&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=the-reacher-data_loom-py)
+[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=the-reacher-data_loom-py&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=the-reacher-data_loom-py)
+[![Coverage](https://codecov.io/gh/the-reacher-data/loom-py/branch/master/graph/badge.svg)](https://app.codecov.io/gh/the-reacher-data/loom-py/tree/master)
+[![PyPI](https://img.shields.io/pypi/v/loom-kernel)](https://pypi.org/project/loom-kernel/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/the-reacher-data/loom-py/blob/master/pyproject.toml)
+
+Framework-agnostic Python toolkit to build backend applications with:
+
+- **Auto-CRUD** — full REST surface from a model declaration, two lines of code
+- typed use cases (`msgspec.Struct`) with rules, computes, and dependency injection
+- repositories decoupled from infrastructure
+- REST/FastAPI adapters with OpenAPI generation
+- background jobs and Celery workers, first-class
+- testing utilities for business workflows
+
+## Purpose
+
+`loom-kernel` helps you ship production APIs faster without sacrificing clean
+architecture. Declare your domain model, describe your business rules, and let the
+framework handle the infrastructure plumbing — DB wiring, DI, routing, serialization.
+
+The library separates core contracts from concrete adapters so you can swap
+infrastructure (DB, cache, transport) without breaking business logic.
+
+## Documentation
+
+- Usage guides and architecture docs are available in the `docs/` site.
+- API reference is autogenerated from public docstrings.
+- End-to-end demo application: [`dummy-loom`](https://github.com/the-reacher-data/dummy-loom).
+
+## Main subpaths
+
+| Subpath | What it is for |
+| --- | --- |
+| `src/loom/core/use_case` | `UseCase` definition, rules (`Rule`), and compute steps (`Compute`). |
+| `src/loom/core/engine` | Compilation and runtime execution of a use-case plan. |
+| `src/loom/core/repository/abc` | Repository contracts, pagination, and typed query spec. |
+| `src/loom/core/repository/sqlalchemy` | Concrete async SQLAlchemy repository implementation. |
+| `src/loom/core/model` | Base model, fields, relations, and entity introspection. |
+| `src/loom/core/cache` | Decorators and cached repository with dependency invalidation. |
+| `src/loom/rest` | Framework-agnostic REST model and route compiler. |
+| `src/loom/rest/fastapi` | Direct FastAPI integration (auto wiring and runtime router). |
+| `src/loom/prometheus` | Middleware and adapter for runtime metrics. |
+| `src/loom/testing` | Harnesses for unit/integration tests and golden tests. |
+
+## Quick start
+
+### 1. Define your model
+
+```python
+from loom.core.model import ColumnField, OnDelete, TimestampedModel
+
+class User(TimestampedModel):
+    __tablename__ = "users"
+    id: int = ColumnField(primary_key=True, autoincrement=True)
+    full_name: str = ColumnField(length=120)
+    email: str = ColumnField(length=255, unique=True, index=True)
+
+class Address(TimestampedModel):
+    __tablename__ = "addresses"
+    id: int = ColumnField(primary_key=True, autoincrement=True)
+    user_id: int = ColumnField(foreign_key="users.id", on_delete=OnDelete.CASCADE, index=True)
+    city: str = ColumnField(length=120)
+    country: str = ColumnField(length=120)
+```
+
+### 2. Write use cases
+
+Use cases declare their inputs and invariants declaratively. The engine resolves them before `execute()` runs.
+
+```python
+import re
+from loom.core.command import Command, Patch
+from loom.core.errors import NotFound
+from loom.core.use_case import Exists, F, Input, LoadById, OnMissing, Rule
+from loom.core.use_case.use_case import UseCase
+
+_EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+
+class CreateUser(Command, frozen=True):
+    full_name: str
+    email: str
+
+class UpdateUser(Command, frozen=True):
+    full_name: Patch[str] = None
+    email: Patch[str] = None
+
+def _name_must_not_be_blank(full_name: str) -> str | None:
+    return None if full_name.strip() else "full_name must not be blank"
+
+def _email_must_be_valid(email: str) -> str | None:
+    return None if _EMAIL_RE.fullmatch(email) else "email must be valid"
+
+class CreateUserUseCase(UseCase[User, User]):
+    rules = [
+        Rule.check(F(CreateUser).full_name, via=_name_must_not_be_blank),
+        Rule.check(F(CreateUser).email, via=_email_must_be_valid),
+        Rule.forbid(lambda _, __, exists: exists, message="email already exists").from_params("email_exists"),
+    ]
+
+    async def execute(
+        self,
+        cmd: CreateUser = Input(),
+        email_exists: bool = Exists(User, from_command="email", against="email"),
+    ) -> User:
+        return await self.main_repo.create(cmd)
+
+class UpdateUserUseCase(UseCase[User, User | None]):
+    rules = [Rule.check(F(UpdateUser).full_name, via=_name_must_not_be_blank).when_present(F(UpdateUser).full_name)]
+
+    async def execute(
+        self,
+        user_id: int,
+        cmd: UpdateUser = Input(),
+        current_user: User = LoadById(User, by="user_id"),  # loaded automatically
+    ) -> User | None:
+        return await self.main_repo.update(user_id, cmd)
+```
+
+**`Exists`** checks a DB condition before execute runs — no boilerplate in the body.
+**`LoadById`** fetches an entity by a path/command parameter, available in rules and the body.
+**`Patch[T]`** marks a field as optional in partial updates; `.when_present(...)` gates rules on whether the field was sent.
+
+### 3. Scope resources under a parent
+
+Use `from_param` to guard nested routes (e.g. `/users/{user_id}/addresses/{address_id}`):
+
+```python
+from loom.core.use_case import Exists, Input, OnMissing
+
+class CreateAddressUseCase(UseCase[Address, Address]):
+    async def execute(
+        self,
+        user_id: int,
+        cmd: CreateUserAddress = Input(),
+        _user_exists: bool = Exists(User, from_param="user_id", against="id", on_missing=OnMissing.RAISE),
+    ) -> Address:
+        return await self.main_repo.create(CreateAddressRecord(user_id=user_id, **cmd.__dict__))
+```
+
+`OnMissing.RAISE` returns a structured 404 automatically — no `if` in the body.
+
+### 4. Structured queries
+
+Build explicit queries without raw SQL:
+
+```python
+from loom.core.repository.abc.query import (
+    FilterGroup, FilterOp, FilterSpec, PageResult, PaginationMode, QuerySpec, SortSpec,
+)
+
+class ListLowStockProductsUseCase(UseCase[Product, PageResult[Product]]):
+    async def execute(self, profile: str = "default") -> PageResult[Product]:
+        query = QuerySpec(
+            filters=FilterGroup(filters=(FilterSpec(field="stock", op=FilterOp.LTE, value=5),)),
+            sort=(SortSpec(field="stock", direction="ASC"),),
+            pagination=PaginationMode.OFFSET,
+            limit=20,
+            page=1,
+        )
+        result = await self.main_repo.list_with_query(query, profile=profile)
+        if not isinstance(result, PageResult):
+            raise RuntimeError("expected offset result")
+        return result
+```
+
+### 5. Background jobs
+
+Jobs are use-case-like executors that run in a queue. `LoadById` works the same way:
+
+```python
+from loom.core.job.job import Job
+from loom.core.use_case import Input, LoadById
+
+class SendRestockEmailJob(Job[bool]):
+    __queue__ = "notifications"
+
+    async def execute(
+        self,
+        product_id: int,
+        cmd: SendRestockEmailCommand = Input(),
+        product: Product = LoadById(Product, by="product_id"),
+    ) -> bool:
+        if product.stock > 0:
+            return False
+        # send email to cmd.recipient_email ...
+        return True
+```
+
+### 6. Dispatch jobs from use cases + callbacks
+
+```python
+from loom.core.job.service import JobService
+from loom.core.use_case.use_case import UseCase
+
+class DispatchRestockEmailUseCase(UseCase[Product, DispatchRestockEmailResponse]):
+    def __init__(self, job_service: JobService) -> None:
+        self._jobs = job_service
+
+    async def execute(self, product_id: str, cmd: DispatchRestockEmailCommand = Input()) -> DispatchRestockEmailResponse:
+        handle = self._jobs.dispatch(
+            SendRestockEmailJob,
+            params={"product_id": int(product_id)},
+            payload={"product_id": int(product_id), "recipient_email": cmd.recipient_email},
+            on_success=RestockEmailSuccessCallback,
+            on_failure=RestockEmailFailureCallback,
+        )
+        return DispatchRestockEmailResponse(job_id=handle.job_id, queue=handle.queue)
+```
+
+Callbacks are resolved by the DI container and receive the job result + context:
+
+```python
+class RestockEmailSuccessCallback:
+    def __init__(self, app: ApplicationInvoker) -> None:
+        self._app = app
+
+    async def on_success(self, job_id: str, result: Any, **context: Any) -> None:
+        if not result:
+            return
+        entity = self._app.entity(Product)
+        product = await entity.get(params={"id": context["product_id"]})
+        if product:
+            await entity.update(params={"id": product.id}, payload={"category": f"{product.category}-notified"})
+```
+
+### 7. Chain use cases (workflow pattern)
+
+`ApplicationInvoker` lets a use case call another use case by type — no tight coupling:
+
+```python
+from loom.core.use_case.invoker import ApplicationInvoker
+
+class RestockWorkflowUseCase(UseCase[Product, RestockWorkflowResponse]):
+    def __init__(self, app: ApplicationInvoker, job_service: JobService) -> None:
+        self._app = app
+        self._jobs = job_service
+
+    async def execute(self, product_id: str, cmd: DispatchRestockEmailCommand = Input()) -> RestockWorkflowResponse:
+        summary = await self._app.invoke(BuildProductSummaryUseCase, params={"product_id": int(product_id)})
+        handle = self._jobs.dispatch(SendRestockEmailJob, params={"product_id": int(product_id)}, payload={...})
+        return RestockWorkflowResponse(summary=summary.summary, restock_job_id=handle.job_id, queue=handle.queue)
+```
+
+### 8. Declare REST interfaces
+
+```python
+from loom.rest.autocrud import build_auto_routes
+from loom.rest.model import PaginationMode, RestInterface, RestRoute
+
+class ProductRestInterface(RestInterface[Product]):
+    prefix = "/products"
+    tags = ("Products",)
+    pagination_mode = PaginationMode.CURSOR
+    routes = (
+        RestRoute(use_case=ListLowStockProductsUseCase, method="GET", path="/low-stock",
+                  summary="List low stock products"),
+        RestRoute(use_case=DispatchRestockEmailUseCase, method="POST",
+                  path="/{product_id}/jobs/restock-email", status_code=202,
+                  summary="Dispatch restock email"),
+        RestRoute(use_case=RestockWorkflowUseCase, method="POST",
+                  path="/{product_id}/workflows/restock", status_code=202,
+                  summary="Run restock workflow"),
+        *build_auto_routes(Product, ()),  # adds GET, POST, PATCH, DELETE automatically
+    )
+```
+
+Nested resource interfaces work the same way — routes mirror the URL hierarchy:
+
+```python
+class AddressRestInterface(RestInterface[Address]):
+    prefix = "/users"
+    tags = ("UserAddresses",)
+    routes = (
+        RestRoute(use_case=CreateAddressUseCase, method="POST", path="/{user_id}/addresses/", status_code=201),
+        RestRoute(use_case=ListAddressesUseCase, method="GET",  path="/{user_id}/addresses/"),
+        RestRoute(use_case=GetAddressUseCase,    method="GET",  path="/{user_id}/addresses/{address_id}"),
+        RestRoute(use_case=UpdateAddressUseCase, method="PATCH", path="/{user_id}/addresses/{address_id}"),
+        RestRoute(use_case=DeleteAddressUseCase, method="DELETE", path="/{user_id}/addresses/{address_id}"),
+    )
+```
+
+### 9. Bootstrap with YAML
+
+The `create_app()` factory wires everything — DB, cache, DI, routes — from a YAML config:
+
+```yaml
+# config/api.yaml
+app:
+  name: my_store
+  code_path: src
+  discovery:
+    mode: modules
+    modules:
+      include:
+        - app.user.model
+        - app.user.interface
+        - app.product.model
+        - app.product.interface
+  rest:
+    backend: fastapi
+    title: My Store API
+    version: 0.1.0
+
+database:
+  url: ${oc.env:DATABASE_URL,sqlite+aiosqlite:///store.db}
+
+metrics:
+  enabled: false
+```
+
+```python
+# main.py — 3 lines
+from loom.rest.fastapi.auto import create_app
+
+app = create_app("config/api.yaml")
+```
+
+For larger projects, use `mode: manifest` and a manifest module:
+
+```python
+# app/manifest.py
+from app.user.model import User
+from app.user.interface import UserRestInterface
+
+MODELS = [User, ...]
+INTERFACES = [UserRestInterface, ...]
+```
+
+```yaml
+discovery:
+  mode: manifest
+  manifest:
+    module: app.manifest
+```
+
+### 10. Rules + Computes (advanced)
+
+For compute-heavy write flows, declare field derivations and run them before rules:
+
+```python
+from loom.core.use_case import Compute, F
+
+class PricingPreviewUseCase(UseCase[Record, PricingPreviewResponse]):
+    computes = (
+        Compute.set(F(PricingCommand).normalized_email).from_command(
+            F(PricingCommand).email, via=lambda v: v.strip().lower(),
+        ),
+        Compute.set(F(PricingCommand).subtotal).from_command(
+            F(PricingCommand).unit_price, F(PricingCommand).quantity,
+            via=lambda price, qty: price * qty,
+        ),
+        Compute.set(F(PricingCommand).tax_amount).from_command(
+            F(PricingCommand).subtotal, F(PricingCommand).tax_rate,
+            via=lambda sub, rate: sub * rate,
+        ),
+    )
+    rules = (
+        Rule.check(F(PricingCommand).unit_price, via=lambda v: v <= 0, message="unit_price must be > 0"),
+        Rule.check(F(PricingCommand).country, via=lambda v: v not in TAX_RATES, message="Unsupported country"),
+    )
+
+    async def execute(self, record_id: int, cmd: PricingCommand = Input()) -> PricingPreviewResponse:
+        ...
+```
+
+Computes run in declaration order — later computes can reference fields set by earlier ones.
+
+For deeper references, review the integration examples under
+`tests/integration/fake_repo`.
+For a runnable full-stack sample with all patterns combined, check the companion repository
+[`dummy-loom`](https://github.com/the-reacher-data/dummy-loom).
+
+## Performance
+
+`loom-kernel` adds zero measurable overhead at the concurrency levels typical of
+production REST APIs. The benchmark below compares `loompy` (loom-kernel + SQLAlchemy)
+against a hand-written FastAPI application hitting the same PostgreSQL database.
+
+**Methodology:** 3 independent runs × 3 concurrency levels (20 / 100 / 300 workers),
+median RPS reported. Dataset: 1 200 records, 3 notes each.
+Infrastructure: each target runs in its own isolated Docker container with a dedicated
+PostgreSQL instance.
+
+**loompy vs hand-written FastAPI (median RPS, 3 repeats):**
+
+| Scenario | c=20 | c=100 | c=300 |
+| --- | --- | --- | --- |
+| `GET /:id` with joins | ≈ tied | **+8.9 %** | −11.7 % |
+| `LIST` cursor | −2.8 % | **+3.8 %** | −19.4 % |
+| `LIST` offset + `COUNT(*)` | ≈ tied | **+6.2 %** | −25.4 % |
+| `PATCH` (UPDATE RETURNING) | **+2.1 %** | ≈ tied | **+12.7 %** |
+| `GET /ping` (no DB) | ≈ tied | −5.1 % | **+16.5 %** |
+
+At the production sweet spot (moderate concurrency, c=100), loom-kernel matches or
+outperforms the baseline in 4 out of 5 scenarios — without a single line of hand-tuned
+SQL. The `GET` and `LIST` advantages come from the compiled single-pass SQL read path.
+The `PATCH` advantage at high concurrency comes from the `UPDATE … RETURNING` pattern
+(one round-trip vs three in a naive implementation).
+
+The full benchmark suite is available in [`dummy-loom`](https://github.com/the-reacher-data/dummy-loom).
+
+## Status
+
+Project under active development.
+
+---
+
+## Author
+
+Designed and built by [Massive Data Scope](mailto:massivedatascope@gmail.com).
+
+For questions, feedback, or collaboration: **massivedatascope@gmail.com**