loom-kernel 0.6.0__tar.gz → 0.7.0__tar.gz

{loom_kernel-0.6.0 → loom_kernel-0.7.0}/CHANGELOG.md

@@ -1,3 +1,101 @@
+# 🚀 Release 0.7.0 ([#25](https://github.com/the-reacher-data/loom-py/pull/25)) ([`0d8941a`](https://github.com/the-reacher-data/loom-py/commit/0d8941a724ec768b162a07e756bac3d53157ec85))
+
+
+## ✨ Features
+### config
+- **config:** add StructBinder and migrate streaming binding resolution<br>
+  > Introduces StructBinder in core/config/binder.py — a Strategy that
+  > injects constructor arguments from a config mapping via msgspec.convert,
+  > covering primitives, Literal constraints, and LoomFrozenStruct subclasses.
+  > Migrates streaming _instantiate_binding to use it, removing ~30 lines of
+  > private helpers and adding typed ConfigError on resolution failures.
+
+- **config:** add ConfigContext for typed section extraction and binding resolution<br>
+  > Single entry-point for runner and bootstrap code to read config:
+  > section() extracts typed sub-trees, bind() injects constructor args
+  > from a config path + overrides, resolve() materializes ConfigBinding
+  > declarations. Accepts an optional StructBinder for strict-mode control.
+
+
+
+## 🐛 Fixes
+### core
+- **core:** clean async bridge timeout and celery typing
+
+### etl
+- **etl:** align missing storage error with config contract
+
+
+
+
+## ♻️ Refactor
+### model
+- **model:** migrate public config structs to LoomFrozenStruct
+
+### streaming
+- **streaming:** clean up _instantiate_binding before extraction<br>
+  > Replace mutable dict() + .update() with a single dict unpacking
+  > Remove the dead param.annotation fallback (get_type_hints already
+  > resolves all forward refs; the fallback silently passed strings to
+  > _is_struct_annotation which always returned False)
+  > Extract _SKIP_KINDS constant to name the variadic-parameter guard
+  > Raise ConfigError instead of TypeError for missing required struct
+  > params (semantically a config error, not a type error; both are
+  > caught by the enclosing _resolve_binding handler so no behaviour
+  > change in streaming)
+  > All 7 binding tests pass.
+
+
+### core
+- **core:** homogenize config and runner boundaries
+- **core:** add runner and compiler protocols
+- **core:** apply runner lifecycle protocols
+- **core:** harden runner lifecycle abstraction<br>
+  > shutdown_runner/flush_runner now catch and log exceptions instead of
+  > propagating, preserving the original exception when called from finally
+  > blocks; contract updated in docstrings and covered by new tests
+  > CompilerProtocol drops @runtime_checkable — no production isinstance
+  > usage existed; Protocol remains valid for static typing
+  > StreamingRunner.prepare_run() calls shutdown_runner(self) before
+  > overwriting self._shutdown, preventing resource leaks on double calls
+  > _build_backend_options extracted from loom.celery.config into
+  > loom.core.async_bridge.build_backend_options, eliminating duplication
+  > between the Celery and streaming domains
+  > _CeleryAsyncRuntime._signals_connected ClassVar removed; the
+  > module-level _SIGNALS_CONNECTED flag is the single source of truth
+  > for the process-level signal guard
+  > ETLRunner.flush() delegates to ETLExecutor.flush(), which checks
+  > SupportsFlush via isinstance instead of getattr duck-typing
+  > TypeVars in compiler.py renamed to _RequestT/_PlanT to signal they
+  > are implementation details of the Protocol, not public API
+
+
+### etl
+- **etl:** make flush an optional runner capability
+
+### celery
+- **celery:** adopt runner shutdown helper
+- **celery:** replace _SIGNALS_CONNECTED sentinel with dispatch_uid<br>
+  > Eliminates the module-level mutable boolean that violated the no-global-
+  > mutable-state architecture rule. Idempotency is now handled by Celery's
+  > dispatch_uid mechanism: disconnect+connect on each call ensures the most-
+  > recently registered closure is always active, so a second bootstrap_worker
+  > call wires up fresh dependencies rather than leaving stale closures from
+  > the first call.
+  > This is strictly better than the sentinel: no global state, no race
+  > condition between threads calling bootstrap_worker concurrently, and
+  > correct closure replacement when called multiple times in tests.
+
+
+### rest
+- **rest:** use observability config directly
+
+
+
+
+
+
+
 # 🚀 Release 0.6.0 ([#22](https://github.com/the-reacher-data/loom-py/pull/22)) ([`5146569`](https://github.com/the-reacher-data/loom-py/commit/51465697115036ed05f620a1099272e4fd216501))
 
 

loom_kernel-0.7.0/CHANGELOG_RELEASE.md

@@ -0,0 +1,96 @@
+# 🚀 Release 0.7.0 ([#25](https://github.com/the-reacher-data/loom-py/pull/25)) ([`0d8941a`](https://github.com/the-reacher-data/loom-py/commit/0d8941a724ec768b162a07e756bac3d53157ec85))
+
+
+## ✨ Features
+### config
+- **config:** add StructBinder and migrate streaming binding resolution<br>
+  > Introduces StructBinder in core/config/binder.py — a Strategy that
+  > injects constructor arguments from a config mapping via msgspec.convert,
+  > covering primitives, Literal constraints, and LoomFrozenStruct subclasses.
+  > Migrates streaming _instantiate_binding to use it, removing ~30 lines of
+  > private helpers and adding typed ConfigError on resolution failures.
+
+- **config:** add ConfigContext for typed section extraction and binding resolution<br>
+  > Single entry-point for runner and bootstrap code to read config:
+  > section() extracts typed sub-trees, bind() injects constructor args
+  > from a config path + overrides, resolve() materializes ConfigBinding
+  > declarations. Accepts an optional StructBinder for strict-mode control.
+
+
+
+## 🐛 Fixes
+### core
+- **core:** clean async bridge timeout and celery typing
+
+### etl
+- **etl:** align missing storage error with config contract
+
+
+
+
+## ♻️ Refactor
+### model
+- **model:** migrate public config structs to LoomFrozenStruct
+
+### streaming
+- **streaming:** clean up _instantiate_binding before extraction<br>
+  > Replace mutable dict() + .update() with a single dict unpacking
+  > Remove the dead param.annotation fallback (get_type_hints already
+  > resolves all forward refs; the fallback silently passed strings to
+  > _is_struct_annotation which always returned False)
+  > Extract _SKIP_KINDS constant to name the variadic-parameter guard
+  > Raise ConfigError instead of TypeError for missing required struct
+  > params (semantically a config error, not a type error; both are
+  > caught by the enclosing _resolve_binding handler so no behaviour
+  > change in streaming)
+  > All 7 binding tests pass.
+
+
+### core
+- **core:** homogenize config and runner boundaries
+- **core:** add runner and compiler protocols
+- **core:** apply runner lifecycle protocols
+- **core:** harden runner lifecycle abstraction<br>
+  > shutdown_runner/flush_runner now catch and log exceptions instead of
+  > propagating, preserving the original exception when called from finally
+  > blocks; contract updated in docstrings and covered by new tests
+  > CompilerProtocol drops @runtime_checkable — no production isinstance
+  > usage existed; Protocol remains valid for static typing
+  > StreamingRunner.prepare_run() calls shutdown_runner(self) before
+  > overwriting self._shutdown, preventing resource leaks on double calls
+  > _build_backend_options extracted from loom.celery.config into
+  > loom.core.async_bridge.build_backend_options, eliminating duplication
+  > between the Celery and streaming domains
+  > _CeleryAsyncRuntime._signals_connected ClassVar removed; the
+  > module-level _SIGNALS_CONNECTED flag is the single source of truth
+  > for the process-level signal guard
+  > ETLRunner.flush() delegates to ETLExecutor.flush(), which checks
+  > SupportsFlush via isinstance instead of getattr duck-typing
+  > TypeVars in compiler.py renamed to _RequestT/_PlanT to signal they
+  > are implementation details of the Protocol, not public API
+
+
+### etl
+- **etl:** make flush an optional runner capability
+
+### celery
+- **celery:** adopt runner shutdown helper
+- **celery:** replace _SIGNALS_CONNECTED sentinel with dispatch_uid<br>
+  > Eliminates the module-level mutable boolean that violated the no-global-
+  > mutable-state architecture rule. Idempotency is now handled by Celery's
+  > dispatch_uid mechanism: disconnect+connect on each call ensures the most-
+  > recently registered closure is always active, so a second bootstrap_worker
+  > call wires up fresh dependencies rather than leaving stale closures from
+  > the first call.
+  > This is strictly better than the sentinel: no global state, no race
+  > condition between threads calling bootstrap_worker concurrently, and
+  > correct closure replacement when called multiple times in tests.
+
+
+### rest
+- **rest:** use observability config directly
+
+
+
+
+

{loom_kernel-0.6.0 → loom_kernel-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loom-kernel
-Version: 0.6.0
+Version: 0.7.0
 Summary: Loom Python project
 License-File: LICENSE
 Requires-Python: >=3.11

{loom_kernel-0.6.0 → loom_kernel-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "loom-kernel"
-version = "0.6.0"
+version = "0.7.0"
 description = "Loom Python project"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -220,7 +220,7 @@ markers = [
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.6.0"
+version = "0.7.0"
 tag_format = "v$version"
 version_files = [
     "pyproject.toml:project.version",

{loom_kernel-0.6.0 → loom_kernel-0.7.0}/src/loom/celery/bootstrap.py

@@ -6,7 +6,7 @@ registration:
 
 1. Load and merge YAML configuration.
 2. Create :class:`~loom.core.di.container.LoomContainer` and register the
-   raw config as an ``APPLICATION``-scope singleton.
+   resolved app config as an ``APPLICATION``-scope singleton.
 3. Execute user-supplied module callables.
 4. Compile all declared ``Job`` subclasses via
    :class:`~loom.core.engine.compiler.UseCaseCompiler`.
@@ -54,9 +54,9 @@ from __future__ import annotations
 
 import importlib
 import inspect
-from collections.abc import Callable, Sequence
+from collections.abc import Callable, Mapping, Sequence
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, Literal, TypeVar
+from typing import Any, Literal, Protocol, TypeVar
 
 import msgspec
 from celery import Celery  # type: ignore[import-untyped]
@@ -69,7 +69,6 @@ from loom.celery.config import (
     CeleryConfig,
     CeleryRuntimeConfig,
     JobConfig,
-    _build_backend_options,
     apply_job_config,
     create_celery_app,
 )
@@ -80,14 +79,15 @@ from loom.celery.runner import (
     _make_callback_task,
     _make_job_task,
 )
+from loom.core.async_bridge import build_backend_options
 from loom.core.backend.sqlalchemy import compile_all, reset_registry
 from loom.core.bootstrap import create_kernel
+from loom.core.config import ConfigContext, ConfigKey
 from loom.core.config.errors import ConfigError
-from loom.core.config.keys import ConfigKey
-from loom.core.config.loader import load_config, section
 from loom.core.di.container import LoomContainer
 from loom.core.discovery._utils import collect_from_modules, import_modules
 from loom.core.engine.compilable import Compilable
+from loom.core.engine.metrics import MetricsAdapter
 from loom.core.job.job import Job
 from loom.core.model import BaseModel
 from loom.core.observability.config import ObservabilityConfig
@@ -95,15 +95,11 @@ from loom.core.observability.runtime import ObservabilityRuntime
 from loom.core.repository.sqlalchemy import build_sqlalchemy_repository_registration_module
 from loom.core.repository.sqlalchemy.session_manager import SessionManager
 from loom.core.repository.sqlalchemy.uow import SQLAlchemyUnitOfWorkFactory
+from loom.core.runner import shutdown_runner
 from loom.core.uow.abc import UnitOfWorkFactory
 from loom.core.use_case.factory import UseCaseFactory
 from loom.rest.autocrud import build_auto_routes
 
-if TYPE_CHECKING:
-    from omegaconf import DictConfig
-
-    from loom.core.engine.metrics import MetricsAdapter
-
 _T = TypeVar("_T")
 
 
@@ -203,22 +199,30 @@ class _WorkerResolved:
 # Celery worker lifecycle signals
 # ---------------------------------------------------------------------------
 
+_WORKER_INIT_UID = "loom.celery.worker.init"
+_WORKER_SHUTDOWN_UID = "loom.celery.worker.shutdown"
+
+
+class _AsyncRuntimeProtocol(Protocol):
+    def initialize(self) -> None: ...
+
+    def run(self, coro: Any, *, eager_fallback: bool) -> Any: ...
 
-_SIGNALS_CONNECTED = False
+    def shutdown(self) -> None: ...
 
 
 def _build_async_runtime(runtime_cfg: CeleryRuntimeConfig) -> _CeleryAsyncRuntime:
     """Build the per-process async runtime used by Celery worker tasks."""
     return _CeleryAsyncRuntime(
         backend=runtime_cfg.backend,
-        backend_options=_build_backend_options(runtime_cfg.backend, runtime_cfg.use_uvloop),
+        backend_options=build_backend_options(runtime_cfg.backend, runtime_cfg.use_uvloop),
         shutdown_timeout_ms=runtime_cfg.shutdown_timeout_ms,
     )
 
 
 def _connect_worker_signals(
     session_manager: SessionManager | None,
-    async_runtime: _CeleryAsyncRuntime,
+    async_runtime: _AsyncRuntimeProtocol,
 ) -> None:
     """Connect Celery worker lifecycle signals for per-process bridge management.
 
@@ -229,9 +233,12 @@ def _connect_worker_signals(
     * ``worker_process_shutdown`` — disposes the session manager through
       the bridge, then shuts it down.
 
-    Idempotent: subsequent calls within the same process are no-ops.
-    This prevents handler accumulation when :func:`bootstrap_worker` is
-    called more than once (e.g. in integration tests without full isolation).
+    Idempotency is guaranteed by ``dispatch_uid``: subsequent calls replace
+    the active closures rather than accumulating handlers.  This means that
+    when :func:`bootstrap_worker` is called more than once (e.g. in
+    integration tests), the most-recently registered ``session_manager`` and
+    ``async_runtime`` are always the ones used at shutdown — no stale
+    closures remain active.
 
     Args:
         session_manager: The shared :class:`~SessionManager` instance
@@ -239,9 +246,6 @@ def _connect_worker_signals(
             on shutdown when present.
         async_runtime: Per-process async bridge runtime used for async jobs.
     """
-    global _SIGNALS_CONNECTED
-    if _SIGNALS_CONNECTED:
-        return
 
     def _on_init(**kwargs: Any) -> None:
         async_runtime.initialize()
@@ -259,21 +263,24 @@ def _connect_worker_signals(
                     close()
             raise
         finally:
-            async_runtime.shutdown()
+            shutdown_runner(async_runtime)
 
-    worker_process_init.connect(_on_init, weak=False)
-    worker_process_shutdown.connect(_on_shutdown, weak=False)
-    _CeleryAsyncRuntime._signals_connected = True
-    _SIGNALS_CONNECTED = True
+    worker_process_init.disconnect(dispatch_uid=_WORKER_INIT_UID)
+    worker_process_init.connect(_on_init, weak=False, dispatch_uid=_WORKER_INIT_UID)
+    worker_process_shutdown.disconnect(dispatch_uid=_WORKER_SHUTDOWN_UID)
+    worker_process_shutdown.connect(_on_shutdown, weak=False, dispatch_uid=_WORKER_SHUTDOWN_UID)
 
 
-def _resolve_uow_factory(raw: DictConfig) -> tuple[UnitOfWorkFactory | None, SessionManager | None]:
+def _resolve_uow_factory(
+    ctx: ConfigContext | Mapping[str, Any],
+) -> tuple[UnitOfWorkFactory | None, SessionManager | None]:
     """Return SQLAlchemy UoW factory when database config is present.
 
     This keeps worker bootstrap lightweight for pure jobs that do not use DB.
     """
+    config = _ensure_config_context(ctx)
     try:
-        db_cfg = section(raw, ConfigKey.DATABASE, _WorkerDbConfig)
+        db_cfg = config.section(ConfigKey.DATABASE, _WorkerDbConfig)
     except ConfigError:
         return None, None
 
@@ -291,19 +298,22 @@ def _resolve_uow_factory(raw: DictConfig) -> tuple[UnitOfWorkFactory | None, Ses
 # ---------------------------------------------------------------------------
 
 
-def _apply_job_config_if_present(raw: DictConfig, job_type: type[Job[Any]]) -> None:
+def _apply_job_config_if_present(
+    ctx: ConfigContext | Mapping[str, Any],
+    job_type: type[Job[Any]],
+) -> None:
     """Apply ``JobConfig`` overrides from YAML to ``job_type``'s ClassVars.
 
     Silently skips when the ``jobs.<JobTypeName>`` section is absent — the
     Job's ClassVar defaults remain unchanged.
 
     Args:
-        raw: Root :class:`omegaconf.DictConfig` returned by
-            :func:`~loom.core.config.loader.load_config`.
+        ctx: Resolved configuration context.
         job_type: Concrete ``Job`` subclass to configure.
     """
+    config = _ensure_config_context(ctx)
     try:
-        cfg = section(raw, f"{ConfigKey.JOBS}.{job_type.__name__}", JobConfig)
+        cfg = config.section(f"{ConfigKey.JOBS}.{job_type.__name__}", JobConfig)
         apply_job_config(job_type, cfg)
     except ConfigError:
         pass  # no override for this job — use ClassVar defaults
@@ -524,25 +534,27 @@ def _discover_compilables_from_config(
     return _discover_from_manifest(discovery_cfg)
 
 
-def _try_discover_components(raw: DictConfig) -> _WorkerResolved:
+def _try_discover_components(ctx: ConfigContext | Mapping[str, Any]) -> _WorkerResolved:
     """Best-effort discovery; returns empty _WorkerResolved if config is absent."""
+    config = _ensure_config_context(ctx)
     try:
-        app_cfg = section(raw, ConfigKey.APP, _WorkerAppConfig)
+        app_cfg = config.section(ConfigKey.APP, _WorkerAppConfig)
         return _discover_compilables_from_config(app_cfg.discovery)
     except (ConfigError, RuntimeError, ValueError, TypeError):
         return _WorkerResolved(compilables=(), jobs=(), models=(), callbacks=())
 
 
 def _resolve_compilables_and_jobs(
-    raw: DictConfig,
+    ctx: ConfigContext | Mapping[str, Any],
     explicit_jobs: Sequence[type[Job[Any]]],
     explicit_use_cases: Sequence[type[Compilable]],
 ) -> _WorkerResolved:
     """Resolve worker components from explicit args and/or discovery config."""
+    config = _ensure_config_context(ctx)
     if explicit_jobs or explicit_use_cases:
         jobs = tuple(explicit_jobs)
         compilables = _merge_unique(explicit_use_cases, jobs)
-        discovered = _try_discover_components(raw)
+        discovered = _try_discover_components(config)
         extra = tuple(c for c in discovered.compilables if c not in set(compilables))
         return _WorkerResolved(
             compilables=(*compilables, *extra),
@@ -552,7 +564,7 @@ def _resolve_compilables_and_jobs(
         )
 
     try:
-        app_cfg = section(raw, ConfigKey.APP, _WorkerAppConfig)
+        app_cfg = config.section(ConfigKey.APP, _WorkerAppConfig)
     except ConfigError as exc:
         raise RuntimeError(
             "No jobs provided and no app.discovery configured for worker bootstrap."
@@ -594,10 +606,13 @@ def _compile_models(models: Sequence[type[BaseModel]]) -> tuple[type[BaseModel],
 # ---------------------------------------------------------------------------
 
 
-def _build_observability_runtime(raw: DictConfig) -> ObservabilityRuntime:
+def _build_observability_runtime(
+    ctx: ConfigContext | Mapping[str, Any],
+) -> ObservabilityRuntime:
     """Build the shared observability runtime from top-level config."""
+    config = _ensure_config_context(ctx)
     try:
-        observability_cfg = section(raw, ConfigKey.OBSERVABILITY, ObservabilityConfig)
+        observability_cfg = config.section(ConfigKey.OBSERVABILITY, ObservabilityConfig)
     except ConfigError:
         observability_cfg = ObservabilityConfig()
     return ObservabilityRuntime.from_config(observability_cfg)
@@ -642,6 +657,13 @@ def _emit_worker_init_graph(components: _WorkerResolved) -> None:
     )
 
 
+def _ensure_config_context(source: ConfigContext | Mapping[str, Any]) -> ConfigContext:
+    """Return a :class:`ConfigContext` for any supported config input."""
+    if isinstance(source, ConfigContext):
+        return source
+    return ConfigContext.from_dict(source)
+
+
 # ---------------------------------------------------------------------------
 # Result
 # ---------------------------------------------------------------------------
@@ -750,21 +772,22 @@ def bootstrap_worker(
         )
         result.celery_app.start()
     """
-    raw = load_config(*config_paths)
-    celery_cfg = section(raw, ConfigKey.CELERY, CeleryConfig)
-    observability_runtime = _build_observability_runtime(raw)
+    ctx = ConfigContext.from_yaml(*config_paths)
+    app_cfg = ctx.section_optional(ConfigKey.APP, _WorkerAppConfig) or _WorkerAppConfig()
+    celery_cfg = ctx.section(ConfigKey.CELERY, CeleryConfig)
+    observability_runtime = _build_observability_runtime(ctx)
     async_runtime = _build_async_runtime(celery_cfg.runtime)
 
-    resolved = _resolve_compilables_and_jobs(raw, jobs, use_cases)
+    resolved = _resolve_compilables_and_jobs(ctx, jobs, use_cases)
     all_compilables = _merge_unique(
         resolved.compilables,
         _use_cases_from_interfaces(interfaces),
     )
 
     for job_type in resolved.jobs:
-        _apply_job_config_if_present(raw, job_type)
+        _apply_job_config_if_present(ctx, job_type)
 
-    uow_factory, session_manager = _resolve_uow_factory(raw)
+    uow_factory, session_manager = _resolve_uow_factory(ctx)
     final_models, runtime_modules = _compile_db_layer(session_manager, resolved.models, modules)
 
     resolved = _WorkerResolved(
@@ -776,7 +799,7 @@ def bootstrap_worker(
     _emit_worker_init_graph(resolved)
 
     kernel = create_kernel(
-        config=raw,
+        config=app_cfg,
         use_cases=resolved.compilables,
         modules=runtime_modules,
         metrics=metrics,

{loom_kernel-0.6.0 → loom_kernel-0.7.0}/src/loom/celery/config.py

@@ -30,7 +30,6 @@ Typical YAML layout::
 
 from __future__ import annotations
 
-import sys
 from typing import TYPE_CHECKING, Any, Literal
 
 import msgspec
@@ -172,15 +171,6 @@ def apply_job_config(job_type: type[Job[Any]], cfg: JobConfig) -> None:
             setattr(job_type, class_var, value)
 
 
-def _build_backend_options(backend: str, use_uvloop: bool) -> dict[str, Any]:
-    """Return AnyIO backend options for an async bridge."""
-    if backend == "asyncio" and use_uvloop and sys.platform != "win32":
-        import uvloop  # guarded by sys_platform marker in pyproject.toml
-
-        return {"loop_factory": uvloop.new_event_loop}
-    return {}
-
-
 def create_celery_app(cfg: CeleryConfig) -> Celery:
     """Build a Celery application from a ``CeleryConfig``.
 

{loom_kernel-0.6.0 → loom_kernel-0.7.0}/src/loom/celery/runner.py

@@ -25,7 +25,7 @@ import inspect
 import time
 from contextvars import Token
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, ClassVar
+from typing import TYPE_CHECKING, Any
 
 from celery import Celery  # type: ignore[import-untyped]
 from celery.result import AsyncResult  # type: ignore[import-untyped]
@@ -49,11 +49,6 @@ if TYPE_CHECKING:
 class _CeleryAsyncRuntime:
     """Per-process async bridge for Celery worker coroutines."""
 
-    # Class-level guard: signals must be connected exactly once per process.
-    # Stored on the class (not the instance) because it reflects process state,
-    # not a property of any particular runtime object.
-    _signals_connected: ClassVar[bool] = False
-
     backend: str = "asyncio"
     backend_options: dict[str, Any] = field(default_factory=dict)
     shutdown_timeout_ms: int | None = None

{loom_kernel-0.6.0 → loom_kernel-0.7.0}/src/loom/core/async_bridge.py

@@ -28,6 +28,7 @@ Thread safety:
 from __future__ import annotations
 
 import logging
+import sys
 import threading
 from collections.abc import Coroutine
 from typing import Any, TypeVar, cast
@@ -39,6 +40,23 @@ logger = logging.getLogger(__name__)
 T = TypeVar("T")
 
 
+def build_backend_options(backend: str, use_uvloop: bool) -> dict[str, Any]:
+    """Build AnyIO backend options for the shared async bridge contract.
+
+    Args:
+        backend: AnyIO backend name.
+        use_uvloop: Whether asyncio should use uvloop when available.
+
+    Returns:
+        A backend-options mapping suitable for :class:`AsyncBridge`.
+    """
+    if backend == "asyncio" and use_uvloop and sys.platform != "win32":
+        import uvloop  # guarded by sys_platform marker in pyproject.toml
+
+        return {"loop_factory": uvloop.new_event_loop}
+    return {}
+
+
 class AsyncBridge:
     """Anyio blocking portal wrapper for sync-to-async execution.
 
@@ -94,8 +112,13 @@ class AsyncBridge:
         if self._closed:
             coro.close()
             raise RuntimeError("AsyncBridge has been shut down.")
+
+        async def _await_coro_with_timeout() -> T:
+            with anyio.fail_after(timeout):
+                return await coro
+
         if timeout is not None:
-            return cast(T, self._portal.call(_await_with_timeout, coro, timeout))
+            return self._portal.call(_await_coro_with_timeout)
         return cast(T, self._portal.call(_await_coro, coro))
 
     @property
@@ -139,11 +162,6 @@ async def _await_coro(coro: Coroutine[Any, Any, T]) -> T:
     return await coro
 
 
-async def _await_with_timeout(coro: Coroutine[Any, Any, T], timeout: float) -> T:  # noqa: S7483
-    with anyio.fail_after(timeout):
-        return await coro
-
-
 AsyncWorker = AsyncBridge
 
-__all__ = ["AsyncBridge", "AsyncWorker"]
+__all__ = ["AsyncBridge", "AsyncWorker", "build_backend_options"]

{loom_kernel-0.6.0 → loom_kernel-0.7.0}/src/loom/core/cache/abc/config.py

@@ -4,8 +4,10 @@ from typing import Any
 
 import msgspec
 
+from loom.core.model import LoomFrozenStruct
 
-class CacheConfig(msgspec.Struct, kw_only=True):
+
+class CacheConfig(LoomFrozenStruct, frozen=True, kw_only=True):
     """Configuration for cache behaviour including TTLs and aiocache backend settings.
 
     Attributes:

loom_kernel-0.7.0/src/loom/core/compiler.py

@@ -0,0 +1,24 @@
+"""Compiler contracts shared by Loom domains.
+
+Compilers translate a request object into an executable plan. The concrete
+request and plan types vary by domain; this protocol only captures the
+shape of the transformation.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, TypeVar
+
+_RequestT = TypeVar("_RequestT", contravariant=True)
+_PlanT = TypeVar("_PlanT", covariant=True)
+
+
+class CompilerProtocol(Protocol[_RequestT, _PlanT]):
+    """Structural protocol for a compiler that materializes an execution plan."""
+
+    def compile(self, request: _RequestT) -> _PlanT:
+        """Transform *request* into an executable plan."""
+        ...
+
+
+__all__ = ["CompilerProtocol"]