plba

src/app_runtime/contracts/__init__.py

@@ -0,0 +1 @@
+__all__: list[str] = []

src/app_runtime/contracts/application.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from app_runtime.core.registration import ModuleRegistry
+
+
+class ApplicationModule(ABC):
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Module name used for runtime status and diagnostics."""
+
+    @abstractmethod
+    def register(self, registry: ModuleRegistry) -> None:
+        """Register workers, queues, handlers, services, and health contributors."""

src/app_runtime/contracts/config.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class ConfigProvider(ABC):
+    @abstractmethod
+    def load(self) -> dict[str, Any]:
+        """Return a config fragment."""

src/app_runtime/contracts/health.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from app_runtime.contracts.worker import WorkerHealth
+
+
+class HealthContributor(ABC):
+    @abstractmethod
+    def health(self) -> WorkerHealth:
+        """Return contributor health state."""

src/app_runtime/contracts/queue.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from app_runtime.contracts.tasks import Task
+
+
+class TaskQueue(ABC):
+    @abstractmethod
+    def publish(self, task: Task) -> None:
+        """Push a task into the queue."""
+
+    @abstractmethod
+    def consume(self, timeout: float = 0.1) -> Task | None:
+        """Return the next available task or None."""
+
+    @abstractmethod
+    def ack(self, task: Task) -> None:
+        """Confirm successful task processing."""
+
+    @abstractmethod
+    def nack(self, task: Task, retry_delay: float | None = None) -> None:
+        """Signal failed task processing."""
+
+    @abstractmethod
+    def stats(self) -> dict[str, Any]:
+        """Return transport-level queue statistics."""

src/app_runtime/contracts/tasks.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class Task:
+    name: str
+    payload: dict[str, Any]
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class TaskHandler(ABC):
+    @abstractmethod
+    def handle(self, task: Task) -> None:
+        """Execute domain logic for a task."""

src/app_runtime/contracts/trace.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Protocol
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+@dataclass(slots=True)
+class TraceContext:
+    trace_id: str
+    span_id: str
+    parent_span_id: str | None = None
+    attributes: dict[str, Any] | None = None
+
+
+class TraceContextFactory(ABC):
+    @abstractmethod
+    def new_root(self, operation: str) -> TraceContext:
+        """Create a new root trace context."""
+
+    @abstractmethod
+    def child_of(self, parent: TraceContext, operation: str) -> TraceContext:
+        """Create a child trace context."""
+
+
+@dataclass(frozen=True)
+class TraceContextRecord:
+    trace_id: str
+    alias: str
+    parent_id: str | None = None
+    type: str | None = None
+    event_time: datetime = field(default_factory=utc_now)
+    attrs: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class TraceLogMessage:
+    trace_id: str
+    step: str
+    status: str
+    message: str
+    level: str
+    event_time: datetime = field(default_factory=utc_now)
+    attrs: dict[str, Any] = field(default_factory=dict)
+
+
+class TraceTransport(Protocol):
+    def write_context(self, record: TraceContextRecord) -> None:
+        """Persist trace context record."""
+
+    def write_message(self, record: TraceLogMessage) -> None:
+        """Persist trace log message."""

src/app_runtime/contracts/worker.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+
+HealthState = Literal["ok", "degraded", "unhealthy"]
+WorkerState = Literal["starting", "idle", "busy", "stopping", "stopped"]
+
+
+@dataclass(slots=True)
+class WorkerHealth:
+    name: str
+    status: HealthState
+    critical: bool
+    detail: str | None = None
+    meta: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class WorkerStatus:
+    name: str
+    state: WorkerState
+    in_flight: int = 0
+    detail: str | None = None
+    meta: dict[str, Any] = field(default_factory=dict)
+
+
+class Worker(ABC):
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Stable worker name for diagnostics."""
+
+    @property
+    @abstractmethod
+    def critical(self) -> bool:
+        """Whether this worker is required for healthy app operation."""
+
+    @abstractmethod
+    def start(self) -> None:
+        """Start worker execution."""
+
+    @abstractmethod
+    def stop(self, force: bool = False) -> None:
+        """Request graceful or immediate stop."""
+
+    @abstractmethod
+    def health(self) -> WorkerHealth:
+        """Return current health state."""
+
+    @abstractmethod
+    def status(self) -> WorkerStatus:
+        """Return current runtime status."""