engineering-platform 2.2.0__py3-none-any.whl

engineering_platform/component_logging.py

@@ -0,0 +1,420 @@
+"""Redacted component logging with CENTRAL as the only persistent authority."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from datetime import datetime, timezone
+import json
+import logging
+import os
+from pathlib import Path
+import signal
+import sqlite3
+import sys
+from collections.abc import Iterable, Iterator, Mapping
+
+from .agent_state import redact_diagnostic
+from .storage import EngineeringStorageError, open_storage
+from .providers import GitProvider
+from .platform_components import PLATFORM_COMPONENT_IDS
+
+LOG_LEVEL_ENVIRONMENT = "ENGINEERING_PLATFORM_LOG_LEVEL"
+SERVER_DATA_ROOT_ENVIRONMENT = "EP_SERVER_DATA_ROOT"
+DEFAULT_LOG_LEVEL = "INFO"
+COMPONENT_LOG_PAGE_SIZE = 50
+MAX_COMPONENT_LOG_PAGE_SIZE = 200
+PLATFORM_LOG_COMPONENTS = PLATFORM_COMPONENT_IDS
+VALID_LEVELS = frozenset({"DEBUG", "INFO", "WARNING", "ERROR"})
+LOG_LEVELS_AT_OR_ABOVE = {
+    "INFO": ("INFO", "WARNING", "ERROR"),
+    "WARNING": ("WARNING", "ERROR"),
+    "ERROR": ("ERROR",),
+}
+LIFECYCLE_CONTEXT_KEYS = frozenset(
+    {
+        "application_version",
+        "git_commit",
+        "launchd_label",
+        "launch_agent_path",
+        "target_component",
+        "shutdown_signal",
+        "configuration_scope",
+        "configuration_key",
+        "previous_value",
+        "new_value",
+        "provider",
+        "provider_action",
+        "provider_action_source",
+        "audit_outcome",
+    }
+)
+
+
+def configured_level(value: str | None = None) -> int:
+    """Resolve the supported local logging level without silently accepting typos."""
+    name = (value or os.environ.get(LOG_LEVEL_ENVIRONMENT, DEFAULT_LOG_LEVEL)).upper()
+    return getattr(logging, name if name in VALID_LEVELS else DEFAULT_LOG_LEVEL)
+
+
+class RedactingJsonFormatter(logging.Formatter):
+    """Persist only bounded, redacted structured component events."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, object] = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "level": record.levelname,
+            "component": redact_diagnostic(str(getattr(record, "component", record.name)), limit=80),
+            "run_id": redact_diagnostic(str(getattr(record, "run_id", "")), limit=80) or None,
+            "event": redact_diagnostic(record.getMessage(), limit=500),
+        }
+        diagnostic = getattr(record, "diagnostic", None)
+        if diagnostic is not None:
+            payload["diagnostic"] = redact_diagnostic(str(diagnostic), limit=500)
+        context = getattr(record, "context", {})
+        if isinstance(context, Mapping):
+            for key in sorted(LIFECYCLE_CONTEXT_KEYS):
+                if (value := context.get(key)) is not None:
+                    payload[key] = redact_diagnostic(str(value), limit=500)
+        return json.dumps(payload, separators=(",", ":"), sort_keys=True)
+
+
+class SQLiteLogHandler(logging.Handler):
+    """Persist component events only in the canonical CENTRAL store."""
+
+    def __init__(self, root: Path, component: str, *, central_database: Path | None = None) -> None:
+        super().__init__()
+        self.root = root.resolve()
+        self.component = component
+        self.central_database = central_database.resolve() if central_database is not None else None
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            if self.central_database is None:
+                raise EngineeringStorageError("CENTRAL component log authority is unavailable")
+            payload = self.format(record)
+            parsed = json.loads(payload)
+            created_at = parsed.get("timestamp")
+            connection = sqlite3.connect(self.central_database, isolation_level=None)
+            try:
+                connection.execute(
+                    "INSERT INTO engineering_component_logs(component,payload,created_at) VALUES(?,?,?)",
+                    (self.component, payload, created_at),
+                )
+            finally:
+                connection.close()
+        except (EngineeringStorageError, OSError, sqlite3.DatabaseError, TypeError, ValueError):
+            # Falling back into an arbitrary checkout would silently create a
+            # second supported component-log authority.  Keep the diagnostic
+            # observable but non-persistent when CENTRAL is unavailable.
+            try:
+                sys.stderr.write("engineering-platform: CENTRAL component log unavailable\n")
+            except OSError:
+                pass
+
+    def close(self) -> None:
+        super().close()
+
+
+def component_logger(
+    root: Path, component: str, *, level: str | None = None,
+    central_database: Path | None = None,
+) -> logging.Logger:
+    """Return the canonical CENTRAL logger for supported Platform components.
+
+    Installed runtime writers do not select a repository-local sink: the
+    Server publishes its data root and the component identity resolves through
+    the shared Platform Component model.  Missing CENTRAL binding is a
+    bounded diagnostic, never a local persistent fallback.
+    """
+    if component not in PLATFORM_COMPONENT_IDS:
+        # The database table has no foreign key to the component model.  The
+        # writer is therefore the authority boundary: accepting an arbitrary
+        # string here would let a retired alias become a new operational log
+        # identity simply by supplying a CENTRAL path.
+        raise ValueError("Unsupported Platform component.")
+    if central_database is None:
+        configured_root = os.environ.get(SERVER_DATA_ROOT_ENVIRONMENT)
+        if configured_root:
+            candidate = Path(configured_root).resolve() / "engineering.db"
+            if candidate.is_file():
+                central_database = candidate
+    logger = logging.getLogger(f"engineering_platform.{component}")
+    logger.setLevel(configured_level(level))
+    logger.propagate = False
+    for handler in tuple(logger.handlers):
+        if (
+            isinstance(handler, SQLiteLogHandler)
+            and handler.root == root.resolve()
+            and handler.central_database == (central_database.resolve() if central_database is not None else None)
+            and handler.component == component
+        ):
+            handler.setLevel(logger.level)
+            return logger
+        logger.removeHandler(handler)
+        handler.close()
+    handler = SQLiteLogHandler(root, component, central_database=central_database)
+    handler.setLevel(logger.level)
+    handler.setFormatter(RedactingJsonFormatter())
+    logger.addHandler(handler)
+    return logger
+
+
+def component_log(root: Path, component: str, *, limit: int = 100) -> bytes:
+    """Read component logs from CENTRAL, never from a repository-local fallback."""
+    if component not in PLATFORM_COMPONENT_IDS:
+        return b""
+    try:
+        connection = open_storage(root)
+        try:
+            rows = connection.execute(
+                "SELECT payload FROM engineering_component_logs WHERE component=? ORDER BY id DESC LIMIT ?",
+                (component, limit),
+            ).fetchall()
+        finally:
+            connection.close()
+        lines = [str(row[0]) for row in reversed(rows)]
+        return ("\n".join(lines) or "Nog geen applicatielog beschikbaar.").encode()
+    except (EngineeringStorageError, OSError, sqlite3.DatabaseError):
+        return b"CENTRAL componentlog is tijdelijk niet beschikbaar."
+
+
+def component_log_page(
+    root: Path,
+    component: str,
+    *,
+    page: int = 1,
+    page_size: int = COMPONENT_LOG_PAGE_SIZE,
+    start_at: str | None = None,
+    end_at: str | None = None,
+    inclusive_end: bool = False,
+    search: str = "",
+    level: str = "",
+    events: Iterable[str] = (),
+    sort_key: str = "timestamp",
+    direction: str = "desc",
+) -> dict[str, object]:
+    """Return one bounded, filtered page from canonical component-log storage.
+
+    Filtering happens before pagination so a historical date, event or text
+    search never disappears merely because newer rows filled an arbitrary
+    client-side sample.
+    """
+    if component not in PLATFORM_COMPONENT_IDS:
+        raise ValueError("Onbekende componentlog.")
+    if not isinstance(page, int) or page < 1:
+        raise ValueError("Ongeldige logpagina.")
+    if not isinstance(page_size, int) or not 1 <= page_size <= MAX_COMPONENT_LOG_PAGE_SIZE:
+        raise ValueError("Ongeldige logpaginagrootte.")
+    normalized_level = level.upper().strip()
+    if normalized_level and normalized_level not in VALID_LEVELS:
+        raise ValueError("Ongeldig logniveau.")
+    normalized_search = str(search).strip()
+    if len(normalized_search) > 160:
+        raise ValueError("Zoekterm voor logs is te lang.")
+    normalized_events = tuple(
+        sorted({str(event).strip() for event in events if str(event).strip()})
+    )
+    if len(normalized_events) > 50 or any(len(event) > 160 for event in normalized_events):
+        raise ValueError("Ongeldige gebeurtenisfilter.")
+    sort_columns = {
+        "line": "id",
+        "timestamp": "created_at",
+        "level": "json_extract(payload, '$.level')",
+        "event": "json_extract(payload, '$.event')",
+        "runId": "COALESCE(json_extract(payload, '$.run_id'), '')",
+        "details": "COALESCE(json_extract(payload, '$.diagnostic'), '')",
+    }
+    if sort_key not in sort_columns or direction not in {"asc", "desc"}:
+        raise ValueError("Ongeldige logsorteervolgorde.")
+
+    clauses = ["component=?"]
+    parameters: list[object] = [component]
+    if start_at:
+        clauses.append("created_at >= ?")
+        parameters.append(start_at)
+    if end_at:
+        clauses.append("created_at <= ?" if inclusive_end else "created_at < ?")
+        parameters.append(end_at)
+    if normalized_search:
+        escaped = normalized_search.lower().replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+        clauses.append("LOWER(payload) LIKE ? ESCAPE '\\'")
+        parameters.append(f"%{escaped}%")
+    # The dashboard's level picker is a minimum-severity filter. DEBUG is
+    # deliberately unbounded so it includes every retained record, including
+    # a future or legacy level the dashboard does not yet classify.
+    if normalized_level in LOG_LEVELS_AT_OR_ABOVE:
+        levels = LOG_LEVELS_AT_OR_ABOVE[normalized_level]
+        clauses.append("json_extract(payload, '$.level') IN (" + ",".join("?" for _ in levels) + ")")
+        parameters.extend(levels)
+    event_option_clauses = list(clauses)
+    event_option_parameters = list(parameters)
+    if normalized_events:
+        clauses.append("json_extract(payload, '$.event') IN (" + ",".join("?" for _ in normalized_events) + ")")
+        parameters.extend(normalized_events)
+    where = " WHERE " + " AND ".join(clauses)
+
+    try:
+        connection = open_storage(root)
+    except (EngineeringStorageError, OSError, sqlite3.DatabaseError):
+        # Schema activation is deliberately deferred during a managed run.
+        # The dashboard remains a read-only consumer, so it must retain its
+        # bounded response contract rather than terminate the HTTP handler.
+        return {
+            "entries": [],
+            "page": page,
+            "page_size": page_size,
+            "total": 0,
+            "events": [],
+        }
+    try:
+        total = int(connection.execute(
+            "SELECT COUNT(*) FROM engineering_component_logs" + where,
+            parameters,
+        ).fetchone()[0])
+        rows = connection.execute(
+            "SELECT id,payload FROM engineering_component_logs" + where
+            + f" ORDER BY {sort_columns[sort_key]} {direction.upper()}, id {direction.upper()} LIMIT ? OFFSET ?",
+            [*parameters, page_size, (page - 1) * page_size],
+        ).fetchall()
+        event_rows = connection.execute(
+            "SELECT DISTINCT json_extract(payload, '$.event') FROM engineering_component_logs WHERE "
+            + " AND ".join(event_option_clauses)
+            + " AND json_extract(payload, '$.event') IS NOT NULL ORDER BY 1 LIMIT 500",
+            event_option_parameters,
+        ).fetchall()
+        records: list[dict[str, object]] = []
+        for row_id, raw in rows:
+            try:
+                record = json.loads(str(raw))
+            except (TypeError, json.JSONDecodeError):
+                continue
+            if isinstance(record, dict):
+                record["line"] = int(row_id)
+                records.append(record)
+        return {
+            "entries": records,
+            "page": page,
+            "page_size": page_size,
+            "total": total,
+            "events": [str(row[0]) for row in event_rows if row[0]],
+        }
+    finally:
+        connection.close()
+
+
+def component_log_version(root: Path, component: str) -> str:
+    """Return a lightweight CENTRAL SQLite revision."""
+    if component not in PLATFORM_COMPONENT_IDS:
+        return "missing"
+    try:
+        connection = open_storage(root)
+        try:
+            count, newest = connection.execute(
+                "SELECT COUNT(*), COALESCE(MAX(id), 0) FROM engineering_component_logs WHERE component=?",
+                (component,),
+            ).fetchone()
+        finally:
+            connection.close()
+        return f"sqlite:{count}:{newest}"
+    except (EngineeringStorageError, OSError, sqlite3.DatabaseError):
+        return "central-unavailable"
+
+
+def clear_component_log(root: Path, component: str) -> None:
+    """Clear one CENTRAL component log without creating local log state."""
+    if component not in PLATFORM_COMPONENT_IDS:
+        raise ValueError("Onbekende componentlog.")
+    try:
+        connection = open_storage(root)
+        try:
+            connection.execute("DELETE FROM engineering_component_logs WHERE component=?", (component,))
+        finally:
+            connection.close()
+        return
+    except (EngineeringStorageError, OSError, sqlite3.DatabaseError) as error:
+        raise OSError("CENTRAL componentlog kon niet worden gewist.") from error
+
+
+def prune_component_logs(root: Path, retention_days: int) -> None:
+    """Remove only expired, local component-log rows for an approved retention period."""
+    if retention_days not in {30, 60, 90, 120, 180, 360}:
+        raise ValueError("Ongeldige logbewaartermijn.")
+    cutoff = datetime.now(timezone.utc).timestamp() - retention_days * 86_400
+    cutoff_iso = datetime.fromtimestamp(cutoff, timezone.utc).isoformat()
+    connection = open_storage(root)
+    try:
+        connection.execute(
+            "DELETE FROM engineering_component_logs WHERE created_at < ?", (cutoff_iso,)
+        )
+    finally:
+        connection.close()
+
+
+def log_event(
+    logger: logging.Logger,
+    level: int,
+    event: str,
+    *,
+    run_id: str | None = None,
+    diagnostic: str | None = None,
+    context: Mapping[str, object] | None = None,
+) -> None:
+    """Write one redacted, structured event without exposing arbitrary extras."""
+    logger.log(
+        level,
+        redact_diagnostic(event, limit=500),
+        extra={
+            "component": logger.name.rsplit(".", 1)[-1],
+            "run_id": run_id or "",
+            "diagnostic": diagnostic,
+            "context": dict(context or {}),
+        },
+    )
+
+
+def component_lifecycle_context(
+    root: Path,
+    *,
+    version: str,
+    launchd_label: str,
+    launch_agent_path: Path,
+) -> dict[str, str]:
+    """Return bounded, non-secret identity data for a component lifecycle event."""
+    try:
+        result = GitProvider().execute(root.resolve(), "git", "rev-parse", "--short=12", "HEAD")
+        commit = result.stdout.strip() if result.returncode == 0 else "onbekend"
+    except OSError:
+        commit = "onbekend"
+    return {
+        "application_version": version,
+        "git_commit": commit or "onbekend",
+        "launchd_label": launchd_label,
+        "launch_agent_path": str(launch_agent_path),
+    }
+
+
+@contextmanager
+def shutdown_signal_logging(
+    logger: logging.Logger,
+    context: Mapping[str, object],
+) -> Iterator[None]:
+    """Log a managed shutdown request before ending the local service loop."""
+    previous_handlers: dict[int, signal.Handlers] = {}
+
+    def request_shutdown(signum: int, _frame: object) -> None:
+        signal_name = signal.Signals(signum).name
+        log_event(
+            logger,
+            logging.INFO,
+            "component_shutdown_trigger_received",
+            context={**context, "shutdown_signal": signal_name},
+        )
+        raise KeyboardInterrupt
+
+    for current_signal in (signal.SIGINT, signal.SIGTERM):
+        previous_handlers[current_signal] = signal.getsignal(current_signal)
+        signal.signal(current_signal, request_shutdown)
+    try:
+        yield
+    finally:
+        for current_signal, previous in previous_handlers.items():
+            signal.signal(current_signal, previous)

engineering_platform/console_presentation.py

@@ -0,0 +1,14 @@
+"""Installed EP Server Console presentation resources.
+
+This module owns only package resources and stable presentation identifiers.
+It has no listener, route, project, queue, execution or persistence authority.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+ASSET_DIRECTORY = Path(__file__).with_name("assets")
+APP_ICON_DARK = "operations-console/apple-touch-icon-dark.png"
+APP_ICON_LIGHT = "operations-console/apple-touch-icon-light.png"
+WEB_MANIFEST = "operations-console/manifest.webmanifest"

engineering_platform/console_route_ownership.py

@@ -0,0 +1,83 @@
+"""Canonical ownership for Console and Console-adjacent HTTP routes.
+
+Ownership is an authority decision, not a presentation decision. A selected
+project may tailor a PLATFORM projection, but never its authority.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+
+from .platform_components import PLATFORM_COMPONENT_ROUTE_PATTERN, RETIRED_COMPONENT_ALIAS_ROUTE_PATTERN
+
+PLATFORM = "PLATFORM"
+PROJECT = "PROJECT"
+HOST_ADMIN = "HOST_ADMIN"
+TRANSPORT_INTERNAL = "TRANSPORT_INTERNAL"
+HISTORICAL_UNREACHABLE = "HISTORICAL_UNREACHABLE"
+OWNERS = frozenset({PLATFORM, PROJECT, HOST_ADMIN, TRANSPORT_INTERNAL, HISTORICAL_UNREACHABLE})
+
+
+@dataclass(frozen=True)
+class ConsoleRoute:
+    methods: tuple[str, ...]
+    pattern: str
+    owner: str
+    component: str
+    description: str
+    selected_project_presentation_only: bool = False
+
+    def matches(self, method: str, path: str) -> bool:
+        return method.upper() in self.methods and re.fullmatch(self.pattern, path) is not None
+
+
+# Closed list: each addition must select an owner and component family.
+ROUTE_OWNERSHIP_MATRIX: tuple[ConsoleRoute, ...] = (
+    ConsoleRoute(("GET",), r"/", PLATFORM, "console_shell", "Console shell", True),
+    ConsoleRoute(("GET",), r"/(?:favicon\.ico|apple-touch-icon(?:-precomposed)?\.png)", PLATFORM, "console_shell", "Console icons"),
+    ConsoleRoute(("GET",), r"/assets/[A-Za-z0-9_./-]+", PLATFORM, "console_shell", "Installed Console assets"),
+    ConsoleRoute(("GET",), r"/health", PLATFORM, "platform_components", "Platform Components health", True),
+    ConsoleRoute(("GET",), r"/api/platform-status", PLATFORM, "platform_components", "Platform Components projection", True),
+    ConsoleRoute(("GET",), r"/api/(?:dashboard-snapshot|status|events)", PLATFORM, "platform_components", "Platform status projection or stream", True),
+    ConsoleRoute(("GET",), rf"/api/components/{PLATFORM_COMPONENT_ROUTE_PATTERN}/details", PLATFORM, "platform_components", "Component detail popout", True),
+    ConsoleRoute(("POST",), rf"/api/components/{PLATFORM_COMPONENT_ROUTE_PATTERN}/restart", PLATFORM, "platform_components", "Canonical component restart", True),
+    ConsoleRoute(("GET", "POST"), rf"/api/logs/(?:all|{PLATFORM_COMPONENT_ROUTE_PATTERN})", PLATFORM, "platform_components", "Platform component logs", True),
+    ConsoleRoute(("GET",), r"/api/provider-login-status", PLATFORM, "provider_login", "Provider readiness", True),
+    ConsoleRoute(("POST",), r"/api/provider-login/(?:repair|logout)", PLATFORM, "provider_login", "Provider login action", True),
+    ConsoleRoute(("GET",), r"/api/execution-runtime-status", PLATFORM, "execution_runtime", "Execution runtime readiness", True),
+    ConsoleRoute(("POST",), r"/api/execution-runtime/repair", PLATFORM, "execution_runtime", "Execution runtime repair", True),
+    ConsoleRoute(("GET",), r"/api/provider-capacity", PLATFORM, "provider_capacity", "Provider capacity", True),
+    ConsoleRoute(("GET", "POST"), r"/api/provider-capacity/configuration", PLATFORM, "provider_capacity", "Provider capacity settings", True),
+    ConsoleRoute(("GET",), r"/api/github-rate-limit", PLATFORM, "provider_capacity", "Provider rate-limit diagnostics", True),
+    ConsoleRoute(("GET", "POST"), r"/api/configuration", PLATFORM, "server_settings", "Server settings", True),
+    ConsoleRoute(("GET",), r"/api/(?:process-metrics|usage)", PLATFORM, "platform_components", "Platform diagnostics", True),
+    ConsoleRoute(("GET",), r"/api/host-admin/diagnostics", HOST_ADMIN, "host_admin", "Bounded installation diagnostics", True),
+    ConsoleRoute(("GET",), r"/api/central-data/export", PLATFORM, "server_settings", "Central data export", True),
+    ConsoleRoute(("POST",), r"/api/central-data/(?:relocate(?:/browse)?|import)", PLATFORM, "server_settings", "Central data transfer", True),
+    ConsoleRoute(("GET", "POST"), r"/api/central-database/configuration", PLATFORM, "server_settings", "Central database maintenance settings", True),
+    ConsoleRoute(("GET",), r"/v1/operations/projects", PLATFORM, "operations", "Operations project listing"),
+    ConsoleRoute(("GET",), r"/api/prompt-history", PROJECT, "project_history", "Project run history"),
+    ConsoleRoute(("GET",), r"/api/prompt-history/[a-z0-9][a-z0-9-]{0,63}/(?:report|chat|details)", PROJECT, "project_history", "Project run detail"),
+    ConsoleRoute(("GET",), r"/api/telemetry/[0-9]{4}-[0-9]{2}-[0-9]{2}", PROJECT, "project_history", "Project telemetry detail"),
+    ConsoleRoute(("POST",), r"/api/execution-(?:dismiss|retry)", PROJECT, "project_execution", "Project execution action"),
+    ConsoleRoute(("POST",), r"/api/dashboard-translate", PROJECT, "project_console", "Project Console translation"),
+    ConsoleRoute(("GET",), r"/diagnostics/topology", TRANSPORT_INTERNAL, "transport", "Transport topology diagnostic"),
+    ConsoleRoute(("GET",), r"/(?:healthz|readyz)", TRANSPORT_INTERNAL, "transport", "Transport probe"),
+    ConsoleRoute(("POST",), r"/v1/projects/[A-Za-z0-9._-]+/submissions", TRANSPORT_INTERNAL, "transport", "Authenticated submission ingress"),
+    ConsoleRoute(("POST",), r"/v1/agent/(?:pair|register|heartbeat|attachment)", TRANSPORT_INTERNAL, "transport", "Agent transport control"),
+    ConsoleRoute(("POST",), r"/api/runtime-directory/open", HISTORICAL_UNREACHABLE, "historical_unreachable", "Retired checkout runtime action"),
+    ConsoleRoute(("POST",), r"/api/configuration/inbox-location(?:/browse)?", HISTORICAL_UNREACHABLE, "historical_unreachable", "Retired local Inbox-watcher configuration"),
+    ConsoleRoute(("GET", "POST"), r"/api/logs/(?:inbox|dashboard)", HISTORICAL_UNREACHABLE, "historical_unreachable", "Retired legacy component-log routes"),
+    ConsoleRoute(("GET", "POST"), rf"/api/components/{RETIRED_COMPONENT_ALIAS_ROUTE_PATTERN}/(?:details|restart)", HISTORICAL_UNREACHABLE, "historical_unreachable", "Retired legacy component authority"),
+)
+
+
+def route_owners(method: str, path: str) -> tuple[ConsoleRoute, ...]:
+    return tuple(route for route in ROUTE_OWNERSHIP_MATRIX if route.matches(method, path))
+
+
+def route_owner(method: str, path: str) -> ConsoleRoute | None:
+    matches = route_owners(method, path)
+    if len(matches) > 1:
+        raise RuntimeError(f"AMBIGUOUS_ROUTE_OWNERSHIP: {method} {path}")
+    return matches[0] if matches else None

engineering_platform/contracts/__init__.py

@@ -0,0 +1,38 @@
+"""Stable, read-only contracts for external Engineering Platform consumers.
+
+The contract layer projects canonical Engineering Platform evidence.  It is
+deliberately downstream from lifecycle code and contains no action executor.
+"""
+
+from .models import ActionAuditRecord, ActionPolicyDecision, AllowedAction, EvidenceReference
+from .ep_consumer import (
+    AuthEnvelope,
+    ConsumerEnvelope,
+    ContractError,
+    ErrorCode,
+    ErrorEnvelope,
+    RequestEnvelope,
+    ResponseEnvelope,
+    deserialize_request,
+    serialize,
+)
+from .projection import evaluate_action, get_allowed_actions, get_run_context
+
+__all__ = (
+    "ActionAuditRecord",
+    "ActionPolicyDecision",
+    "AllowedAction",
+    "AuthEnvelope",
+    "ConsumerEnvelope",
+    "ContractError",
+    "ErrorCode",
+    "ErrorEnvelope",
+    "EvidenceReference",
+    "RequestEnvelope",
+    "ResponseEnvelope",
+    "deserialize_request",
+    "evaluate_action",
+    "get_allowed_actions",
+    "get_run_context",
+    "serialize",
+)