rexecop 0.2.2a0__py3-none-any.whl

rexecop/__init__.py

@@ -0,0 +1,3 @@
+"""RExecOp — Regulated Execution Operations control-plane."""
+
+__version__ = "0.2.2a0"

rexecop/__main__.py

@@ -0,0 +1,4 @@
+from rexecop.cli import app
+
+if __name__ == "__main__":
+    app()

rexecop/adapters/__init__.py

@@ -0,0 +1 @@
+"""External system adapters (GovEngine, SCLite)."""

rexecop/adapters/govengine_port/__init__.py

@@ -0,0 +1,19 @@
+from rexecop.adapters.govengine_port.adapter import default_govengine_adapter
+from rexecop.adapters.govengine_port.client import GovEngineClient
+from rexecop.adapters.govengine_port.contracts import (
+    GovEngineAdapter,
+    GovEngineDecision,
+    GovEngineDecisionType,
+    GovEngineRequest,
+)
+from rexecop.adapters.govengine_port.static_adapter import StaticGovEngineAdapter
+
+__all__ = [
+    "GovEngineClient",
+    "GovEngineAdapter",
+    "GovEngineDecision",
+    "GovEngineDecisionType",
+    "GovEngineRequest",
+    "StaticGovEngineAdapter",
+    "default_govengine_adapter",
+]

rexecop/adapters/govengine_port/adapter.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from rexecop.adapters.govengine_port.client import GovEngineClient
+from rexecop.adapters.govengine_port.contracts import GovEngineAdapter, GovEngineDecisionType
+from rexecop.adapters.govengine_port.static_adapter import StaticGovEngineAdapter
+
+
+def default_govengine_adapter() -> GovEngineAdapter:
+    """Fail-closed real GovEngine client for local development."""
+    return GovEngineClient()
+
+
+def static_govengine_adapter(
+    decision_type: GovEngineDecisionType,
+    *,
+    summary: str = "",
+) -> GovEngineAdapter:
+    """Explicit bootstrap/test adapter."""
+    return StaticGovEngineAdapter(decision_type, summary=summary)

rexecop/adapters/govengine_port/client.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+from typing import Any
+
+from govengine import compose_runtime_admission_result, runtime_admission_public_summary
+from govengine.admission import RuntimeAdmissionResult
+
+from rexecop.adapters.govengine_port.contracts import (
+    GovEngineDecision,
+    GovEngineDecisionType,
+    GovEngineRequest,
+    is_mutating_mode,
+)
+
+
+def map_runtime_admission_to_decision(result: RuntimeAdmissionResult) -> GovEngineDecision:
+    if result.allowed:
+        return GovEngineDecision(
+            decision_type=GovEngineDecisionType.ALLOWED,
+            summary=result.reason_code,
+            details={
+                "admission_id": result.admission_id,
+                "status": result.status,
+                "public_summary": runtime_admission_public_summary(result),
+            },
+        )
+
+    actions = set(result.required_next_actions)
+    blockers = set(result.blockers)
+
+    if result.status == "needs_review" or actions.intersection(
+        {"approve_execution_ticket", "obtain_policy_decision"}
+    ):
+        return GovEngineDecision(
+            decision_type=GovEngineDecisionType.APPROVAL_REQUIRED,
+            summary=result.reason_code,
+            details={
+                "admission_id": result.admission_id,
+                "status": result.status,
+                "blockers": list(blockers),
+                "required_next_actions": list(actions),
+            },
+        )
+
+    if result.status == "dry_run_only" or "live_backend_disabled" in blockers:
+        return GovEngineDecision(
+            decision_type=GovEngineDecisionType.READ_ONLY_ONLY,
+            summary=result.reason_code,
+            details={"admission_id": result.admission_id, "status": result.status},
+        )
+
+    return GovEngineDecision(
+        decision_type=GovEngineDecisionType.BLOCKED,
+        summary=result.reason_code,
+        details={
+            "admission_id": result.admission_id,
+            "status": result.status,
+            "blockers": list(blockers),
+            "required_next_actions": list(actions),
+        },
+    )
+
+
+def build_compose_inputs(request: GovEngineRequest) -> dict[str, Any]:
+    preview = dict(request.preview)
+    override = preview.get("admission_compose")
+    if isinstance(override, dict):
+        return dict(override)
+
+    policy_decision = preview.get("policy_decision")
+    if policy_decision is None:
+        return {
+            "admission_id": f"adm-{request.operation_id}",
+            "subject_ref": f"rexecop:{request.operation_id}",
+            "prepared_execution_contract": {
+                "status": "prepared",
+                "digest": f"sha256:{request.operation_id}",
+            },
+            "policy_decision": None,
+            "execution_ticket": None,
+            "trust_decision": None,
+            "runner_profile": {
+                "name": "rexecop",
+                "allowed": False,
+                "live_backend_enabled": False,
+            },
+            "receipt_obligation": {"required": True, "binds": ["admission", "ticket"]},
+            "metadata": {"source": "rexecop", "phase": "2b"},
+        }
+
+    runner_profile = preview.get(
+        "runner_profile",
+        {
+            "name": "rexecop",
+            "allowed": True,
+            "live_backend_enabled": is_mutating_mode(request.mode),
+        },
+    )
+
+    return {
+        "admission_id": f"adm-{request.operation_id}",
+        "subject_ref": f"rexecop:{request.operation_id}",
+        "prepared_execution_contract": preview.get(
+            "prepared_execution_contract",
+            {"status": "prepared", "digest": f"sha256:{request.operation_id}"},
+        ),
+        "policy_decision": policy_decision,
+        "execution_ticket": preview.get("execution_ticket"),
+        "trust_decision": preview.get("trust_decision"),
+        "runner_profile": runner_profile,
+        "receipt_obligation": preview.get(
+            "receipt_obligation",
+            {"required": True, "binds": ["admission", "ticket"]},
+        ),
+        "artifact_refs": preview.get("artifact_refs"),
+        "metadata": {"source": "rexecop", "operation_id": request.operation_id},
+    }
+
+
+class GovEngineClient:
+    """Real GovEngine adapter using runtime admission composition."""
+
+    def evaluate(self, request: GovEngineRequest) -> GovEngineDecision:
+        inputs = build_compose_inputs(request)
+        try:
+            result = compose_runtime_admission_result(
+                **inputs,
+                live=is_mutating_mode(request.mode),
+            )
+        except Exception as exc:
+            return GovEngineDecision(
+                decision_type=GovEngineDecisionType.ERROR,
+                summary=str(exc),
+                details={"adapter": "govengine_client"},
+            )
+        return map_runtime_admission_to_decision(result)
+
+
+def build_runner_request_preview(
+    plan_steps: list[dict[str, Any]],
+    *,
+    operation_id: str,
+) -> dict[str, Any]:
+    """Shape helper for future runner execution (Phase 4+)."""
+    from govengine.execution.runner_protocol import GovRunnerRequest, GovRunnerStep
+
+    steps = tuple(
+        GovRunnerStep(
+            index=index,
+            tool=str(step.get("connector") or step.get("type") or "internal"),
+            args=(str(step.get("action") or ""),),
+        )
+        for index, step in enumerate(plan_steps)
+    )
+    request = GovRunnerRequest(
+        request_id=f"req-{operation_id}",
+        source="rexecop",
+        steps=steps,
+        dry_run=True,
+    )
+    return request.as_dict()

rexecop/adapters/govengine_port/contracts.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any, Protocol
+
+
+class GovEngineDecisionType(StrEnum):
+    ALLOWED = "allowed"
+    BLOCKED = "blocked"
+    APPROVAL_REQUIRED = "approval_required"
+    MAINTENANCE_WINDOW_REQUIRED = "maintenance_window_required"
+    BACKUP_REQUIRED = "backup_required"
+    READ_ONLY_ONLY = "read_only_only"
+    HUMAN_REQUIRED = "human_required"
+    UNSUPPORTED = "unsupported"
+    ERROR = "error"
+
+
+BLOCKING_DECISIONS = frozenset(
+    {
+        GovEngineDecisionType.BLOCKED,
+        GovEngineDecisionType.READ_ONLY_ONLY,
+        GovEngineDecisionType.HUMAN_REQUIRED,
+        GovEngineDecisionType.UNSUPPORTED,
+        GovEngineDecisionType.ERROR,
+    }
+)
+
+WAITING_DECISIONS = frozenset(
+    {
+        GovEngineDecisionType.APPROVAL_REQUIRED,
+        GovEngineDecisionType.MAINTENANCE_WINDOW_REQUIRED,
+        GovEngineDecisionType.BACKUP_REQUIRED,
+    }
+)
+
+MUTATING_MODES = frozenset({"apply", "recovery"})
+
+
+def is_mutating_mode(mode: str) -> bool:
+    return mode in MUTATING_MODES
+
+
+@dataclass(frozen=True)
+class GovEngineRequest:
+    operation_id: str
+    profile: str
+    environment: str
+    intent: str
+    target: str
+    mode: str
+    risk: str
+    preview: dict[str, Any] = field(default_factory=dict)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "operation_id": self.operation_id,
+            "profile": self.profile,
+            "environment": self.environment,
+            "intent": self.intent,
+            "target": self.target,
+            "mode": self.mode,
+            "risk": self.risk,
+            "preview": dict(self.preview),
+        }
+
+
+@dataclass(frozen=True)
+class GovEngineDecision:
+    decision_type: GovEngineDecisionType
+    summary: str
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "decision_type": self.decision_type.value,
+            "summary": self.summary,
+            "details": dict(self.details),
+        }
+
+    @property
+    def allows_mutating_execution(self) -> bool:
+        return self.decision_type == GovEngineDecisionType.ALLOWED
+
+
+class GovEngineAdapter(Protocol):
+    def evaluate(self, request: GovEngineRequest) -> GovEngineDecision: ...

rexecop/adapters/govengine_port/static_adapter.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from rexecop.adapters.govengine_port.contracts import (
+    GovEngineDecision,
+    GovEngineDecisionType,
+    GovEngineRequest,
+)
+
+STATIC_ADAPTER_NOTICE = (
+    "StaticGovEngineAdapter is bootstrap/test only and is not production governance."
+)
+
+
+class StaticGovEngineAdapter:
+    """Bootstrap/test governance adapter. Not a policy engine."""
+
+    def __init__(
+        self,
+        decision_type: GovEngineDecisionType,
+        *,
+        summary: str = "",
+        details: dict[str, object] | None = None,
+    ) -> None:
+        self.decision_type = decision_type
+        self.summary = summary or f"static decision: {decision_type.value}"
+        self.details = dict(details or {})
+        self.bootstrap_only = True
+
+    def evaluate(self, request: GovEngineRequest) -> GovEngineDecision:
+        return GovEngineDecision(
+            decision_type=self.decision_type,
+            summary=self.summary,
+            details={
+                **self.details,
+                "adapter": "static",
+                "bootstrap_only": True,
+                "operation_id": request.operation_id,
+            },
+        )

rexecop/adapters/sclite_port/__init__.py

@@ -0,0 +1,26 @@
+from rexecop.adapters.sclite_port.contracts import (
+    ARTIFACT_SLOTS,
+    EVENT_SCLITE_MAPPING,
+    PLACEHOLDER_EMITTER_NOTICE,
+    RECEIPT_EXPORT_AUTHORITY,
+    SCLITE_SCHEMA_REFS,
+    SCLiteArtifactDescriptor,
+    SCLiteEmitter,
+    SCLiteReceiptExport,
+)
+from rexecop.adapters.sclite_port.emitter import SCLiteArtifactEmitter
+from rexecop.adapters.sclite_port.placeholder_emitter import PlaceholderSCLiteEmitter
+
+__all__ = [
+    "ARTIFACT_SLOTS",
+    "EVENT_SCLITE_MAPPING",
+    "PLACEHOLDER_EMITTER_NOTICE",
+    "RECEIPT_EXPORT_AUTHORITY",
+    "SCLITE_ARTIFACT_AUTHORITY",
+    "SCLITE_SCHEMA_REFS",
+    "SCLiteArtifactDescriptor",
+    "SCLiteArtifactEmitter",
+    "SCLiteEmitter",
+    "SCLiteReceiptExport",
+    "PlaceholderSCLiteEmitter",
+]

rexecop/adapters/sclite_port/contracts.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+PLACEHOLDER_EMITTER_NOTICE = (
+    "DEPRECATED: Placeholder SCLite emitter is bootstrap/offline only. "
+    "Use SCLiteArtifactEmitter for real emission (Phase 3B+). "
+    "Receipt exports under .rexecop/receipts/ are non-authoritative summaries."
+)
+
+SCLITE_ARTIFACT_AUTHORITY = "sclite_artifact"
+
+RECEIPT_EXPORT_AUTHORITY = "non_authoritative_export"
+
+SCLITE_SCHEMA_REFS: dict[str, str] = {
+    "intent_contract": "schemas/intent_contract.v0.2.schema.json",
+    "policy_decision": "schemas/policy_decision.v0.2.schema.json",
+    "execution_contract": "schemas/execution_contract.v0.2.schema.json",
+    "execution_ticket": "schemas/execution_ticket.v0.3.schema.json",
+    "execution_receipt": "schemas/execution_receipt.v0.2.schema.json",
+    "evidence_contract": "schemas/evidence_contract.v0.2.schema.json",
+}
+
+ARTIFACT_SLOTS = (
+    "intent_contract",
+    "policy_decision",
+    "execution_contract",
+    "execution_ticket",
+    "execution_receipt",
+    "evidence_contract",
+)
+
+EVENT_SCLITE_MAPPING: dict[str, dict[str, str]] = {
+    "operation_created": {
+        "future_artifact": "intent_contract",
+        "sclite_schema_ref": SCLITE_SCHEMA_REFS["intent_contract"],
+    },
+    "operation_triggered": {
+        "future_artifact": "intent_contract",
+        "sclite_schema_ref": SCLITE_SCHEMA_REFS["intent_contract"],
+    },
+    "plan_generated": {
+        "future_artifact": "execution_contract",
+        "sclite_schema_ref": SCLITE_SCHEMA_REFS["execution_contract"],
+    },
+    "govengine_decision_requested": {
+        "future_artifact": "policy_decision",
+        "sclite_schema_ref": SCLITE_SCHEMA_REFS["policy_decision"],
+    },
+    "govengine_decision_received": {
+        "future_artifact": "policy_decision",
+        "sclite_schema_ref": SCLITE_SCHEMA_REFS["policy_decision"],
+    },
+    "approval_received": {
+        "future_artifact": "execution_ticket",
+        "sclite_schema_ref": SCLITE_SCHEMA_REFS["execution_ticket"],
+    },
+    "state_transition": {
+        "future_artifact": "execution_receipt",
+        "sclite_schema_ref": SCLITE_SCHEMA_REFS["execution_receipt"],
+    },
+    "step_started": {
+        "future_artifact": "execution_receipt",
+        "sclite_schema_ref": SCLITE_SCHEMA_REFS["execution_receipt"],
+    },
+    "step_completed": {
+        "future_artifact": "execution_receipt",
+        "sclite_schema_ref": SCLITE_SCHEMA_REFS["execution_receipt"],
+    },
+    "step_failed": {
+        "future_artifact": "execution_receipt",
+        "sclite_schema_ref": SCLITE_SCHEMA_REFS["execution_receipt"],
+    },
+    "validation_started": {
+        "future_artifact": "evidence_contract",
+        "sclite_schema_ref": SCLITE_SCHEMA_REFS["evidence_contract"],
+    },
+    "validation_completed": {
+        "future_artifact": "evidence_contract",
+        "sclite_schema_ref": SCLITE_SCHEMA_REFS["evidence_contract"],
+    },
+    "receipt_generated": {
+        "future_artifact": "execution_receipt",
+        "sclite_schema_ref": SCLITE_SCHEMA_REFS["execution_receipt"],
+    },
+    "operation_completed": {
+        "future_artifact": "execution_receipt",
+        "sclite_schema_ref": SCLITE_SCHEMA_REFS["execution_receipt"],
+    },
+    "operation_failed": {
+        "future_artifact": "execution_receipt",
+        "sclite_schema_ref": SCLITE_SCHEMA_REFS["execution_receipt"],
+    },
+    "operation_escalated": {
+        "future_artifact": "evidence_contract",
+        "sclite_schema_ref": SCLITE_SCHEMA_REFS["evidence_contract"],
+    },
+}
+
+
+@dataclass(frozen=True)
+class SCLiteArtifactDescriptor:
+    artifact_role: str
+    sclite_schema_ref: str
+    descriptor_path: str | None = None
+    digest: str | None = None
+    status: str = "placeholder"
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "artifact_role": self.artifact_role,
+            "sclite_schema_ref": self.sclite_schema_ref,
+            "descriptor_path": self.descriptor_path,
+            "digest": self.digest,
+            "status": self.status,
+        }
+
+
+@dataclass
+class SCLiteReceiptExport:
+    operation_id: str
+    authority: str = RECEIPT_EXPORT_AUTHORITY
+    emitter: str = "placeholder"
+    migration_note: str = PLACEHOLDER_EMITTER_NOTICE
+    artifact_slots: dict[str, dict[str, Any]] = field(default_factory=dict)
+    evidence_event_mappings: list[dict[str, str]] = field(default_factory=list)
+    internal_evidence_event_ids: list[str] = field(default_factory=list)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "operation_id": self.operation_id,
+            "authority": self.authority,
+            "emitter": self.emitter,
+            "migration_note": self.migration_note,
+            "artifact_slots": dict(self.artifact_slots),
+            "evidence_event_mappings": list(self.evidence_event_mappings),
+            "internal_evidence_event_ids": list(self.internal_evidence_event_ids),
+        }
+
+
+class SCLiteEmitter(Protocol):
+    def export_operation_receipt(
+        self,
+        *,
+        operation_id: str,
+        events: list[dict[str, Any]],
+        plan_summary: dict[str, Any] | None = None,
+    ) -> SCLiteReceiptExport: ...