loom-kernel 9.2.0__tar.gz → 10.1.0__tar.gz

{loom_kernel-9.2.0 → loom_kernel-10.1.0}/CHANGELOG.md

@@ -2,6 +2,99 @@
 
 ## ✨ Features
 
+### jobs
+
+- **jobs:** `app.job_service` (`inline`, `celery` or `module:Class` built with
+  a `JobBackendContext`) names the job backend; queues listed in
+  `celery.queues`, but Celery's default queue, go to Celery through the new
+  `JobRouter`. Use cases keep
+  injecting `JobService`.
+- **jobs:** `app.job_service: sqs` (extra `loom[sqs]`) sends each job to the
+  SQS queue `sqs.queues` maps its queue to, after the commit, as the
+  `JobEnvelope` the Lambda SQS adapter runs. `sqs:` inherits `aws:`.
+  FIFO queues take the SHA-256 of the new `Job.__group_by__` payload field as
+  `MessageGroupId`. Callbacks, priorities, delays SQS cannot honour and bodies
+  over 256 KiB raise `SQSDispatchError`; unmapped queues stop startup.
+- **jobs:** an execution's SQS jobs leave after the commit in
+  `SendMessageBatch` calls per queue, in dispatch order (`sqs.batch`,
+  `sqs.batch_size`, `sqs.max_concurrent_sends`); a standard queue resends the
+  entries SQS refuses once, a FIFO queue stops at its first failure. `lambda.functions.<name>` with `sqs: true` declares `batch_size`,
+  `batching_window_s`, `max_concurrency` and `report_batch_item_failures`;
+  `false` makes the SQS handler fail the whole batch.
+
+### lambda
+
+- **lambda:** `loom deploy manifest <config> [--function x]` prints a
+  versioned JSON manifest (`manifest_version: 1`) of each function of
+  `lambda.functions` for a deployment tool: the handler, code path and
+  queues once, then per function its http routes and `auth` or its sqs queue
+  and event source mapping, and the secret and SSM parameter names it
+  resolves (never values; no resolver runs). It runs the deploy
+  checks of `loom check --deploy` first, prints their findings to stderr and
+  no manifest when one fails. New keys: `lambda.handler` and
+  `lambda.functions.<name>.queue` (a key of `sqs.queues`), both required by
+  the manifest only.
+- **rest:** `loom.rest.E001` also fails a `lambda.functions.<name>.auth`
+  that names no mechanism (`{}`, `jwt: null`, `custom: false`): it replaces
+  `app.rest.auth` for that function.
+
+### testing
+
+- **testing:** Lambda functions are tested in process, without AWS:
+  `LambdaTestClient`, an `httpx.Client` like FastAPI's `TestClient`, sends API
+  Gateway HTTP API or REST events to the real handler; `sqs_record` and
+  `sqs_raw_record` drive the SQS handler with the `JobEnvelope`
+  `SQSJobService` sends; `RecordingJobService`
+  (`app.job_service: loom.testing:RecordingJobService`) records each dispatch
+  after the commit. The `testing` extra now includes `httpx`.
+
+### stores
+
+- **stores:** an application composes `stores.default` and every store that
+  holds a model (`__store__`). Each store gets its own backend, engine,
+  repositories, unit of work and readiness probe; its `SessionManager` or
+  `MongoSessions` is injected by type for `default` and as
+  `(SessionManager, "<store>")` for the others. One invocation enlists the
+  stores it uses and commits them one after another (ADR 0008); nothing is
+  atomic across stores. When they do not all end the same way the execution
+  raises `StoresNotCommitted` (`stores_not_committed`, HTTP 500) with each
+  store's outcome.
+- **stores:** `Joined[...]` (`loom.core.use_case`) wraps a repository a use
+  case or job injects, such as `Joined[RepoFor[AuditEntry]]`, to declare that
+  it writes to that repository's store as well as to its primary store, the
+  `__store__` of its main model. Composition refuses `Joined` on a store that
+  cannot roll back (`UseCaseErrorCode.JOINED_AUTOCOMMIT_STORE`).
+- **stores:** a use case or job without a main model declares its primary
+  store with `__store__ = "<store>"`, as a model does; without it the primary
+  store stays `default`. A store it names that is not declared fails
+  composition, and so does `__store__` beside a main model.
+- **stores:** `load_application(path, store="audit")` loads one store's models
+  and schema section, so `create_schema` and `verify` prepare and check a
+  second Postgres store. `Application.path` (`loom.core.locator`) is derived
+  from the new `Application.store` and is no longer a constructor argument. Migrations still cover `default` only and log
+  `StoresNotLoaded` naming the stores they leave out.
+- **stores:** `persistence.rollback_timeout` (seconds, default 30) bounds the
+  rollbacks of one invocation together.
+- **stores:** the errors a caller catches have public import paths:
+  `StoresNotCommitted`, `ScopeOwnershipError`, `UnitOfWorkInsideScope`,
+  `UndeclaredStoreWrite` and `NestedElevation` from `loom.core.uow`,
+  `ForeignSessionError` from `loom.core.errors`, and `ReadOnlyElevation` from
+  `loom.core.repository.sqlalchemy.rls`, next to `elevate`.
+- **stores:** `async with session_manager.operation_session(write=...)`
+  gives raw SQL the session its operation runs in, as a repository's: the
+  invocation's when the store is enlisted, else a transaction of its own.
+  Repositories now run through it.
+
+### config
+
+- **config:** a top-level `aws:` section (`region`, `url`, `profile`, `pool`,
+  timeouts and retries; no credentials) sets the AWS client defaults every
+  AWS product inherits: `dynamodb` stores, `storage.dynamodb`, the `secrets`
+  and `ssm` resolvers (which read it as written and refuse a placeholder in
+  it) and the SNS notifier (from the flow's YAML; the topic's region wins).
+  A product's own keys override it key by key; without `aws:` nothing changes.
+  No `config.overridable` entry may open `aws` or `sqs.queues`.
+
 ### etl
 
 - **etl:** `IntoTable(...).upsert(..., delete_flag=...)` deletes matched rows
@@ -59,6 +152,181 @@
 
 ## ⚠ Behaviour changes
 
+### jobs
+
+- **jobs:** the composition applies `jobs.<Job>.*` once for every entry point,
+  so the API process now honours them too; before, only the Celery and Lambda
+  SQS workers did.
+- **jobs:** without `app.job_service` the job service is still chosen from the
+  `celery` section, now with a `DeprecationWarning` when Celery is installed or
+  configured. Set `app.job_service` to keep the choice explicit.
+- **jobs:** the Lambda SQS adapter logs the type of its job service instead
+  of assuming Celery for anything that is not inline.
+- **jobs:** job settings belong to the application:
+  `MyJob.__queue__`, `__retries__`, `__countdown__`, `__timeout__` and
+  `__priority__` no longer reflect `jobs.<Job>`; read
+  `application.job_settings.of(MyJob)`. `apply_job_config`,
+  `apply_job_overrides`, `read_job_config`, `resolve_binding` and
+  `validate_bindings` are removed, and an invalid or unknown `jobs.<Job>` key
+  fails composition.
+
+### stores
+
+- **stores:** a repository read, a `@with_session_scope(write=False)` method
+  or `operation_session(write=False)` on a store the invocation did not
+  enlist (a read-only execution such as a REST `GET`, or no invocation)
+  runs in a transaction of its own that is never committed: a write in it
+  persists nothing. On an enlisted store a `write=False` block still runs,
+  unrecorded, in the invocation's transaction and commits with it; declare
+  writes as `write=True`.
+- **stores:** a failed transaction of its own logs `OperationSessionRollback`
+  with `store=` and the exception type only, where it logged
+  `RepositorySessionRollback` with `repository=` and the exception text.
+- **stores:** a write to a store the running use case did not declare raises
+  `UndeclaredStoreWrite` (`undeclared_store_write`, HTTP 500) before the
+  driver is called, where it raised `ForeignSessionError`. So does a
+  `@transactional` call inside an invocation that did not enlist its store.
+- **stores:** `with_session_scope` takes the method's write intent:
+  `@with_session_scope(write=True)` or `@with_session_scope(write=False)`; a
+  bare `@with_session_scope` fails at import. A repository subclass calling
+  `self._session_scope()` passes `write=` too. A custom write is now refused
+  or joins the invocation like a built-in one, instead of committing on its
+  own when its store was not enlisted.
+- **stores:** post-commit actions run by the outcome of the stores they
+  depend on: a job dispatch or publish on every store of the execution that
+  queued it, a cache invalidation on its repository's store. With one store
+  two outcomes change. A commit whose result is unknown (a lost
+  acknowledgement, a cancellation during the commit) now runs the cache
+  invalidations it queued, and still sends no job. A store without
+  transactions whose use case raised, or whose invocation was poisoned, now
+  runs its cache invalidations too, and sends no job; a poisoned invocation
+  over such stores alone now fails with the poison's cause instead of
+  succeeding.
+- **stores:** `loom.core.transaction` is removed (`in_atomic_transaction`,
+  `open_atomic_transaction`, `close_atomic_transaction`). A cache
+  invalidation asks the invocation scope instead
+  (`InvocationScope.owners_of`): it waits for the commit only while the
+  model's store is enlisted and its unit of work declares both
+  `transactional = True` and `phased = True`, which is all a third-party unit
+  of work now needs. A write already durable (a store not enlisted, a unit of
+  work driven in a single phase, DynamoDB, Mongo without transactions) bumps
+  at once, so a later failure of the invocation no longer discards it.
+  `set_active_mutations`, `reset_active_mutations` and
+  `get_pending_mutations` are removed: `record_mutation` records on
+  `InvocationScope.mutations` while an outermost `@transactional` collects
+  them.
+- **stores:** `clear_pending_dispatches()` drops the job dispatches and
+  publishes of every store of the running invocation, and never a cache
+  invalidation.
+- **stores:** a read-only execution (`read_only = True`, every REST GET) runs
+  in an invocation that writes to no store: a write raises
+  `UndeclaredStoreWrite` instead of committing on its own, and so does a
+  `@transactional` method it calls; `async with uow:` in it raises
+  `UnitOfWorkInsideScope`, with or without a configured unit of work. A
+  use case or job that writes, run from it (a `gather` child or the invoker
+  included), raises `UndeclaredStoreWrite` instead of opening and committing
+  an invocation of its own, and so does one run from a read-only execution
+  nested in a writer. Move the write to a use case that is not read-only. A
+  job it dispatches, with any job service, raises `UndeclaredStoreWrite` too.
+  An
+  invocation that enlists no store closes without an outcome and logs no
+  `InvocationOutcome`.
+- **stores:** `async with uow:` and an outermost `@transactional` run through
+  the coordinator; `async with uow:` inside a running invocation raises
+  `UnitOfWorkInsideScope`. Even with one store, a write from a `gather` child
+  or from a task that outlived its use case raises `ScopeOwnershipError`. A
+  write in an open invocation with no execution running raises
+  `UndeclaredStoreWrite`.
+  SQLAlchemy flushes before it commits, a rollback interrupted by a second
+  cancellation is still awaited (bounded by `persistence.rollback_timeout`),
+  and Mongo never aborts after an attempted commit. The post-commit actions
+  queued inside, a nested use case's job dispatches and cache invalidations
+  included, run once the store has ended and by its outcome, as in an
+  execution; before, a nested use case sent them before the outer commit, and
+  a cache invalidation ran inline. A failed action raises `PostCommitError`
+  from `async with uow:` too. A job dispatched in the block is sent after the
+  commit instead of waiting for `flush_pending_dispatches()`, which raises
+  `RuntimeError` inside the block, as inside `@transactional`.
+- **stores:** an unknown commit result is `Uncertain`, not a rollback:
+  SQLAlchemy `OperationalError`, `InterfaceError`, an invalidated connection
+  or a transport timeout during `COMMIT`, and Mongo
+  `UnknownTransactionCommitResult`. The connection is invalidated and only the
+  cache invalidations run. The caller gets `StoresNotCommitted`, even with
+  one store, caused by the driver error; job runners never retry it, and REST
+  still answers 500, now with the code `stores_not_committed`.
+- **stores:** `SessionManager.active_session` and
+  `MongoSessions.active_session` (properties) are the only public way to read
+  a store's session; `get_active_session()`, `session_to_join()`,
+  `has_caller_scoped_session()` and Mongo `active_session()` are gone. A Mongo
+  `session_provider` is called with the write intent
+  (`Callable[[bool], AsyncClientSession | None]`); one without arguments no
+  longer works.
+- **stores:** a SQLAlchemy repository refuses a `session=` that is not the
+  invocation's session for its store (`ForeignSessionError`), and
+  `CachedRepository` requires a repository with `model`.
+- **stores:** DynamoDB writes go through the same checks
+  (`UndeclaredStoreWrite`, `ScopeOwnershipError`) before any call to AWS and
+  report `NonTransactional(wrote=True)`; `delete` is conditional. Its thread
+  pool starts when the store is built, shuts down when the application closes
+  and starts again when it reopens.
+- **stores:** wiring API. `RuntimeExecutor(uow_factory=)` and
+  `create_kernel(uow_factory=)` become `coordinator=` (`OrderedCommits`);
+  `Recipe.backend` becomes `Recipe.default_backend`, and
+  `CompositionSource.backend(key, *, default=)` takes the store;
+  `Application.persistence` and `require_single_store` are removed. `store`
+  is required by `StoreCatalog.served_by`, `BackendRuntime`, `SessionManager`,
+  `build_session_manager`, `MongoSessions`, `MongoUnitOfWork` and
+  `MongoUnitOfWorkFactory.transactional`;
+  `build_repository_registration_module` takes `default_builder=` and
+  `store=`. `StoreCatalog.models_by_store` always includes `default`. Binding
+  `MongoSessions` unkeyed, or a session manager keyed by store, is refused.
+  An invalid `stores` section fails in `compose_application`.
+  `_ROLLBACK_TIMEOUT_S` is now `ROLLBACK_TIMEOUT_S`.
+
+### rls
+
+- **rls:** a Postgres role that is a superuser or has `BYPASSRLS` is refused
+  at startup in every mode, `create_all` included; local setups running as
+  `postgres` need a plain role.
+- **rls:** elevation is routed per store. `SQLAlchemyElevationSink` becomes
+  `SQLAlchemyStoreElevation`; a hand-built kernel registers
+  `ScopedElevationSink({store: SQLAlchemyStoreElevation(session_manager)})`.
+  `validate_elevations(product, Mapping[StoreKey, ScopedTables])` runs in the
+  composition, and a backend plugin may expose `PersistenceWiring.elevation`.
+  A scope that is elevable or listed in `AuthzProduct.elevations` and
+  declared by two stores fails at startup
+  (`ELEVABLE_SCOPE_IN_SEVERAL_STORES`).
+- **rls:** `elevate()` in a read-only execution, REST GET routes included,
+  raises `ReadOnlyElevation`. A failed elevation step rolls back every store
+  of the invocation, even when a parent use case catches the error.
+- **rls:** scope sources are bound when the application is composed: every
+  `schema.scopes` binding is validated at startup, and a source registered
+  after composition does not reach that application.
+
+### rest
+
+- **rest:** a `5xx` body no longer carries the error's message, which could
+  name hosts, databases, stores or classes: it keeps `code`, `trace_id` and
+  `committed`, with the fixed message `An unexpected error occurred` (`503`:
+  `The service is temporarily unavailable`), also for an `HTTPException`
+  whose detail is a string. The message is logged at `ERROR` under the same
+  `trace_id`. FastAPI and Lambda answer the same; `4xx` bodies are unchanged.
+
+### ai
+
+- **ai:** a `5xx` `/run` body carries the same fixed message instead of the
+  run error's, `HOOK_FAILED` and `CONVERSATION_LOAD_FAILED` included; `code`
+  and `interaction_id` stay, and the error is logged at `ERROR`.
+
+
+### identity
+
+- **identity:** the executor binds the identity it is given for the whole
+  execution, so `Caller()` and row-level security always agree. A nested
+  execution joining the caller's unit of work as another identity raises
+  `NestedIdentityMismatch`; any nested execution under an active elevation
+  raises `NestedElevation`.
+
 ### etl
 
 - **etl:** the `PolarsStepRunner` reader applies what a `FromTable` or

{loom_kernel-9.2.0 → loom_kernel-10.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 9.2.0
+Version: 10.1.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
@@ -81,12 +81,17 @@ Requires-Dist: opentelemetry-sdk<2.0,>=1.27; extra == 'etl-spark'
 Requires-Dist: pyspark<4.0,>=3.5; (python_version < '3.13') and extra == 'etl-spark'
 Provides-Extra: jwt
 Requires-Dist: pyjwt[crypto]<3,>=2.8; extra == 'jwt'
+Provides-Extra: lambda
+Requires-Dist: fastapi<1.0,>=0.115; extra == 'lambda'
+Requires-Dist: mangum<1.0,>=0.22; extra == 'lambda'
+Requires-Dist: prometheus-client>=0.20; extra == 'lambda'
+Requires-Dist: pydantic<3.0,>=2.0; extra == 'lambda'
 Provides-Extra: logfire
-Requires-Dist: logfire<5,>=4.0; extra == 'logfire'
+Requires-Dist: logfire<6,>=4.0; extra == 'logfire'
 Requires-Dist: opentelemetry-api<2.0,>=1.27; extra == 'logfire'
 Requires-Dist: opentelemetry-sdk<2.0,>=1.27; extra == 'logfire'
 Provides-Extra: mongo
-Requires-Dist: pymongo<5.0,>=4.9; extra == 'mongo'
+Requires-Dist: pymongo<5.0,>=4.18.3; extra == 'mongo'
 Provides-Extra: prefect
 Requires-Dist: boto3>=1.35; extra == 'prefect'
 Requires-Dist: docker>=7.0; extra == 'prefect'
@@ -109,6 +114,8 @@ Provides-Extra: sqlalchemy
 Requires-Dist: alembic<2,>=1.13; extra == 'sqlalchemy'
 Requires-Dist: greenlet>=3.0; extra == 'sqlalchemy'
 Requires-Dist: sqlalchemy<3.0,>=2.0; extra == 'sqlalchemy'
+Provides-Extra: sqs
+Requires-Dist: boto3>=1.35; extra == 'sqs'
 Provides-Extra: streaming
 Requires-Dist: anyio<5.0,>=4.0; extra == 'streaming'
 Requires-Dist: bytewax>=0.21; (python_version < '3.13') and extra == 'streaming'
@@ -119,6 +126,7 @@ Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.27; extra == 'stre
 Requires-Dist: opentelemetry-sdk<2.0,>=1.27; extra == 'streaming'
 Requires-Dist: uvloop<1.0,>=0.21; (sys_platform != 'win32') and extra == 'streaming'
 Provides-Extra: testing
+Requires-Dist: httpx>=0.27; extra == 'testing'
 Requires-Dist: pytest>=8.3.0; extra == 'testing'
 Description-Content-Type: text/markdown
 
@@ -439,8 +447,9 @@ class AddressRestInterface(RestInterface[Address]):
 
 The `create_app()` factory wires everything — DB, cache, DI, routes — from a YAML config:
 
+In `config/api.yaml`:
+
 ```yaml
-# config/api.yaml
 app:
   name: my_store
   code_path: src
@@ -459,16 +468,18 @@ app:
 
 persistence:
   cursors:
-    signing: ephemeral   # development.yaml only; production.yaml configures keys
+    signing: ephemeral
 
-database:
-  url: ${oc.env:DATABASE_URL,sqlite+aiosqlite:///store.db}
+stores:
+  default:
+    backend: sqlalchemy
+    url: ${oc.env:DATABASE_URL,sqlite+aiosqlite:///store.db}
 
-cache:                      # optional; wraps every repository marked @cached
+cache:
   default_ttl: 300
   aiocache_config:
     default:
-      cache: aiocache.SimpleMemoryCache       # memory -> Redis: aiocache.RedisCache
+      cache: aiocache.SimpleMemoryCache
       serializer:
         class: loom.core.cache.serializer.MsgspecSerializer
 
@@ -481,6 +492,12 @@ observability:
     enabled: false
 ```
 
+| Key | Meaning |
+| --- | --- |
+| `signing` | `signing: ephemeral` is for `development.yaml` only; `production.yaml` configures keys |
+| `cache` | optional; wraps every repository marked `@cached` |
+| `aiocache_config.default.cache` | memory -> Redis: `aiocache.RedisCache` |
+
 ```python
 # main.py — 3 lines
 from loom.rest.fastapi.auto import create_app

{loom_kernel-9.2.0 → loom_kernel-10.1.0}/README.md

@@ -315,8 +315,9 @@ class AddressRestInterface(RestInterface[Address]):
 
 The `create_app()` factory wires everything — DB, cache, DI, routes — from a YAML config:
 
+In `config/api.yaml`:
+
 ```yaml
-# config/api.yaml
 app:
   name: my_store
   code_path: src
@@ -335,16 +336,18 @@ app:
 
 persistence:
   cursors:
-    signing: ephemeral   # development.yaml only; production.yaml configures keys
+    signing: ephemeral
 
-database:
-  url: ${oc.env:DATABASE_URL,sqlite+aiosqlite:///store.db}
+stores:
+  default:
+    backend: sqlalchemy
+    url: ${oc.env:DATABASE_URL,sqlite+aiosqlite:///store.db}
 
-cache:                      # optional; wraps every repository marked @cached
+cache:
   default_ttl: 300
   aiocache_config:
     default:
-      cache: aiocache.SimpleMemoryCache       # memory -> Redis: aiocache.RedisCache
+      cache: aiocache.SimpleMemoryCache
       serializer:
         class: loom.core.cache.serializer.MsgspecSerializer
 
@@ -357,6 +360,12 @@ observability:
     enabled: false
 ```
 
+| Key | Meaning |
+| --- | --- |
+| `signing` | `signing: ephemeral` is for `development.yaml` only; `production.yaml` configures keys |
+| `cache` | optional; wraps every repository marked `@cached` |
+| `aiocache_config.default.cache` | memory -> Redis: `aiocache.RedisCache` |
+
 ```python
 # main.py — 3 lines
 from loom.rest.fastapi.auto import create_app

{loom_kernel-9.2.0 → loom_kernel-10.1.0}/pyproject.toml

@@ -31,6 +31,7 @@ loom = "loom.cli:main"
 # them needs pytest at runtime like any other declared dependency.
 testing = [
     "pytest>=8.3.0",
+    "httpx>=0.27",
 ]
 rest = [
     "fastapi>=0.115,<1.0",
@@ -51,8 +52,11 @@ clickhouse = [
 dynamodb = [
     "boto3>=1.35",
 ]
+sqs = [
+    "boto3>=1.35",
+]
 mongo = [
-    "pymongo>=4.9,<5.0",
+    "pymongo>=4.18.3,<5.0",
 ]
 jwt = [
     "pyjwt[crypto]>=2.8,<3",
@@ -158,7 +162,7 @@ ai-harness = [
 # See docs/ai/observability.md — a non-empty endpoint makes loom build its own
 # provider, and the two are mutually exclusive by construction.
 logfire = [
-    "logfire>=4.0,<5",
+    "logfire>=4.0,<6",
     "opentelemetry-api>=1.27,<2.0",
     "opentelemetry-sdk>=1.27,<2.0",
 ]
@@ -171,6 +175,14 @@ cli = [
     "pyyaml>=6",
     "typer>=0.12,<1",
 ]
+# AWS Lambda behind API Gateway: the REST stack without a server, and the
+# translator from API Gateway events to ASGI. The SQS adapter needs no extra.
+lambda = [
+    "fastapi>=0.115,<1.0",
+    "pydantic>=2.0,<3.0",
+    "prometheus-client>=0.20",
+    "mangum>=0.22,<1.0",
+]
 
 [project.entry-points."loom.ai.engines"]
 pydantic-ai = "loom.ai.engines.pydantic_ai.provider:PydanticAIEngineProvider"
@@ -269,7 +281,7 @@ dev = [
     "confluent-kafka>=2.6,<3.0",
     "bytewax>=0.21; python_version < '3.13'",
     "boto3>=1.35",
-    "pymongo>=4.9,<5.0",
+    "pymongo>=4.18.3,<5.0",
     "opentelemetry-api>=1.27,<2.0",
     "opentelemetry-sdk>=1.27,<2.0",
     "opentelemetry-exporter-otlp-proto-http>=1.27,<2.0",
@@ -284,6 +296,9 @@ dev = [
     "a2a-sdk>=1.1,<2",
     "pydantic-ai-harness[skills]>=0.28,<1",
     "typer>=0.12,<1",
+    "pytest-timeout>=2.3",
+    # The Lambda HTTP adapter's tests run in the fast lane, without extras.
+    "mangum>=0.22,<1.0",
 ]
 
 [tool.hatch.build.targets.wheel]
@@ -440,6 +455,7 @@ pythonpath = [
 ]
 addopts = "-ra --log-disable=aiosqlite"
 asyncio_mode = "auto"
+timeout = 300
 log_cli = true
 log_cli_level = "DEBUG"
 log_cli_format = "%(asctime)s %(levelname)s %(name)s %(message)s"

{loom_kernel-9.2.0 → loom_kernel-10.1.0}/src/loom/ai/_concurrency.py

@@ -16,6 +16,8 @@ import logging
 from collections.abc import Coroutine
 from typing import Any, TypeVar
 
+from loom.core._async import discard_outcome
+
 _logger = logging.getLogger(__name__)
 
 _T = TypeVar("_T")
@@ -34,7 +36,8 @@ async def shield_and_drain(call: Coroutine[Any, Any, _T], *, label: str) -> _T:
     Raises:
         asyncio.CancelledError: Re-raised to the caller once the call has
             finished draining underneath it; the call itself still ran to
-            completion.
+            completion. A second cancellation while draining escapes at
+            once, so a caller can still abandon a call that hangs.
     """
     in_flight = asyncio.ensure_future(call)
     try:
@@ -42,11 +45,5 @@ async def shield_and_drain(call: Coroutine[Any, Any, _T], *, label: str) -> _T:
     except asyncio.CancelledError:
         _logger.debug("%r: draining a cancelled call", label)
         await asyncio.wait([in_flight])
-        _discard_outcome(in_flight)
+        discard_outcome(in_flight)
         raise
-
-
-def _discard_outcome(task: asyncio.Future[Any]) -> None:
-    """Consume a drained call's outcome so it is never reported as unretrieved."""
-    if not task.cancelled():
-        task.exception()

{loom_kernel-9.2.0 → loom_kernel-10.1.0}/src/loom/ai/_startup.py

@@ -1,7 +1,7 @@
 """Start-up verification of use-case marker bindings, shared by every worker.
 
 Both composition roots that admit a marker — the FastAPI auto-bootstrap
-(:mod:`loom.rest.fastapi.auto`) and the Celery worker bootstrap
+(:mod:`loom.composition._ai`) and the Celery worker bootstrap
 (:mod:`loom.celery.bootstrap`) — call :func:`verify_agent_markers` once every
 compiled use case declaring at least one ``Agent()`` binding is already known
 via :func:`~loom.core.use_case.agent_markers.declaring_agent_bindings`, so

{loom_kernel-9.2.0 → loom_kernel-10.1.0}/src/loom/ai/a2a/_rpc.py

@@ -32,6 +32,7 @@ from starlette.responses import Response
 
 from loom.ai.errors import AgentRunErrorCode
 from loom.ai.fastapi.response import AgentJSONResponse
+from loom.rest.errors import _INTERNAL_ERROR_MESSAGE
 
 _JSONRPC_VERSION: Final = "2.0"
 
@@ -84,10 +85,6 @@ RUN_ERROR_DETAILS: Final[Mapping[AgentRunErrorCode, str]] = MappingProxyType(
     }
 )
 
-# Detail of a failure with no catalogue entry, including the catch-all. Mirrors
-# the wording of the HTTP surface's own unexpected-failure body.
-_UNEXPECTED_DETAIL: Final[str] = "An unexpected error occurred"
-
 
 class RpcEnvelope(msgspec.Struct, frozen=True, kw_only=True):
     """Permissive view of a JSON-RPC request, so a malformed one still echoes its id."""
@@ -162,7 +159,7 @@ def internal_error(code: AgentRunErrorCode) -> InternalError:
     return InternalError(
         code=-32603,
         message="Internal error",
-        data={"code": str(code), "detail": RUN_ERROR_DETAILS.get(code, _UNEXPECTED_DETAIL)},
+        data={"code": str(code), "detail": RUN_ERROR_DETAILS.get(code, _INTERNAL_ERROR_MESSAGE)},
     )
 
 
@@ -171,7 +168,10 @@ def unexpected_error() -> InternalError:
     return InternalError(
         code=-32603,
         message="Internal error",
-        data={"code": str(AgentRunErrorCode.PROVIDER_UNAVAILABLE), "detail": _UNEXPECTED_DETAIL},
+        data={
+            "code": str(AgentRunErrorCode.PROVIDER_UNAVAILABLE),
+            "detail": _INTERNAL_ERROR_MESSAGE,
+        },
     )
 
 

{loom_kernel-9.2.0 → loom_kernel-10.1.0}/src/loom/ai/compiler/phases/_capabilities.py

@@ -295,7 +295,7 @@ def compile_mcp_capability(
     """Resolve a server name and filter into a :class:`CompiledMcpCapability`.
 
     Shared by the agent ``mcp`` capability (:func:`_compile_mcp`) and the
-    use-case ``Mcp()`` marker path (:mod:`loom.rest.fastapi.auto`), so both
+    use-case ``Mcp()`` marker path (:mod:`loom.composition._ai`), so both
     produce an identical compiled capability from identical inputs and the
     agent path's behaviour cannot drift from an independent copy.
 

{loom_kernel-9.2.0 → loom_kernel-10.1.0}/src/loom/ai/config.py

@@ -326,11 +326,7 @@ class A2AConfig(LoomFrozenStruct, frozen=True, kw_only=True):
             _warn_plaintext_loopback("ai.a2a.base_url", address)
         if fault is not None:
             raise AgentCompilationError(
-                [
-                    AgentErrorCode.A2A_BASE_URL_INVALID.issue(
-                        url=_redact_url(address), reason=fault
-                    )
-                ]
+                [AgentErrorCode.A2A_BASE_URL_INVALID.issue(url=_redact_url(address), reason=fault)]
             )
 
 

{loom_kernel-9.2.0 → loom_kernel-10.1.0}/src/loom/ai/engines/pydantic_ai/_instructions.py

@@ -196,7 +196,7 @@ def _handlebars_instruction(
     The closure renders against ``ctx.deps.state``, never against ``ctx.deps``
     itself. ``ctx.deps`` is the bundle carrying the caller's verified
     ``Identity``, the application container and a caller-bound invoker
-    (``loom.rest.fastapi.auto``); rendering against the bundle would put all
+    (``loom.composition._ai``); rendering against the bundle would put all
     three within a marker's reach. Rendering against ``state`` — the
     normalised mapping the artifact declared a shape for — is the security
     boundary a template cannot cross (FR-036).

{loom_kernel-9.2.0 → loom_kernel-10.1.0}/src/loom/ai/fastapi/endpoints.py

@@ -63,6 +63,7 @@ from loom.core.observability.runtime import ObservabilityRuntime
 from loom.core.observability.span import LoomSpan
 from loom.core.tracing import get_trace_id
 from loom.rest.auth.abc import Authenticator
+from loom.rest.errors import _INTERNAL_ERROR_MESSAGE, _public_message
 
 _logger = logging.getLogger(__name__)
 
@@ -143,11 +144,20 @@ _REQUEST_DECODER = msgspec.json.Decoder(_AgentRunRequest)
 
 
 def _run_error_response(error: AgentRunError) -> Response:
-    """Map a run-error code onto its published HTTP status."""
+    """Map a run-error code onto its published HTTP status; a ``5xx`` hides the message."""
+    status = _STATUS_BY_CODE.get(error.code, 500)
+    if status >= 500:
+        _logger.error(
+            "Agent run failed (code=%s interaction_id=%s trace_id=%s)",
+            error.code,
+            error.interaction_id,
+            get_trace_id(),
+            exc_info=error,
+        )
     return error_response(
-        _STATUS_BY_CODE.get(error.code, 500),
+        status,
         str(error.code),
-        str(error),
+        _public_message(status, str(error)),
         interaction_id=error.interaction_id,
     )
 
@@ -360,7 +370,7 @@ def _make_run_handler(
             return _run_error_response(exc)
         except Exception:
             _logger.exception("Unhandled error in the run endpoint of agent %r", name)
-            return error_response(500, "INTERNAL_ERROR", "An unexpected error occurred")
+            return error_response(500, "INTERNAL_ERROR", _INTERNAL_ERROR_MESSAGE)
 
     return run_agent