loom-kernel 2.22.3__tar.gz → 4.0.0__tar.gz

{loom_kernel-2.22.3 → loom_kernel-4.0.0}/CHANGELOG.md

@@ -459,6 +459,85 @@
 
 ### core
 
+- **core:** with no `LOOM_ENV` and no `environment=`, a process starts as
+  `production` and runs the deploy checks; an API without authentication now
+  fails at startup with `loom.rest.E001` until it configures
+  `app.rest.auth.jwt`, sets `app.rest.auth.custom: true` and passes an
+  `authenticator`, sets `LOOM_ENV=development`, or lists the id under
+  `checks.silenced`. An unknown or empty `LOOM_ENV` is a startup error.
+- **core:** the logger's default changed from development to production: with
+  no explicit `renderer`/`colors`, logs render as JSON without colours unless
+  the process resolved `development` or `test`. `create_kernel`,
+  `bootstrap_app`, `ObservabilityRuntime.from_config`, `configure_logging`
+  and `configure_logging_from_values` take `environment=None` and resolve it
+  (`LOOM_ENV`, else production) when none is passed.
+- **core:** the logger's own environment is removed:
+  `loom.core.logger.Environment`, `LoggerConfig.environment` and
+  `LogConfig.environment` are gone, and the logging functions take
+  `loom.core.environment.Environment`.
+- **core:** configuration sections refuse keys they do not declare: the
+  logger and its handlers, `checks`, `app.rest` (with `auth`, `jwt`, `cors`
+  and `discovery`), the `observability` log, otel and prometheus structs and
+  `OtelConfig`, `sql`, `celery` and `jobs`, every ETL `storage` struct and
+  lineage, `kafka`, the bytewax runtime, streaming `mongo`, `dynamodb` and the
+  flow config. A leftover `observability.log.config.environment`, or any
+  typo there, is a `ConfigError`. `app`, `database`, `persistence` and the
+  top of `observability`, which several readers decode in part, still accept
+  keys another reader owns. `create_app` and `bootstrap_worker` no longer fall
+  back to the default `observability` section when it fails validation, and
+  `create_app` registers the in-process job service when the `celery`
+  section is absent (with a warning) or the Celery extra is not installed; a
+  `celery` section that fails validation now stops startup instead.
+- **core:** a `LOOM__*` override sets one leaf value. A variable naming no
+  known section, with a malformed level, whose value is or holds a mapping,
+  whose target the files declare as a mapping or a list of mappings, naming
+  `config`, holding `${` however it is written, reaching inside an
+  interpolated key, failing to parse, or colliding with another variable
+  stops startup naming the variable, never the value. In production and
+  staging an override may set only an allowlisted key: loom's operational
+  keys (`loom.core.config.overrides.OVERRIDABLE`: log levels, Celery and
+  streaming worker counts and timeouts, SQL pool sizes and driver timeouts)
+  and the keys the reviewed files list under `config.overridable`. A
+  `config.overridable` entry starting with `*`, or inside `checks` or
+  `config`, stops every load. A placeholder in the `checks` section is a
+  `ConfigError`. A per-flow Prefect YAML is read without overrides.
+  `ConfigKey.LOGGER` and `ConfigKey.METRICS`, read by nothing, are removed.
+- **core:** the SQL `max_execution_time`, `connect_timeout`,
+  `send_receive_timeout`, `pool_size` and `executor_threads`, the Celery
+  `runtime.shutdown_timeout_ms` and the streaming runtime's
+  `epoch_interval_ms` and `force_shutdown_timeout_ms` must be above zero; a
+  `0` fails when the section decodes.
+- **core:** the `loom.core.checks` logger sets its own WARNING level, so a
+  parent level (`CRITICAL`, top-level or `named_levels.loom`) cannot hide a
+  deploy check's warning or the silenced ids; name `loom.core.checks` under
+  `named_levels` to quiet it. The handlers `configure_logging` attaches no
+  longer filter by level, so a named level below the top-level level takes
+  effect for stdlib loggers; structlog loggers, loom's own included, still
+  drop events below the top-level level.
+- **core:** a consumer's test suite must set `LOOM_ENV=test` (loom's own
+  sets it in `tests/conftest.py`), or every application it builds starts as
+  production and runs the deploy checks.
+- **core:** the migration locator now resolves `LOOM_ENV` (picking the
+  overlay of a config directory), applies the `LOOM__*` variables and puts
+  `app.code_path` on `sys.path` when the directory exists, as the
+  application does. `loom check --deploy` refuses an `app.code_path` that is
+  not a literal path.
+- **core:** `ETLRunner` and `StreamingRunner` resolve the environment
+  (`LOOM_ENV`, else production): without one they log JSON and, built from a
+  whole configuration (a file, a directory, or a mapping for
+  `StreamingRunner.from_dict`), run the deploy checks; `ETLRunner.from_dict`
+  and `from_spark` receive no whole configuration and run none.
+- **core:** `loom.core.locator.CONFIG_ENV_VAR` is replaced by
+  `loom.core.environment.CONFIG_VARIABLE`; `LOOM_CONFIG` may name a config
+  directory. `loom.prefect`'s `LOOM_ETL_CONFIG` alias is removed; use
+  `loom.core.environment.ETL_CONFIG_VARIABLE`. `app.code_path` is added to
+  `sys.path` only when the directory exists.
+- **core:** a non-deployed environment logs one WARNING that the deploy
+  checks were skipped.
+- **rest:** `create_app(authenticator=...)` requires
+  `app.rest.auth.custom: true`, `custom: true` requires an `authenticator`,
+  and `custom: true` beside `app.rest.auth.jwt` is refused; `loom.rest.E001`
+  passes on `custom: true`.
 - **core:** `Rule.check(..., via=fn)` takes the violation from `fn`: a `str`
   (the message) or a `RuleViolation` fails the rule, `None` passes it. A `bool`
   or any other result raises `TypeError` naming the field, instead of `True`
@@ -602,6 +681,37 @@
 
 ### rest
 
+- **rest:** a `QuerySpec` route filters and sorts only on the columns it
+  declares. Before, a client could filter or sort on any field the repository
+  could resolve. Now a filter on an undeclared column answers
+  `400 unsupported_query` naming the field, and so does a sort on one, with the
+  same answer whether or not the column exists. The primary key, which the
+  route orders by when the client names no sort, needs no declaration.
+  Declare `filterable` and `sortable` on the interface (its auto-CRUD `list`
+  route included) or on a route, which overrides it, as field references or
+  column names:
+
+  ```python
+  class OrderRestInterface(RestInterface[Order]):
+      prefix = "/orders"
+      auto = True
+      filterable = (F(Order).status, F(Order).total)
+      sortable = (F(Order).created_at,)
+  ```
+
+  In `app.rest.interfaces` both take column names (`[status, total]`).
+  `ALL` (`all` in YAML) keeps every scalar column and logs a warning naming
+  the route at startup. Only scalar columns of the use case's own model
+  (`UseCase[Model, ...]`) qualify. A related model's column (`warehouse.code`)
+  is refused, and so are JSON, array and text-search columns; lists, dicts
+  and structs, and an `Enum` or `Literal` declared without a column type, are
+  JSON. `InterfaceCompilationError` names the route and the field. It is also
+  raised for a declaration on a use case with no model, and for a route-level
+  declaration on a route without a `QuerySpec`; an inherited one is ignored.
+  `exists` and `not_exists` answer `400 unsupported_query`, and so do `like`
+  and `ilike` on a column that is not `str`. The repository's
+  `allowed_filter_fields` is unchanged: programmatic callers are not
+  restricted.
 - **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.
@@ -633,6 +743,20 @@
 
 ### prefect
 
+- **prefect:** `FlowCtx.environment` is removed; nothing read it.
+- **prefect:** the flow parameter `env` and the keys of a flow YAML's
+  `environments` block are loom environments (`production`, `staging`,
+  `development`, `test`); `prod`, `dev`, `local` or any other key or value is
+  a `ConfigError`. A run resolves the worker's environment (`LOOM_ENV`, else
+  production); `env` defaults to `None` and only confirms it, so a run whose
+  `env` differs fails before anything runs. The run hands the environment to
+  the runner, which takes its logger defaults from it and runs the deploy
+  checks when deployed; notifications report it. `deploy_flow` and
+  `discover_and_deploy_etls` take an optional `env` resolved the same way and
+  record it as the deployment's `env` parameter, so a deployment run on a
+  worker in another environment fails.
+- **prefect:** the storage configuration of a flow run may be a config
+  directory.
 - **prefect:** a placeholder counts from the run's scheduled start instead of
   the wall clock. `${today-1d}`, `${yesterday}` and `${now±N}` counted from
   `datetime.now()` inside the flow, so a queued run that started after
@@ -767,6 +891,60 @@
 
 ### core
 
+- **core:** one environment selector and deploy checks (ADR 0005). loom had
+  two unconnected notions of environment (the logger's `dev`/`prod`, where an
+  unknown value meant `dev`, and `FlowCtx.environment`) and nothing checked a
+  deployed configuration. `loom.core.environment` now holds
+  `Environment` (`production`, `staging`, `development`, `test`) and
+  `resolve_environment`: the explicit argument, else `LOOM_ENV`, else
+  `production`; an unknown or empty value raises `ConfigError`. REST
+  `create_app`, Celery `create_app` and `bootstrap_worker` take
+  `environment=` and `config_dir=`, which loads `base.yaml` then
+  `<environment>.yaml` when present; explicit file lists keep working, one
+  form or the other. `create_kernel(environment=...)` registers the
+  environment in the container, so a use case can inject `Environment`.
+  `loom.core.checks` adds deploy checks with stable ids
+  (`@deploy_check("<area>.<E|W><nnn>")`), run at startup in production and
+  staging: `E` fails startup with `DeployCheckError`, `W` logs a warning, and
+  `checks.silenced: [ids]` silences by id with a startup warning naming them.
+  Initial checks: `loom.rest.E001` (neither a literal `app.rest.auth.jwt`
+  mapping nor the literal `app.rest.auth.custom: true`), `loom.rest.W001` (docs, redoc or OpenAPI
+  URL not `null`), `loom.logger.W001` (`console` renderer); they read keys as
+  written (`ConfigContext.raw`) and resolve no placeholder. Processes serving
+  no HTTP skip the `loom.rest` checks. `loom check --deploy [--env X]
+  [--skip AREA] <config>` runs them in CI without starting the application
+  and prints the areas it skipped.
+- **core:** one place tells every loom process its environment and
+  configuration (ADR 0005). `LOOM__SECTION__KEY` variables override any
+  configuration key as the last layer (code defaults < `base.yaml` <
+  `<LOOM_ENV>.yaml` < `LOOM__*`, allowlisted keys only in production and
+  staging), merged as an OmegaConf dotlist; levels
+  match declared keys case-insensitively, a first level naming no known
+  section is a `ConfigError` naming the variable, values are parsed literals
+  (no `${` anywhere in them), an override sets one leaf, and one WARNING
+  line names the overridden keys without their values.
+  `loom.core.config.overrides.load_application_config` is the one loader
+  behind REST and Celery `create_app`, `bootstrap_worker`,
+  `loom check --deploy`, `ETLRunner.from_yaml`, `StreamingRunner.from_yaml`,
+  the migration locator and `load_kafka_settings`; a per-flow Prefect YAML is
+  a flow definition and is read without them. Deploy checks see the final configuration. `ETLRunner`,
+  `StreamingRunner` and the migration locator accept a config directory as
+  the factories do. They take `environment=`, take their logger defaults from
+  it and run the deploy checks when deployed, like the Prefect flows through
+  them; a Prefect run's `env` only confirms the worker's environment.
+  Only `loom.core.environment` names, reads or sets `LOOM_*` variables.
+  `checks.modules` lists the modules registering an
+  application's own checks, imported before every run, at startup and in
+  `loom check --deploy` (which puts `app.code_path` on the import path as
+  `create_app` does). `app.rest.auth.custom: true` declares an authenticator
+  passed in code, so `loom.rest.E001` reads the same answer in CI and at
+  startup. `parse_environment` validates a value naming an environment.
+- **core:** the SQLAlchemy query compiler converts a filter value, and each
+  `in` item, as the repository converts a value it writes
+  (`loom.core.repository.sqlalchemy.values.to_column_value`, now shared by
+  both): an `Enum` member is bound as its value, a JSON column's value is
+  reduced to builtins. A plain `Enum` member as the value of a filter on a
+  string column failed to bind.
 - **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
@@ -953,6 +1131,29 @@
 
 ### rest
 
+- **rest:** `?sort=` accepted any column. A cursor page put the sort
+  column's raw value of its last row in `nextCursor` (base64 JSON), so any
+  column, a secret one included, could be read through it, and a forged
+  cursor could range-probe it. Offset pages leaked its order, and an unknown
+  column answered `400 unsupported_query` (`Unknown filter field path`) while
+  a known one answered `200`, so the model's columns could be enumerated. A
+  route now sorts only by its declared `sortable` columns and its primary
+  key, so a cursor carries only those values.
+- **rest:** a `page` whose offset, `(page - 1) * limit`, exceeds the largest
+  signed 64-bit integer answers `400 query_validation` on `page` before any
+  query runs.
+- **rest:** a `QuerySpec` filter value was typed by its spelling: `true` and
+  `false` became booleans, text with a `.` a float and digits an integer,
+  whatever the filtered field declared. `?code=0123` on a `str` field compared
+  against `123`, and on Postgres a number bound to a text column answered
+  `500`. Values of `eq`, `ne`, `gt`, `gte`, `lt`, `lte` and each item of `in`
+  are now converted by the type of the declared filterable field, with the
+  strict grammar of `Query()`: a `str` field keeps the text as sent, a
+  boolean accepts only `true` or `false`, an `Enum` or `Literal` only its
+  values, and a value its field's type refuses answers `400 query_validation`
+  with `violations` naming the field. The field's constraints
+  (`msgspec.Meta`) do not apply to a filter value, so `rank__gt=0` is valid
+  on a column declared `ge=1`. `like` and `ilike` keep their pattern as text.
 - **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

{loom_kernel-2.22.3 → loom_kernel-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.22.3
+Version: 4.0.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
@@ -484,6 +484,10 @@ from loom.rest.fastapi.auto import create_app
 app = create_app("config/api.yaml")
 ```
 
+Run it with `LOOM_ENV=development`: an unset `LOOM_ENV` means production, where
+the deploy checks refuse an API that authenticates nobody (`loom.rest.E001`).
+See [Environments and deploy checks](docs/getting-started/environments.md).
+
 For larger projects, use `mode: manifest` and a manifest module:
 
 ```python

{loom_kernel-2.22.3 → loom_kernel-4.0.0}/README.md

@@ -360,6 +360,10 @@ from loom.rest.fastapi.auto import create_app
 app = create_app("config/api.yaml")
 ```
 
+Run it with `LOOM_ENV=development`: an unset `LOOM_ENV` means production, where
+the deploy checks refuse an API that authenticates nobody (`loom.rest.E001`).
+See [Environments and deploy checks](docs/getting-started/environments.md).
+
 For larger projects, use `mode: manifest` and a manifest module:
 
 ```python

{loom_kernel-2.22.3 → loom_kernel-4.0.0}/src/loom/celery/auto.py

@@ -13,11 +13,14 @@ from loom.core.di.container import LoomContainer
 if TYPE_CHECKING:
     from loom.core.config import ConfigResolver
     from loom.core.engine.metrics import MetricsAdapter
+    from loom.core.environment import Environment
     from loom.core.job.job import Job
 
 
 def create_app(
     *config_paths: str,
+    config_dir: str | None = None,
+    environment: Environment | str | None = None,
     jobs: Sequence[type[Job[Any]]] = (),
     callbacks: Sequence[type[Any]] = (),
     modules: Sequence[Callable[[LoomContainer], None]] = (),
@@ -27,7 +30,12 @@ def create_app(
     """Create a Celery app with all Loom job tasks registered.
 
     Args:
-        *config_paths: One or more YAML config files merged left-to-right.
+        *config_paths: YAML config files merged left-to-right. Mutually
+            exclusive with *config_dir*.
+        config_dir: Directory holding ``base.yaml`` and the per-environment
+            overlays; ``<environment>.yaml`` loads after the base when present.
+        environment: Environment of the worker; overrides ``LOOM_ENV``, which
+            defaults to production when unset.
         jobs: Concrete ``Job`` subclasses to register as Celery tasks.
             Optional when ``app.discovery`` (modules/manifest) is configured.
         callbacks: Optional callback classes for success/failure hooks.
@@ -42,6 +50,8 @@ def create_app(
     """
     result = bootstrap_worker(
         *config_paths,
+        config_dir=config_dir,
+        environment=environment,
         jobs=jobs,
         callbacks=callbacks,
         modules=modules,

{loom_kernel-2.22.3 → loom_kernel-4.0.0}/src/loom/celery/bootstrap.py

@@ -83,6 +83,7 @@ from loom.celery.runner import (
 from loom.core.async_bridge import build_backend_options
 from loom.core.bootstrap import KernelRuntime, create_kernel
 from loom.core.cache.wiring import cache_module_for
+from loom.core.checks import REST_CHECKS, enforce_deploy_checks
 from loom.core.config import (
     ConfigContext,
     ConfigKey,
@@ -90,10 +91,12 @@ from loom.core.config import (
     with_default_resolvers,
 )
 from loom.core.config.errors import ConfigError
+from loom.core.config.overrides import load_application_config
 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.environment import Environment, resolve_environment, select_config_paths
 from loom.core.job.job import Job
 from loom.core.model import BaseModel
 from loom.core.observability.config import ObservabilityConfig
@@ -666,14 +669,18 @@ def _compile_models(
 
 def _build_observability_runtime(
     ctx: ConfigContext | Mapping[str, Any],
+    environment: Environment = Environment.PRODUCTION,
 ) -> ObservabilityRuntime:
-    """Build the shared observability runtime from top-level config."""
+    """Build the shared observability runtime from top-level config.
+
+    Defaults apply only when the section is absent; one that fails validation
+    stops the worker instead of silently dropping its settings.
+    """
     config = _ensure_config_context(ctx)
-    try:
-        observability_cfg = config.section(ConfigKey.OBSERVABILITY, ObservabilityConfig)
-    except ConfigError:
-        observability_cfg = ObservabilityConfig()
-    return ObservabilityRuntime.from_config(observability_cfg)
+    observability_cfg = config.section_or_default(
+        ConfigKey.OBSERVABILITY, ObservabilityConfig, ObservabilityConfig()
+    )
+    return ObservabilityRuntime.from_config(observability_cfg, environment=environment)
 
 
 def _compile_db_layer(
@@ -835,6 +842,8 @@ def _reject_mcp_markers(
 
 def bootstrap_worker(
     *config_paths: str,
+    config_dir: str | None = None,
+    environment: Environment | str | None = None,
     jobs: Sequence[type[Job[Any]]] = (),
     use_cases: Sequence[type[Compilable]] = (),
     interfaces: Sequence[type[Any]] = (),
@@ -845,9 +854,15 @@ def bootstrap_worker(
 ) -> WorkerBootstrapResult:
     """Bootstrap a Celery worker process and register all Job tasks.
 
-    Loads configuration from ``config_paths``, compiles all ``Job``
-    subclasses, registers Celery tasks, and connects worker lifecycle
-    signals for per-process async bridge management.
+    Resolves the environment once (*environment*, else ``LOOM_ENV``, else
+    production; see :mod:`loom.core.environment`), loads configuration from
+    ``config_dir`` or ``config_paths``, compiles all ``Job`` subclasses,
+    registers Celery tasks, and connects worker lifecycle signals for
+    per-process async bridge management.
+
+    In production and staging the deploy checks run (see
+    :mod:`loom.core.checks`), except the ``loom.rest`` ones: a worker serves
+    no HTTP. The environment is registered in the container.
 
     This function is **independent** of
     :func:`~loom.core.bootstrap.bootstrap.bootstrap_app` — it targets the
@@ -865,9 +880,14 @@ def bootstrap_worker(
     persistence.
 
     Args:
-        *config_paths: One or more paths to YAML configuration files.
-            Files are merged left-to-right.  Later files override earlier
-            ones.
+        *config_paths: Paths to YAML configuration files, merged
+            left-to-right; later files override earlier ones. Mutually
+            exclusive with *config_dir*.
+        config_dir: Local directory holding ``base.yaml`` and the
+            per-environment overlays: ``base.yaml`` loads first, then
+            ``<environment>.yaml`` when present. Either way the
+            ``LOOM__SECTION__KEY`` variables merge last.
+        environment: Environment of the worker; overrides ``LOOM_ENV``.
         jobs: Concrete ``Job`` subclasses to compile/register.  When
             omitted, jobs are discovered from ``app.discovery`` using
             mode ``modules`` or ``manifest``.
@@ -899,8 +919,11 @@ def bootstrap_worker(
         configured Celery application.
 
     Raises:
-        ConfigError: If a required configuration section is missing or
-            fails validation.
+        ConfigError: If neither or both of *config_paths* and *config_dir*
+            are given, the environment is unknown, or a required
+            configuration section is missing or fails validation.
+        DeployCheckError: When a deploy check of level error fails in
+            production or staging.
         RuntimeError: If no ``app.discovery`` config is provided and no
             ``jobs`` are declared, or if discovery finds no ``Job`` classes.
 
@@ -915,10 +938,17 @@ def bootstrap_worker(
         )
         result.celery_app.start()
     """
-    ctx = ConfigContext.from_yaml(*config_paths, resolvers=with_default_resolvers(resolvers))
+    resolved_environment = resolve_environment(environment)
+    paths = select_config_paths(
+        config_paths, config_dir, resolved_environment, caller="bootstrap_worker"
+    )
+    ctx = load_application_config(
+        *paths, resolvers=with_default_resolvers(resolvers), environment=resolved_environment
+    )
     app_cfg = ctx.section_optional(ConfigKey.APP, _WorkerAppConfig) or _WorkerAppConfig()
     celery_cfg = ctx.section(ConfigKey.CELERY, CeleryConfig)
-    observability_runtime = _build_observability_runtime(ctx)
+    observability_runtime = _build_observability_runtime(ctx, resolved_environment)
+    enforce_deploy_checks(ctx, resolved_environment, skip=(REST_CHECKS,))
     async_runtime = _build_async_runtime(celery_cfg.runtime)
 
     resolved = _resolve_compilables_and_jobs(ctx, jobs, use_cases)
@@ -951,6 +981,7 @@ def bootstrap_worker(
         modules=runtime_modules,
         metrics=metrics,
         uow_factory=uow_factory,
+        environment=resolved_environment,
     )
     _reject_agent_markers(resolved.compilables, kernel)
     _reject_mcp_markers(resolved.compilables, kernel)

{loom_kernel-2.22.3 → loom_kernel-4.0.0}/src/loom/celery/config.py

@@ -37,12 +37,13 @@ from celery import Celery  # type: ignore[import-untyped]
 from kombu import Queue  # type: ignore[import-untyped]
 
 from loom.core.model import LoomFrozenStruct
+from loom.core.model.types import PositiveInt
 
 if TYPE_CHECKING:
     from loom.core.job.job import Job
 
 
-class CeleryRuntimeConfig(LoomFrozenStruct, frozen=True, kw_only=True):
+class CeleryRuntimeConfig(LoomFrozenStruct, frozen=True, kw_only=True, forbid_unknown_fields=True):
     """Async bridge settings for a Celery worker process.
 
     Attributes:
@@ -51,15 +52,16 @@ class CeleryRuntimeConfig(LoomFrozenStruct, frozen=True, kw_only=True):
         use_uvloop: When ``True`` and the backend is ``"asyncio"``, the worker
             uses uvloop on supported platforms.
         shutdown_timeout_ms: Maximum milliseconds to wait for in-flight async
-            work during worker shutdown.  ``None`` waits indefinitely.
+            work during worker shutdown, above zero.  ``None`` waits
+            indefinitely.
     """
 
     backend: Literal["asyncio", "trio"] = "asyncio"
     use_uvloop: bool = False
-    shutdown_timeout_ms: int | None = None
+    shutdown_timeout_ms: PositiveInt | None = None
 
 
-class CeleryConfig(LoomFrozenStruct, frozen=True, kw_only=True):
+class CeleryConfig(LoomFrozenStruct, frozen=True, kw_only=True, forbid_unknown_fields=True):
     """Broker and worker settings for the Celery application.
 
     Attributes:
@@ -109,7 +111,7 @@ class CeleryConfig(LoomFrozenStruct, frozen=True, kw_only=True):
     runtime: CeleryRuntimeConfig = msgspec.field(default_factory=CeleryRuntimeConfig)
 
 
-class JobConfig(LoomFrozenStruct, frozen=True, kw_only=True):
+class JobConfig(LoomFrozenStruct, frozen=True, kw_only=True, forbid_unknown_fields=True):
     """Per-job routing and execution overrides applied at bootstrap.
 
     Fields set to ``None`` leave the corresponding ClassVar on the

{loom_kernel-2.22.3 → loom_kernel-4.0.0}/src/loom/cli/app.py

@@ -4,7 +4,9 @@ from __future__ import annotations
 
 import typer
 
+from loom.cli.check import check
 from loom.cli.schema import schema_app
 
-app = typer.Typer(no_args_is_help=True, help="Operate the database side of a loom application.")
+app = typer.Typer(no_args_is_help=True, help="Operate a loom application.")
 app.add_typer(schema_app, name="schema")
+app.command("check")(check)

loom_kernel-4.0.0/src/loom/cli/check.py

@@ -0,0 +1,105 @@
+"""``loom check --deploy``: run the deploy checks without starting the application.
+
+Meant for CI: it loads the configuration the application would load, runs
+every deploy check whatever the environment, prints each finding with its id
+and hint, and exits ``1`` when an error remains. loom's checks read keys as
+written and resolve no placeholder; the configuration loads with loom's
+default resolvers, so a ``${secrets:...}`` value no check reads is left alone.
+
+The command cannot tell which kind of process a configuration is for: a REST
+application may declare ``celery`` for its job service and a worker may share
+``app.rest``. ``--skip loom.rest`` (repeatable, any id or area) leaves out
+what the process does not run, as the worker and the runners do at startup.
+
+``app.code_path`` (``src`` by default, relative to the first file) joins the
+import path as ``create_app`` adds it, so the modules of ``checks.modules``
+import here as they do at startup.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from loom.core.checks import DeployReport, run_deploy_checks
+from loom.core.config import ConfigContext, with_default_resolvers
+from loom.core.config.errors import ConfigError
+from loom.core.config.overrides import load_application_config
+from loom.core.environment import Environment, resolve_environment, select_config_paths
+from loom.core.locator import DEFAULT_CODE_PATH, add_code_path
+
+
+def check(
+    config: Annotated[
+        list[Path],
+        typer.Argument(help="A config directory (base.yaml plus overlays) or YAML files."),
+    ],
+    deploy: Annotated[bool, typer.Option("--deploy", help="Run the deploy checks.")] = False,
+    env: Annotated[
+        str | None,
+        typer.Option("--env", help="Environment picking the overlay; defaults to LOOM_ENV."),
+    ] = None,
+    skip: Annotated[
+        list[str] | None,
+        typer.Option("--skip", help="A check id or area to leave out, e.g. loom.rest; repeatable."),
+    ] = None,
+) -> None:
+    """Run the deploy checks against the configuration, for CI."""
+    if not deploy:
+        typer.echo("only deploy checks exist: run 'loom check --deploy <config>'.", err=True)
+        raise typer.Exit(2)
+    _load_check_packages()
+    try:
+        environment = resolve_environment(env)
+        paths = _config_paths(config, environment)
+        context = load_application_config(
+            *paths, resolvers=with_default_resolvers(()), environment=environment
+        )
+        _add_code_path(context, Path(paths[0]).resolve().parent)
+        report = run_deploy_checks(context, skip=tuple(skip or ()))
+    except ConfigError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    _print(report, environment, tuple(skip or ()))
+    if report.errors:
+        raise typer.Exit(1)
+
+
+def _load_check_packages() -> None:
+    """Import the packages registering loom's checks; the REST ones need the rest extra."""
+    importlib.import_module("loom.core.logger")
+    if importlib.util.find_spec("fastapi") is not None:
+        importlib.import_module("loom.rest")
+
+
+def _add_code_path(context: ConfigContext, config_dir: Path) -> None:
+    raw = context.raw("app.code_path", DEFAULT_CODE_PATH)
+    if not isinstance(raw, str) or "${" in raw:
+        raise ConfigError(
+            "app.code_path must be a literal path for loom check: a placeholder or a "
+            "non-string value cannot name the directory its check modules import from"
+        )
+    add_code_path(raw, config_dir)
+
+
+def _config_paths(config: list[Path], environment: Environment) -> tuple[str, ...]:
+    directory = config[0] if len(config) == 1 and config[0].is_dir() else None
+    if directory is None and any(path.is_dir() for path in config):
+        raise ConfigError("pass one config directory or YAML files, not both")
+    files = () if directory is not None else tuple(str(path) for path in config)
+    return select_config_paths(files, directory, environment, caller="loom check")
+
+
+def _print(report: DeployReport, environment: Environment, skipped: tuple[str, ...]) -> None:
+    typer.echo(f"environment: {environment}")
+    if skipped:
+        typer.echo(f"skipped: {', '.join(skipped)}")
+    if report.silenced:
+        typer.echo(f"silenced: {', '.join(report.silenced)}")
+    for result in report.results:
+        typer.echo(f"{result.level.upper()} {result.describe()}")
+    typer.echo(f"{len(report.errors)} error(s), {len(report.warnings)} warning(s)")

{loom_kernel-2.22.3 → loom_kernel-4.0.0}/src/loom/core/bootstrap/bootstrap.py

@@ -33,6 +33,7 @@ from loom.core.engine.compilable import Compilable
 from loom.core.engine.compiler import UseCaseCompiler
 from loom.core.engine.executor import RuntimeExecutor
 from loom.core.engine.metrics import MetricsAdapter
+from loom.core.environment import Environment, resolve_environment
 from loom.core.logger import LoggerPort, get_logger
 from loom.core.use_case.factory import UseCaseFactory
 
@@ -77,6 +78,7 @@ def bootstrap_app(
     modules: Sequence[Callable[[LoomContainer], None]] = (),
     logger: LoggerPort | None = None,
     metrics: MetricsAdapter | None = None,
+    environment: Environment | str | None = None,
 ) -> BootstrapResult:
     """Run the deterministic Loom bootstrap pipeline.
 
@@ -97,6 +99,11 @@ def bootstrap_app(
             Executed in declaration order before compilation.
         logger: Optional logger.  Falls back to the framework default.
         metrics: Optional metrics adapter passed to the compiler.
+        environment: Environment of the application, resolved like
+            :func:`~loom.core.environment.resolve_environment` (``LOOM_ENV``,
+            else production) when ``None``. Registered at ``APPLICATION``
+            scope with the configuration, before the modules run, so a
+            module's service can resolve it.
 
     Returns:
         :class:`BootstrapResult` with container, compiler, and factory.
@@ -117,12 +124,14 @@ def bootstrap_app(
         app = create_fastapi_app(result, RouteSources(python=[OrderRestInterface]))
     """
     _logger = logger or get_logger("loom.bootstrap")
+    resolved_environment = resolve_environment(environment)
 
     try:
         # Step 1 — Container + config binding
         _logger.info("[BOOT] Initialising DI container")
         container = LoomContainer()
         container.register(type(config), lambda: config, scope=Scope.APPLICATION)
+        container.register(Environment, lambda: resolved_environment, scope=Scope.APPLICATION)
 
         # Step 2 — User module bindings
         for module in modules: