loom-kernel 2.20.2__tar.gz → 2.22.0__tar.gz

{loom_kernel-2.20.2 → loom_kernel-2.22.0}/CHANGELOG.md

@@ -184,6 +184,78 @@
 
 ### rest
 
+- **rest:** a use case says it created. `loom.core.use_case.Created[T]` wraps
+  the result of a use case declared `T | Created[T]`. The REST route answers
+  `Created(v)` with `201` and body `v`, and any other result with the route's
+  `status_code` as before; OpenAPI documents both statuses with the same
+  schema. `Created(v, location="/items/1")` also sends `Location` (RFC 9110
+  §15.3.2), which OpenAPI declares on the `201`; a location that is empty or
+  holds a character not allowed in an RFC 3986 URI reference raises
+  `ValueError`.
+  `LoomRestAdapter.handle` answers a `Created` the same way. Compilation
+  refuses a `Created` that wraps a type other than another member of the
+  result, appears twice or is not parameterised, and a `Created` on a route
+  whose `status_code` is already `201`. The invoker, jobs and Celery receive
+  the wrapper and read `.value`; the use case imports nothing from HTTP.
+- **rest:** `429` with `Retry-After`. `ErrorCode.RATE_LIMITED`
+  (`"rate_limited"`) and `loom.core.errors.RateLimited(retry_after)`, a
+  `DomainError` holding the delay in whole seconds, rounded up and at least
+  1; a non-finite `retry_after` raises `ValueError`. `HttpErrorMapper`
+  answers it with `429`, the standard body and `Retry-After: <seconds>`.
+  loom ships no limiter: the consumer decides who is limited and raises
+  `RateLimited`.
+- **rest:** declared query parameters. `loom.core.use_case.Query()` marks an
+  `execute` parameter typed with a strict `msgspec.Struct` or pydantic model
+  whose fields are each a string, integer, number, boolean, enum or
+  `Literal`, optionally `None`. The REST route accepts exactly its wire
+  names, plus `profile` where the route exposes it and `execute` declares an
+  annotated `profile` parameter, the condition OpenAPI publishes it under.
+  - An unknown or repeated parameter, `profile` included, answers
+    `400 unsupported_query`.
+  - A bad value answers `400 query_validation` (`ErrorCode.QUERY_VALIDATION`),
+    with the body and `violations` of `boundary_validation`; `422` stays for
+    bodies. A `profile` the route does not allow answers the same 400, on
+    field `profile` and without the value.
+  - Values are spelled strictly: a number follows the JSON number grammar
+    and is finite, an integer its integer subset within `[-2**63, 2**64)`
+    (an `IntEnum` or an int `Literal` is coerced the same way), a boolean is
+    `true` or `false`, `null` is never `None`, and a date or time field
+    refuses a number. A refused query never builds the use case.
+  - OpenAPI publishes one parameter per field, with `required`, its
+    constraints and description and no `title`; named enums go to
+    `components.schemas`.
+  - List, object and multi-type fields, a field named like a path parameter
+    or `profile`, a `QuerySpec` next to it and a second `Query()` are refused
+    at startup.
+  - A caller other than REST must pass an instance of the query type; any
+    other value raises `ParameterBindingError` naming the parameter and the
+    type received, never the value.
+  - A `Job` that declares `Query()` fails to compile with a
+    `CompilationError`: a job is dispatched with primitive parameters, so the
+    query struct could never reach it.
+  - An agent granted a use case that takes `Query()` fails to compile with
+    `USECASE_DECLARES_QUERY`.
+  - New: `ExecutionPlan.query_binding` (`QueryBinding`),
+    `CompiledRoute.query_fields` (`QueryField`), `CompiledRoute.result_type`
+    and `created_type`, `build_success_responses`, `LoomType.from_query`,
+    `names_query_spec`, `created_response`, `RETRY_AFTER_HEADER`,
+    `LOCATION_HEADER`, and a keyword-only `code` on `BoundaryValidationError`
+    (default `boundary_validation`). `build_query_parameters_schema` takes an
+    optional `component_registry`. `QuerySpec` routes are unchanged.
+- **rest:** step-up authentication (RFC 9470).
+  `loom.core.errors.InsufficientAuthentication(message, *, max_age=None,
+  acr_values=())`, an `Unauthenticated` with its own code
+  `ErrorCode.INSUFFICIENT_AUTHENTICATION` (`"insufficient_authentication"`),
+  answers `401` with `WWW-Authenticate: Bearer
+  error="insufficient_user_authentication", error_description="…"`, plus
+  `max_age="N"` and `acr_values="…"` when given. In the description each
+  character RFC 6750 §3 does not allow becomes a space, runs of spaces
+  collapse, an empty result falls back to the default message, and the text
+  is cut at 256 characters. A non-`str` message, a negative or non-int
+  `max_age`, `acr_values` that is a single `str` or `bytes`, or
+  an ACR value that is not a `str`, is empty, or holds anything but visible
+  ASCII other than a double quote or a backslash raise `ValueError`. Every
+  other 401 keeps the plain `Bearer` challenge.
 - **rest:** a `403` can say why and what is missing. `Forbidden` takes two
   optional keyword arguments, `reason` (a machine-readable cause such as
   `"mfa_required"`) and `missing` (the permissions the caller lacks, kept as a
@@ -375,6 +447,13 @@
 
 ### core
 
+- **core:** the `LoomType` protocol gains `from_query(params)`, which
+  validates query-string values strictly. A number takes the JSON number
+  grammar and must be finite, an integer its integer subset within
+  `[-2**63, 2**64)`, a boolean `true` or `false`; `null` is never `None` and
+  a date or time field refuses a number instead of reading a timestamp. Both
+  implementations are private to `loom.core.model`; a class of your own
+  declared as a `LoomType` must add the method.
 - **core:** on a model with a composite primary key, the SQLAlchemy
   repository's `get_by_id`, `exists`, `update` and `delete` take the key as a
   tuple of every key value in declaration order (`repo.get_by_id((account_id,
@@ -485,6 +564,17 @@
 
 ### rest
 
+- **rest:** every route now resolves its request parameters and decodes its
+  body before the use case is built, so a request refused at that point
+  never runs the use case's constructor.
+- **rest:** `build_success_response_schema` reads `CompiledRoute.result_type`
+  instead of the use case's annotations; a `CompiledRoute` built by hand
+  without it documents no success body.
+- **rest:** an error whose `code` is `"query_validation"` now answers `400`,
+  and one coded `"insufficient_authentication"` answers `401` with the plain
+  `Bearer` challenge unless it is an `InsufficientAuthentication`.
+- **rest:** an error whose `code` is `"rate_limited"` now answers `429`
+  instead of `500`; only a `RateLimited` carries `Retry-After`.
 - **rest:** a `RestInterface` whose `prefix` contains `{` now raises
   `InterfaceCompilationError` at compile time, naming the interface and the
   prefix; declare the placeholder in the route `path` instead (a catch-all
@@ -606,6 +696,16 @@
 
 ### core
 
+- **core:** a `BoundaryValidationError` no longer echoes the rejected value
+  (#347). msgspec's `Invalid enum value 'x'` (an `Enum`, `IntEnum` or `Literal`
+  field or dict key) and `Invalid value 'x'` (a tagged-union tag) become
+  `Invalid enum value` and `Invalid value`, in the message and the violation,
+  with the field path kept: ``Invalid enum value - at `$.colour` ``. pydantic's
+  `union_tag_invalid`, `uuid_parsing` and `bytes_invalid_encoding` reasons
+  become `Input tag does not match any of the expected tags`, `Input should be
+  a valid UUID` and `Data should be valid in its declared encoding`. A message
+  raised by the type's own validator keeps its text.
+
 - **core:** the relation steps and the `load_many` projection steps of a read
   profile run one after another on the request's session. They ran with
   `asyncio.gather` on that one session: when one step failed while another was
@@ -782,6 +882,17 @@
 
 ### rest
 
+- **rest:** the OpenAPI `limit` parameter of a `QuerySpec` route published
+  `maximum: 1000` and `default: 50` whatever `RestApiDefaults.max_limit` said,
+  while the router clamped `?limit=` to `max_limit`. The schema now publishes
+  `max_limit` as its `maximum` and `min(50, max_limit)` as its `default`, the
+  values the router applies. A larger `?limit=` is still clamped, not refused.
+- **rest:** a `QuerySpec` filter or sort on a field the SQLAlchemy compiler
+  cannot resolve, or a filter the repository's allow-list refuses, answered
+  `500 internal_error`. `FilterPathError` and `UnsafeFilterError` are now
+  `DomainError`s with code `unsupported_query`, so the route answers `400` with
+  the standard error body, whose message names the field and never its value.
+  Both remain `ValueError` subclasses with unchanged constructors and messages.
 - **rest:** a path placeholder in `RestInterface.prefix` was dropped. The route
   was registered on prefix + path, but path parameters were read from the
   route `path` only, so the use case never received the prefix parameter (a

{loom_kernel-2.20.2 → loom_kernel-2.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.20.2
+Version: 2.22.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3

{loom_kernel-2.20.2 → loom_kernel-2.22.0}/pyproject.toml

@@ -333,6 +333,7 @@ extend-immutable-calls = [
     "Load",
     "LoadById",
     "Mcp",
+    "Query",
     "loom.core.use_case.Agent",
     "loom.core.use_case.Caller",
     "loom.core.use_case.Exists",
@@ -340,6 +341,7 @@ extend-immutable-calls = [
     "loom.core.use_case.Load",
     "loom.core.use_case.LoadById",
     "loom.core.use_case.Mcp",
+    "loom.core.use_case.Query",
     "loom.core.use_case.markers.Agent",
     "loom.core.use_case.markers.Caller",
     "loom.core.use_case.markers.Exists",
@@ -347,6 +349,7 @@ extend-immutable-calls = [
     "loom.core.use_case.markers.Load",
     "loom.core.use_case.markers.LoadById",
     "loom.core.use_case.markers.Mcp",
+    "loom.core.use_case.markers.Query",
 ]
 
 [tool.pyright]

{loom_kernel-2.20.2 → loom_kernel-2.22.0}/src/loom/ai/compiler/phases/_capabilities.py

@@ -68,6 +68,7 @@ from loom.ai.errors import (
     sql_connection_roles_unbound,
     sql_connection_unknown,
     sql_result_bound_missing,
+    usecase_declares_query,
     usecase_key_unknown,
 )
 from loom.ai.inference import InferenceTarget
@@ -227,9 +228,14 @@ def _compile_usecase(capability: UsecaseCapability, context: _Context) -> _Handl
     use_cases: list[type[Compilable]] = []
     for key in capability.keys:
         try:
-            use_cases.append(context.registry.resolve(key))
+            use_case = context.registry.resolve(key)
         except KeyError:
             issues.append(usecase_key_unknown(context.component, key))
+            continue
+        execution = getattr(use_case, "__execution_plan__", None)
+        if execution is not None and execution.query_binding is not None:
+            issues.append(usecase_declares_query(context.component, key))
+        use_cases.append(use_case)
     if issues:
         return None, issues
     return CompiledUsecaseCapability(keys=capability.keys, use_cases=tuple(use_cases)), []

{loom_kernel-2.20.2 → loom_kernel-2.22.0}/src/loom/ai/errors.py

@@ -101,6 +101,7 @@ class AgentErrorCode(StrEnum):
     NATIVE_TOOL_DUPLICATE = "NATIVE_TOOL_DUPLICATE"
     CAPABILITY_EMPTY = "CAPABILITY_EMPTY"
     USECASE_KEY_UNKNOWN = "USECASE_KEY_UNKNOWN"
+    USECASE_DECLARES_QUERY = "USECASE_DECLARES_QUERY"
     SQL_CONNECTION_UNKNOWN = "SQL_CONNECTION_UNKNOWN"
     SQL_CONNECTION_NOT_READONLY = "SQL_CONNECTION_NOT_READONLY"
     SQL_CONFIG_MISSING = "SQL_CONFIG_MISSING"
@@ -648,6 +649,19 @@ def usecase_key_unknown(component: str, key: str) -> AgentCompilationIssue:
     )
 
 
+def usecase_declares_query(component: str, key: str) -> AgentCompilationIssue:
+    """A granted use case takes a ``Query()`` parameter, which a tool call cannot bind."""
+    return AgentCompilationIssue(
+        code=AgentErrorCode.USECASE_DECLARES_QUERY,
+        message=(
+            f"{component}: use case '{key}' declares a Query() parameter, which an agent "
+            "tool call cannot bind; grant a use case without one"
+        ),
+        component=component,
+        field="capabilities.keys",
+    )
+
+
 def sql_connection_unknown(component: str, connection: str) -> AgentCompilationIssue:
     """A ``sql`` capability names a connection that is not configured."""
     return AgentCompilationIssue(

{loom_kernel-2.20.2 → loom_kernel-2.22.0}/src/loom/core/engine/compiler.py

@@ -18,9 +18,12 @@ from loom.core.engine.plan import (
     LoadStep,
     McpBinding,
     ParamBinding,
+    QueryBinding,
     RuleStep,
 )
+from loom.core.job.job import Job
 from loom.core.logger import LoggerPort, get_logger
+from loom.core.model import UnsupportedBoundaryType, loom_type
 from loom.core.use_case.markers import (
     LookupKind,
     SourceKind,
@@ -31,6 +34,7 @@ from loom.core.use_case.markers import (
     _LoadByIdMarker,
     _LoadMarker,
     _McpMarker,
+    _QueryMarker,
 )
 
 
@@ -57,6 +61,7 @@ class _SignatureBindings:
     mcp_bindings: list[McpBinding] = field(default_factory=list)
     input_binding: InputBinding | None = None
     caller_binding: CallerBinding | None = None
+    query_binding: QueryBinding | None = None
 
 
 class UseCaseCompiler:
@@ -173,6 +178,7 @@ class UseCaseCompiler:
             caller_binding=bindings.caller_binding,
             agent_bindings=tuple(bindings.agent_bindings),
             mcp_bindings=tuple(bindings.mcp_bindings),
+            query_binding=bindings.query_binding,
         )
         use_case_type.__execution_plan__ = plan
         return plan
@@ -224,6 +230,10 @@ class UseCaseCompiler:
             self._collect_caller(use_case_type, name, bindings)
             return
 
+        if isinstance(marker, _QueryMarker):
+            self._collect_query(use_case_type, name, annotation, bindings)
+            return
+
         if isinstance(marker, _AgentMarker):
             self._collect_agent(name, annotation, marker, bindings)
             return
@@ -288,6 +298,32 @@ class UseCaseCompiler:
         bindings.caller_binding = CallerBinding(name=name)
         self._logger.info(f"[BOOT]  - Detected Caller: {name}")
 
+    def _collect_query(
+        self,
+        use_case_type: type[Compilable],
+        name: str,
+        annotation: Any,
+        bindings: _SignatureBindings,
+    ) -> None:
+        where = f"{use_case_type.__qualname__}.execute"
+        if issubclass(use_case_type, Job):
+            raise CompilationError(
+                f"{where}: a Job cannot declare Query(); a job is dispatched with plain "
+                "parameters, so pass the values it needs as parameters instead"
+            )
+        if bindings.query_binding is not None:
+            raise CompilationError(f"{where}: only one Query() parameter is allowed")
+        try:
+            loom_type(annotation)
+        except UnsupportedBoundaryType as exc:
+            raise CompilationError(
+                f"{where}: Query() parameter '{name}' must be a strict msgspec.Struct or "
+                f"pydantic model: {exc.message}"
+            ) from exc
+        bindings.query_binding = QueryBinding(name=name, query_type=annotation)
+        bindings.param_bindings.append(ParamBinding(name=name, annotation=annotation))
+        self._logger.info(f"[BOOT]  - Detected Query: {annotation.__name__} -> {name}")
+
     def _collect_agent(
         self,
         name: str,

{loom_kernel-2.20.2 → loom_kernel-2.22.0}/src/loom/core/engine/executor.py

@@ -575,6 +575,7 @@ class RuntimeExecutor:
         inputs: _ExecutionInputs,
     ) -> Any:
         bound: dict[str, Any] = {}
+        self._check_query(plan, inputs.params or {})
         self._bind_params(plan, inputs.params or {}, bound)
         self._bind_caller(plan, inputs.identity, bound)
         self._bind_agents(plan, inputs.identity, bound)
@@ -688,6 +689,24 @@ class RuntimeExecutor:
                 use_case_name=plan.use_case_type.__qualname__,
             )
 
+    @staticmethod
+    def _check_query(plan: ExecutionPlan, params: dict[str, Any]) -> None:
+        """Refuse a ``Query()`` value that is not an instance of its type.
+
+        A generic coercion would call the type with the raw value: a struct
+        whose fields are positional would take a dict as its first field. The
+        message names the type received, never the value.
+        """
+        binding = plan.query_binding
+        if binding is None or binding.name not in params:
+            return
+        raw = params[binding.name]
+        if not isinstance(raw, binding.query_type):
+            raise ParameterBindingError(
+                f"{plan.use_case_type.__qualname__}: parameter '{binding.name}' takes a "
+                f"{binding.query_type.__name__} instance, got {type(raw).__name__}"
+            )
+
     @staticmethod
     def _bind_caller(
         plan: ExecutionPlan,

{loom_kernel-2.20.2 → loom_kernel-2.22.0}/src/loom/core/engine/plan.py

@@ -40,6 +40,24 @@ class InputBinding:
     command_type: type[Any]
 
 
+@dataclass(frozen=True)
+class QueryBinding:
+    """The declared query parameter marked with ``Query()``.
+
+    The parameter is also an ordinary :class:`ParamBinding`: the executor
+    receives the typed value under ``name``. This binding tells a transport
+    which type declares the query it must accept and decode.
+
+    Args:
+        name: Parameter name as declared in the signature.
+        query_type: The strict ``msgspec.Struct`` or pydantic model declaring
+            the query.
+    """
+
+    name: str
+    query_type: type[Any]
+
+
 @dataclass(frozen=True)
 class CallerBinding:
     """The caller-identity parameter marked with ``Caller()``.
@@ -205,6 +223,8 @@ class ExecutionPlan:
             empty when the use case declares none.
         mcp_bindings: ``Mcp()`` marker bindings, in declaration order; empty
             when the use case declares none.
+        query_binding: ``Query()`` binding, or ``None`` when the use case
+            declares no ``Query()`` parameter.
         load_steps: Entity prefetch steps, in declaration order.
         exists_steps: Boolean existence checks, in declaration order.
         compute_steps: Compute transformations, in declaration order.
@@ -247,3 +267,4 @@ class ExecutionPlan:
     caller_binding: CallerBinding | None = None
     agent_bindings: tuple[AgentBinding, ...] = ()
     mcp_bindings: tuple[McpBinding, ...] = ()
+    query_binding: QueryBinding | None = None

{loom_kernel-2.20.2 → loom_kernel-2.22.0}/src/loom/core/errors/__init__.py

@@ -2,8 +2,10 @@ from loom.core.errors.errors import (
     Conflict,
     DomainError,
     Forbidden,
+    InsufficientAuthentication,
     LoomError,
     NotFound,
+    RateLimited,
     RuleViolation,
     RuleViolations,
     SystemError,
@@ -14,8 +16,10 @@ __all__ = [
     "Conflict",
     "DomainError",
     "Forbidden",
+    "InsufficientAuthentication",
     "LoomError",
     "NotFound",
+    "RateLimited",
     "RuleViolation",
     "RuleViolations",
     "SystemError",

{loom_kernel-2.20.2 → loom_kernel-2.22.0}/src/loom/core/errors/codes.py

@@ -26,13 +26,16 @@ class ErrorCode(StrEnum):
 
     NOT_FOUND = "not_found"
     UNAUTHENTICATED = "unauthenticated"
+    INSUFFICIENT_AUTHENTICATION = "insufficient_authentication"
     FORBIDDEN = "forbidden"
     CONFLICT = "conflict"
     RULE_VIOLATION = "rule_violation"
     RULE_VIOLATIONS = "rule_violations"
     BOUNDARY_VALIDATION = "boundary_validation"
+    QUERY_VALIDATION = "query_validation"
     UNSUPPORTED_FORMAT = "unsupported_format"
     UNSUPPORTED_QUERY = "unsupported_query"
+    RATE_LIMITED = "rate_limited"
     SYSTEM_ERROR = "system_error"
     SERVICE_UNAVAILABLE = "service_unavailable"
     POST_COMMIT_FAILURE = "post_commit_failure"

{loom_kernel-2.20.2 → loom_kernel-2.22.0}/src/loom/core/errors/errors.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
+import math
 from collections.abc import Iterable, Sequence
-from typing import Any
+from typing import Any, ClassVar
 
 from loom.core.errors.codes import ErrorCode
 
@@ -92,6 +93,66 @@ class Unauthenticated(DomainError):
         super().__init__(message, code=ErrorCode.UNAUTHENTICATED)
 
 
+class InsufficientAuthentication(Unauthenticated):
+    """Raised when the caller is authenticated, but not strongly or recently enough.
+
+    The caller can fix it by authenticating again under the stated
+    requirements (step-up).
+
+    Args:
+        message: Description of the missing authentication strength.
+        max_age: Seconds within which the caller must have authenticated;
+            ``None`` when recency is not the issue.
+        acr_values: Authentication context classes acceptable for a retry,
+            in order of preference; empty when any will do.
+
+    Raises:
+        ValueError: If ``message`` is not a ``str``, ``max_age`` is not a
+            non-negative ``int``, ``acr_values`` is a single ``str`` or
+            ``bytes``, or a value is not a ``str``, is empty, or holds a
+            character outside visible ASCII, a double quote or a backslash.
+        TypeError: If ``acr_values`` is not iterable.
+
+    Example::
+
+        raise InsufficientAuthentication(max_age=300, acr_values=("urn:mfa",))
+    """
+
+    default_message: ClassVar[str] = "A different authentication level is required"
+
+    def __init__(
+        self,
+        message: str = default_message,
+        *,
+        max_age: int | None = None,
+        acr_values: Iterable[str] = (),
+    ) -> None:
+        if not isinstance(message, str):
+            raise ValueError("InsufficientAuthentication.message must be a str")
+        if max_age is not None and (type(max_age) is not int or max_age < 0):
+            raise ValueError("InsufficientAuthentication.max_age must be a non-negative int")
+        if isinstance(acr_values, (str, bytes)):
+            raise ValueError(
+                "InsufficientAuthentication.acr_values takes an iterable of str values, "
+                "not one str or bytes"
+            )
+        values = tuple(acr_values)
+        if not all(
+            isinstance(value, str)
+            and value
+            and all("!" <= char <= "~" and char not in '"\\' for char in value)
+            for value in values
+        ):
+            raise ValueError(
+                "InsufficientAuthentication.acr_values must be visible ASCII without "
+                "whitespace, double quotes or backslashes"
+            )
+        super().__init__(message)
+        self.code = ErrorCode.INSUFFICIENT_AUTHENTICATION
+        self.max_age = max_age
+        self.acr_values: tuple[str, ...] = values
+
+
 class Forbidden(DomainError):
     """Raised when an action is not permitted for the caller.
 
@@ -143,6 +204,32 @@ class Conflict(DomainError):
         super().__init__(message, code=ErrorCode.CONFLICT)
 
 
+class RateLimited(DomainError):
+    """Raised when the caller spent its budget and must wait before retrying.
+
+    loom ships no limiter: the consumer decides who is limited and how much,
+    and raises this when a caller exceeds it.
+
+    Args:
+        retry_after: Seconds the caller should wait. Kept as whole seconds,
+            rounded up and at least ``1``.
+        message: Human-readable description of the refusal.
+
+    Raises:
+        ValueError: ``retry_after`` is not finite.
+
+    Example::
+
+        raise RateLimited(retry_after=2.0)
+    """
+
+    def __init__(self, retry_after: float, message: str = "Too many requests.") -> None:
+        if not math.isfinite(retry_after):
+            raise ValueError(f"RateLimited.retry_after must be finite, got {retry_after!r}")
+        super().__init__(message, code=ErrorCode.RATE_LIMITED)
+        self.retry_after = max(1, math.ceil(retry_after))
+
+
 class RuleViolation(DomainError):
     """Raised when a single business rule is violated.
 

{loom_kernel-2.20.2 → loom_kernel-2.22.0}/src/loom/core/job/job.py

@@ -18,7 +18,9 @@ class Job(ABC, Generic[ResultT]):
 
     ``Job`` is independent of ``UseCase`` — it does not inherit from it.
     The compiler and factory operate on ``__execution_plan__`` and
-    ``execute()`` by duck typing, so they support ``Job`` without changes.
+    ``execute()`` by duck typing, so they support ``Job`` without changes,
+    except that the compiler refuses a ``Query()`` parameter on a ``Job``: a
+    job is dispatched with primitive parameters.
 
     Subclass and implement ``execute`` with any typed signature.  The method
     may be ``async def`` or a plain ``def``; the Celery runner detects the

loom_kernel-2.22.0/src/loom/core/model/_json_schema.py

@@ -0,0 +1,35 @@
+"""Reading the JSON Schema a :class:`~loom.core.model.LoomType` publishes.
+
+msgspec puts the root of a model behind ``{"$ref": "#/$defs/Name"}`` and
+pydantic inlines it; both keep nested definitions under ``$defs`` and write
+an optional value as an ``anyOf`` with a ``null`` branch.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+DEFS = "$defs"
+REF = "$ref"
+DEFS_PREFIX = "#/$defs/"
+
+_NULL = {"type": "null"}
+
+
+def definition(schema: Mapping[str, Any], definitions: Mapping[str, Any]) -> Mapping[str, Any]:
+    """Return the definition *schema* references, or *schema* when it references none."""
+    ref = schema.get(REF)
+    return definitions[ref.removeprefix(DEFS_PREFIX)] if ref is not None else schema
+
+
+def without_null(prop: Mapping[str, Any]) -> Mapping[str, Any]:
+    """Return an optional property as its single non-null branch, without a ``None`` default.
+
+    A property that is not ``X | None`` is returned as it is.
+    """
+    options = [option for option in prop.get("anyOf", ()) if option != _NULL]
+    if len(options) != 1:
+        return prop
+    rest = {k: v for k, v in prop.items() if k != "anyOf" and not (k == "default" and v is None)}
+    return {**options[0], **rest}