juniper-service-core 0.1.0__tar.gz

juniper_service_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Overtoad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

juniper_service_core-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: juniper-service-core
+Version: 0.1.0
+Summary: Shared service-tier scaffolding (FastAPI app factory, settings base, generic routes) for Juniper ML model services
+Author: Paul Calnon
+License: MIT
+Project-URL: Homepage, https://github.com/pcalnon/juniper-ml
+Project-URL: Repository, https://github.com/pcalnon/juniper-ml
+Project-URL: Issues, https://github.com/pcalnon/juniper-ml/issues
+Keywords: juniper,service,fastapi,scaffolding,middleware
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: juniper-model-core>=0.1.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Requires-Dist: httpx>=0.27; extra == "test"
+Dynamic: license-file
+
+# juniper-service-core
+
+**Project**: Juniper — Cascade Correlation Neural Network Research Platform
+**Application**: juniper-service-core (subdirectory of juniper-ml)
+**Author**: Paul Calnon
+**License**: MIT License
+**Version**: 0.1.0
+
+Shared **service-tier scaffolding** for Juniper ML model services: a model-agnostic
+FastAPI application factory, a `pydantic-settings` base, and a generic
+liveness/readiness health router. This is WS-2 of the model/middleware refactor
+(`notes/JUNIPER_MODEL_MIDDLEWARE_REFACTOR_DESIGN_AND_PLAN_2026-05-31.md` in the
+juniper-ml repo).
+
+The `-core` suffix marks it as genuinely shared: it carries **no** model,
+classification, or training logic — those stay in the owning service (e.g.
+`juniper-cascor`) and are passed in.
+
+## Install
+
+```bash
+pip install juniper-service-core
+```
+
+## What's in this scaffold
+
+| Surface | Module | Purpose |
+|---------|--------|---------|
+| `create_app(...)` | `juniper_service_core.app` | FastAPI app factory: mounts the health router, then any service-supplied routers. Model-agnostic. |
+| `SettingsBase` | `juniper_service_core.settings` | `pydantic-settings` base with generic fields (`service_name`, `host`, `port`, `log_level`). Subclasses set their own `env_prefix`. |
+| `health_router()` | `juniper_service_core.health` | Generic `APIRouter` exposing `GET /v1/health` (liveness) and `GET /v1/health/ready` (readiness). |
+
+### Dependency-free top-level import
+
+`import juniper_service_core` pulls **no** third-party runtime dependency. Only
+`__version__` is exposed eagerly; `create_app` and `SettingsBase` are imported lazily
+on attribute access (PEP 562 `__getattr__`) from submodules that require `fastapi` /
+`pydantic-settings`. This lets the TestPyPI publish-verify run a clean `--no-deps`
+import check.
+
+## Usage
+
+```python
+from juniper_service_core import create_app, SettingsBase
+from pydantic_settings import SettingsConfigDict
+
+
+class MyServiceSettings(SettingsBase):
+    model_config = SettingsConfigDict(env_prefix="JUNIPER_MYSVC_")
+
+
+app = create_app(title="My Service", version="1.0.0", routers=[...])
+# GET /v1/health      -> {"status": "ok"}
+# GET /v1/health/ready -> {"status": "ready"}
+```
+
+## What's deferred
+
+This first PR is an additive package skeleton. The following are intentionally **not**
+in this scaffold and arrive in later WS-2 follow-ups:
+
+- Extraction of the **security / middleware / websocket / worker / generic-route**
+  helpers from `juniper-cascor`.
+- The `TrainingLifecycleBase` body, which depends on `juniper-model-core`
+  (this scaffold does not yet depend on `juniper-model-core`).
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest tests/ -v
+```

juniper_service_core-0.1.0/README.md

@@ -0,0 +1,72 @@
+# juniper-service-core
+
+**Project**: Juniper — Cascade Correlation Neural Network Research Platform
+**Application**: juniper-service-core (subdirectory of juniper-ml)
+**Author**: Paul Calnon
+**License**: MIT License
+**Version**: 0.1.0
+
+Shared **service-tier scaffolding** for Juniper ML model services: a model-agnostic
+FastAPI application factory, a `pydantic-settings` base, and a generic
+liveness/readiness health router. This is WS-2 of the model/middleware refactor
+(`notes/JUNIPER_MODEL_MIDDLEWARE_REFACTOR_DESIGN_AND_PLAN_2026-05-31.md` in the
+juniper-ml repo).
+
+The `-core` suffix marks it as genuinely shared: it carries **no** model,
+classification, or training logic — those stay in the owning service (e.g.
+`juniper-cascor`) and are passed in.
+
+## Install
+
+```bash
+pip install juniper-service-core
+```
+
+## What's in this scaffold
+
+| Surface | Module | Purpose |
+|---------|--------|---------|
+| `create_app(...)` | `juniper_service_core.app` | FastAPI app factory: mounts the health router, then any service-supplied routers. Model-agnostic. |
+| `SettingsBase` | `juniper_service_core.settings` | `pydantic-settings` base with generic fields (`service_name`, `host`, `port`, `log_level`). Subclasses set their own `env_prefix`. |
+| `health_router()` | `juniper_service_core.health` | Generic `APIRouter` exposing `GET /v1/health` (liveness) and `GET /v1/health/ready` (readiness). |
+
+### Dependency-free top-level import
+
+`import juniper_service_core` pulls **no** third-party runtime dependency. Only
+`__version__` is exposed eagerly; `create_app` and `SettingsBase` are imported lazily
+on attribute access (PEP 562 `__getattr__`) from submodules that require `fastapi` /
+`pydantic-settings`. This lets the TestPyPI publish-verify run a clean `--no-deps`
+import check.
+
+## Usage
+
+```python
+from juniper_service_core import create_app, SettingsBase
+from pydantic_settings import SettingsConfigDict
+
+
+class MyServiceSettings(SettingsBase):
+    model_config = SettingsConfigDict(env_prefix="JUNIPER_MYSVC_")
+
+
+app = create_app(title="My Service", version="1.0.0", routers=[...])
+# GET /v1/health      -> {"status": "ok"}
+# GET /v1/health/ready -> {"status": "ready"}
+```
+
+## What's deferred
+
+This first PR is an additive package skeleton. The following are intentionally **not**
+in this scaffold and arrive in later WS-2 follow-ups:
+
+- Extraction of the **security / middleware / websocket / worker / generic-route**
+  helpers from `juniper-cascor`.
+- The `TrainingLifecycleBase` body, which depends on `juniper-model-core`
+  (this scaffold does not yet depend on `juniper-model-core`).
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest tests/ -v
+```

juniper_service_core-0.1.0/juniper_service_core/__init__.py

@@ -0,0 +1,103 @@
+"""``juniper-service-core`` -- shared service-tier scaffolding for Juniper ML model services.
+
+A genuinely-shared abstraction (the ``-core`` suffix): the minimal, model-agnostic
+FastAPI plumbing every Juniper model service needs -- an app factory
+(:func:`create_app`), a pydantic-settings base (:class:`SettingsBase`), and a generic
+liveness/readiness health router. WS-2 of the model/middleware refactor
+(``notes/JUNIPER_MODEL_MIDDLEWARE_REFACTOR_DESIGN_AND_PLAN_2026-05-31.md`` in the
+juniper-ml repo).
+
+**Dependency-free top-level import.** Importing this top-level package pulls **no**
+third-party runtime dependency. Only :data:`__version__` is exposed eagerly; the rest
+of the public surface (``create_app``, ``SettingsBase``, the security helpers, the
+secrets helper, and the middleware classes) is imported lazily on attribute access
+(PEP 562 ``__getattr__``) from submodules that *do* require ``fastapi`` /
+``pydantic-settings`` / ``starlette``. This is what lets the TestPyPI publish-verify
+run a clean ``--no-deps`` ``import juniper_service_core`` check.
+
+cascor's generic service infra extracted so far (de-cascored): API-key auth + rate
+limiting (:mod:`~juniper_service_core.security`), Docker-secrets reading
+(:mod:`~juniper_service_core.secrets`), the security / body-limit middleware
+(:mod:`~juniper_service_core.middleware`), the subprocess service launcher
+(:mod:`~juniper_service_core.launcher`), and the **synchronous**
+``TrainingLifecycleBase`` body (:mod:`~juniper_service_core.lifecycle`, which drives a
+``juniper-model-core`` ``TrainableModel``). The websocket / worker / generic-route
+helpers -- and the threaded / worker-coordinated lifecycle bodies (OQ-11) -- remain
+deferred (later WS-2 follow-ups).
+"""
+
+from __future__ import annotations
+
+from juniper_service_core._version import __version__
+
+__all__ = [
+    "__version__",
+    "create_app",
+    "SettingsBase",
+    # Security (lazy, from .security)
+    "APIKeyAuth",
+    "RateLimiter",
+    "api_key_header",
+    "build_api_key_auth",
+    "build_rate_limiter",
+    # Secrets (lazy, from .secrets)
+    "get_secret",
+    # Middleware (lazy, from .middleware)
+    "SecurityHeadersMiddleware",
+    "RequestBodyLimitMiddleware",
+    "SecurityMiddleware",
+    # Launcher (lazy, from .launcher -- stdlib-only)
+    "ManagedService",
+    "start_service",
+    "wait_for_health",
+    # Lifecycle (lazy, from .lifecycle -- requires juniper-model-core)
+    "TrainingLifecycle",
+    "EventCollector",
+]
+
+# Maps each lazily-resolved public name to the submodule that defines it. Keeping
+# these imports out of module top level preserves the dependency-free
+# ``import juniper_service_core`` guarantee: ``fastapi`` / ``pydantic-settings`` /
+# ``starlette`` are only imported when one of these names is actually accessed.
+# (``.secrets`` is stdlib-only, but is routed here too for uniformity.)
+_LAZY_EXPORTS = {
+    "create_app": "juniper_service_core.app",
+    "SettingsBase": "juniper_service_core.settings",
+    "APIKeyAuth": "juniper_service_core.security",
+    "RateLimiter": "juniper_service_core.security",
+    "api_key_header": "juniper_service_core.security",
+    "build_api_key_auth": "juniper_service_core.security",
+    "build_rate_limiter": "juniper_service_core.security",
+    "get_secret": "juniper_service_core.secrets",
+    "SecurityHeadersMiddleware": "juniper_service_core.middleware",
+    "RequestBodyLimitMiddleware": "juniper_service_core.middleware",
+    "SecurityMiddleware": "juniper_service_core.middleware",
+    # .launcher is stdlib-only (asyncio / subprocess / urllib), but is routed
+    # through the lazy path too so the PEP 562 pattern stays uniform.
+    "ManagedService": "juniper_service_core.launcher",
+    "start_service": "juniper_service_core.launcher",
+    "wait_for_health": "juniper_service_core.launcher",
+    # .lifecycle requires juniper-model-core; kept lazy so the top-level import stays
+    # dependency-free and the --no-deps publish-verify still works.
+    "TrainingLifecycle": "juniper_service_core.lifecycle",
+    "EventCollector": "juniper_service_core.lifecycle",
+}
+
+
+def __getattr__(name: str):
+    """Lazily resolve the third-party-dependent public surface (PEP 562).
+
+    Keeping these imports out of module top level preserves the dependency-free
+    ``import juniper_service_core`` guarantee: ``fastapi`` / ``pydantic-settings`` /
+    ``starlette`` are only imported when one of the lazy exports is accessed.
+    """
+    module_name = _LAZY_EXPORTS.get(name)
+    if module_name is not None:
+        from importlib import import_module
+
+        return getattr(import_module(module_name), name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

juniper_service_core-0.1.0/juniper_service_core/_version.py

@@ -0,0 +1,5 @@
+"""Single source of truth for the ``juniper-service-core`` version string."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

juniper_service_core-0.1.0/juniper_service_core/app.py

@@ -0,0 +1,39 @@
+"""FastAPI application factory for Juniper model services.
+
+:func:`create_app` builds a model-agnostic FastAPI app, mounts the generic health
+router, then includes any service-supplied routers. It carries **no** model,
+classification, or training logic -- those live in the owning service and are passed in
+as ``routers``. This keeps the service-tier scaffolding reusable across every Juniper
+model service (WS-2).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from fastapi import APIRouter, FastAPI
+
+from juniper_service_core.health import health_router
+
+
+def create_app(
+    *,
+    title: str = "Juniper Service",
+    version: str = "0.1.0",
+    routers: Iterable[APIRouter] = (),
+) -> FastAPI:
+    """Create a FastAPI app with the generic health router plus any extra routers.
+
+    Args:
+        title: OpenAPI title for the app.
+        version: OpenAPI version string for the app.
+        routers: Additional service routers to mount after the health router.
+
+    Returns:
+        A configured :class:`~fastapi.FastAPI` instance. Model-agnostic by design.
+    """
+    app = FastAPI(title=title, version=version)
+    app.include_router(health_router())
+    for router in routers:
+        app.include_router(router)
+    return app

juniper_service_core-0.1.0/juniper_service_core/health.py

@@ -0,0 +1,41 @@
+"""Generic liveness/readiness health router shared by Juniper model services.
+
+Provides a minimal, model-agnostic ``/v1/health`` (liveness) and ``/v1/health/ready``
+(readiness) pair. Services that need richer dependency-probe readiness (the
+``ReadinessResponse`` contract) layer that on via ``juniper-observability``; this router
+is the baseline every service gets for free from the app factory.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+
+class HealthStatus(BaseModel):
+    """Response body for the generic health endpoints."""
+
+    status: str
+
+
+def health_router() -> APIRouter:
+    """Build the generic health :class:`~fastapi.APIRouter`.
+
+    Returns a router exposing:
+
+    * ``GET /v1/health`` -- liveness, returns ``{"status": "ok"}``.
+    * ``GET /v1/health/ready`` -- readiness, returns ``{"status": "ready"}``.
+    """
+    router = APIRouter(tags=["health"])
+
+    @router.get("/v1/health", response_model=HealthStatus)
+    async def health() -> HealthStatus:
+        """Liveness probe: the process is up and serving requests."""
+        return HealthStatus(status="ok")
+
+    @router.get("/v1/health/ready", response_model=HealthStatus)
+    async def health_ready() -> HealthStatus:
+        """Readiness probe: the service is ready to accept traffic."""
+        return HealthStatus(status="ready")
+
+    return router

juniper_service_core-0.1.0/juniper_service_core/launcher.py

@@ -0,0 +1,198 @@
+"""Generic subprocess launcher for companion services.
+
+Provides a small, model-agnostic mechanism for starting auxiliary services as
+managed subprocesses and waiting for them to report healthy over HTTP:
+
+* :class:`ManagedService` — a subprocess wrapper with lifecycle support
+  (``is_running`` / ``terminate``).
+* :func:`wait_for_health` — poll an HTTP health endpoint until it responds 200
+  or a timeout expires.
+* :func:`start_service` — ``Popen`` a service from a shell-command string and
+  wait for it to become healthy.
+
+Started services are tracked in a module-level registry and terminated on
+interpreter exit via an :mod:`atexit` hook.
+
+Primarily intended for non-containerized (local development) environments where
+Docker Compose is not managing service orchestration.  In Docker deployments,
+use ``depends_on`` with ``condition: service_healthy`` instead.
+"""
+
+import asyncio
+import atexit
+import logging
+import os
+import shlex
+import subprocess  # nosec B404 — subprocess is the core purpose of this module
+import urllib.request
+from pathlib import Path
+
+# Local timeout / interval defaults (seconds). Defined here (rather than imported
+# from a project-specific constants module) so this launcher carries no coupling to
+# any particular Juniper service.
+_HEALTH_CHECK_HTTP_TIMEOUT = 5.0
+_PROCESS_TERMINATION_TIMEOUT = 5.0
+_SERVICE_DEFAULT_TERMINATE_TIMEOUT = 10.0
+_SERVICE_HEALTH_POLL_INTERVAL = 0.5
+_SERVICE_HEALTH_POLL_TIMEOUT = 30.0
+_SERVICE_TERMINATION_TIMEOUT = 10.0
+
+logger = logging.getLogger("juniper_service_core.launcher")
+
+_active_services: list["ManagedService"] = []
+
+
+class ManagedService:
+    """A subprocess-managed companion service with lifecycle support."""
+
+    def __init__(
+        self,
+        name: str,
+        process: subprocess.Popen,
+        log_handle: object | None = None,
+    ):
+        self.name = name
+        self.process = process
+        self._log_handle = log_handle
+
+    def is_running(self) -> bool:
+        return self.process.poll() is None
+
+    def terminate(self, timeout: float = _SERVICE_DEFAULT_TERMINATE_TIMEOUT) -> None:
+        if not self.is_running():
+            logger.debug(f"{self.name} already stopped (rc={self.process.returncode})")
+            self._close_log()
+            return
+        logger.info(f"Terminating {self.name} (pid={self.process.pid})")
+        self.process.terminate()
+        try:
+            self.process.wait(timeout=timeout)
+            logger.info(f"{self.name} stopped gracefully")
+        except subprocess.TimeoutExpired:
+            logger.warning(f"{self.name} did not stop in {timeout}s, sending SIGKILL")
+            self.process.kill()
+            self.process.wait(timeout=_PROCESS_TERMINATION_TIMEOUT)
+            logger.info(f"{self.name} killed")
+        self._close_log()
+
+    def _close_log(self) -> None:
+        if self._log_handle is not None:
+            try:
+                self._log_handle.close()
+            except Exception:  # nosec B110 — cleanup must not propagate exceptions
+                pass
+            self._log_handle = None
+
+
+def _cleanup_at_exit() -> None:
+    """Terminate all managed services on interpreter exit."""
+    for svc in _active_services:
+        try:
+            svc.terminate(timeout=_SERVICE_TERMINATION_TIMEOUT)
+        except Exception:  # nosec B110 — cleanup must not propagate exceptions
+            pass
+
+
+atexit.register(_cleanup_at_exit)
+
+
+def _resolve_log_dir() -> Path:
+    """Resolve the canonical log directory for subprocess output."""
+    return Path(os.environ.get("JUNIPER_SERVICE_LOG_DIR") or (Path.cwd() / "logs"))
+
+
+async def wait_for_health(
+    url: str,
+    timeout: float = _SERVICE_HEALTH_POLL_TIMEOUT,
+    interval: float = _SERVICE_HEALTH_POLL_INTERVAL,
+) -> bool:
+    """Poll a health endpoint until it responds HTTP 200 or timeout expires."""
+    import time
+
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            req = urllib.request.Request(url, method="GET")
+            with urllib.request.urlopen(req, timeout=_HEALTH_CHECK_HTTP_TIMEOUT) as resp:  # nosec B310 — internal health check URL from configuration
+                if resp.status == 200:
+                    return True
+        except Exception:  # nosec B110 — health poll retries on any exception
+            pass
+        await asyncio.sleep(interval)
+    return False
+
+
+async def start_service(
+    name: str,
+    command: str,
+    health_url: str,
+    env_overrides: dict[str, str] | None = None,
+    health_timeout: float = _SERVICE_HEALTH_POLL_TIMEOUT,
+) -> ManagedService | None:
+    """Start a service as a subprocess and wait for it to become healthy.
+
+    Args:
+        name: Human-readable service name for logging.
+        command: Shell command string to start the service (parsed with shlex).
+        health_url: URL to poll for health status (expects HTTP 200).
+        env_overrides: Additional environment variables for the subprocess.
+        health_timeout: Seconds to wait for the health check to pass.
+
+    Returns:
+        ManagedService instance if started successfully, None otherwise.
+    """
+    cmd_parts = shlex.split(command)
+    logger.info(f"Starting {name}: {command}")
+
+    env = os.environ.copy()
+    if env_overrides:
+        env.update(env_overrides)
+
+    # Redirect subprocess output to a log file for diagnostics
+    log_dir = _resolve_log_dir()
+    log_dir.mkdir(parents=True, exist_ok=True)
+    safe_name = name.lower().replace(" ", "_").replace("-", "_")
+    log_file = log_dir / f"subprocess_{safe_name}.log"
+
+    log_handle = None
+    stdout_target = subprocess.DEVNULL
+    stderr_target = subprocess.DEVNULL
+    try:
+        log_handle = open(log_file, "a", encoding="utf-8")
+        stdout_target = log_handle
+        stderr_target = subprocess.STDOUT
+        logger.info(f"{name} output -> {log_file}")
+    except OSError:
+        logger.warning(f"Could not open log file {log_file}, using /dev/null")
+
+    try:
+        process = subprocess.Popen(  # nosec B603 — command is from settings, not user input
+            cmd_parts,
+            env=env,
+            stdout=stdout_target,
+            stderr=stderr_target,
+            start_new_session=True,
+        )
+    except Exception:
+        logger.exception(f"Failed to start {name}")
+        if log_handle:
+            log_handle.close()
+        return None
+
+    service = ManagedService(name, process, log_handle)
+    _active_services.append(service)
+
+    logger.info(f"Waiting for {name} health at {health_url} (timeout={health_timeout}s)")
+    healthy = await wait_for_health(health_url, timeout=health_timeout)
+
+    if not healthy:
+        if service.is_running():
+            logger.error(f"{name} started but health check failed after {health_timeout}s")
+        else:
+            logger.error(f"{name} exited prematurely (rc={process.returncode})")
+        service.terminate()
+        _active_services.remove(service)
+        return None
+
+    logger.info(f"{name} is healthy (pid={process.pid})")
+    return service

juniper_service_core-0.1.0/juniper_service_core/lifecycle.py

@@ -0,0 +1,80 @@
+"""Generic training-lifecycle bodies (WS-2).
+
+Concrete :class:`juniper_model_core.lifecycle.TrainingLifecycleBase` implementations that
+drive a model-core :class:`~juniper_model_core.interfaces.TrainableModel` through training
+and forward the model's :class:`~juniper_model_core.events.TrainingEvent`s to the injected
+sink. This is the **synchronous foundation**; the threaded / finite-state-machine /
+dataset-hot-swap / worker-coordinated bodies -- and the worker-parallelism question
+(OQ-11) -- are deferred follow-ups (model-core ``lifecycle.py`` decision D8).
+
+Importing this module requires ``juniper-model-core`` (the model contract); it is therefore
+NOT imported at the top level of :mod:`juniper_service_core` (it is exposed lazily) so the
+dependency-free top-level import is preserved.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import replace
+from typing import TYPE_CHECKING, Any
+
+from juniper_model_core.lifecycle import TrainingLifecycleBase
+
+if TYPE_CHECKING:
+    import numpy as np
+    from juniper_model_core.events import TrainingEvent
+    from juniper_model_core.interfaces import TrainableModel, TrainResult
+
+__all__ = ["TrainingLifecycle", "EventCollector"]
+
+
+class EventCollector:
+    """A simple, ordered event sink -- for tests, inspection, and replay.
+
+    Use it as the ``on_event`` sink of a lifecycle; it records every emitted event in order.
+    """
+
+    def __init__(self) -> None:
+        self.events: list[TrainingEvent] = []
+
+    def __call__(self, event: TrainingEvent) -> None:
+        self.events.append(event)
+
+    @property
+    def types(self) -> list[str]:
+        """The event ``type`` strings, in emission order."""
+        return [event.type for event in self.events]
+
+
+class TrainingLifecycle(TrainingLifecycleBase):
+    """Synchronous lifecycle: drives ``model.fit`` to completion on the calling thread.
+
+    :meth:`run` wires the model's ``on_event`` to this lifecycle's :meth:`emit`, so the
+    model's progress events flow to the injected sink. The lifecycle owns **run-level
+    ordering**: it stamps a monotonic ``seq`` on each event as it passes through, so the
+    sink sees a legally-ordered stream regardless of what ``seq`` the model emits.
+
+    Growth (``unit_added``) for a :class:`~juniper_model_core.interfaces.GrowableModel`
+    happens *inside* its ``fit`` (the model-core contract), so this single synchronous body
+    drives both fixed-topology and growable models. The threaded / FSM / dataset-hot-swap /
+    worker-coordinated bodies are deferred (D8; worker parallelism is OQ-11).
+    """
+
+    def __init__(self, model: TrainableModel, on_event: Callable[[TrainingEvent], None] | None = None) -> None:
+        super().__init__(model, on_event)
+        self._seq = 0
+
+    def emit(self, event: TrainingEvent) -> None:
+        """Forward ``event`` to the sink with a monotonic, run-scoped ``seq`` stamped."""
+        super().emit(replace(event, seq=self._seq))
+        self._seq += 1
+
+    def run(self, X: np.ndarray, y: np.ndarray, **kw: Any) -> TrainResult:
+        """Drive the model's full ``fit`` synchronously, routing its events through the
+        lifecycle.
+
+        ``**kw`` (e.g. ``X_val`` / ``y_val``, or sequence auxiliaries like ``dt``) is
+        forwarded to ``fit``. Do **not** pass ``on_event`` -- the lifecycle owns the sink.
+        """
+        self._seq = 0
+        return self.model.fit(X, y, on_event=self.emit, **kw)