specromancy-engine 0.1.3__py3-none-any.whl

specromancy_engine/_engine/approval_service.py

@@ -0,0 +1,278 @@
+"""Coordinate approval requests, grants, invalidation, and continuation.
+
+The caller supplies a strictly loaded manifest for requests. Grants deliberately
+load persisted state here before checking bindings, so drift can be audited.
+Validation collects evidence and records expected failures through an explicit
+collaborator; successful evidence is committed with the request or transition.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from . import responses
+from .approvals import (
+    approval_integrity_errors, approved_for_phase, approved_record,
+    build_approval_record, conflict, grant_decision, invalidate_decision,
+    pending_approval, request_decision, require_binding,
+)
+from ..artifacts import ArtifactError, artifact_record
+from .command_decisions import declared_reason, illegal_transition, select_outcome
+from .._config.config_models import PhaseConfig, PipelineConfig
+from .engine_errors import EngineError
+from ..exit_codes import ExitCode
+from .provenance import observe_provenance
+from .._runs.run_records import ApprovalRecord, RunRecord, VisitRecord, current_visit
+from ..run_store import RunStore
+from .validation_service import ValidationResult
+
+
+class ApprovalService:
+    """Own approval ordering with explicit validation and timestamp seams."""
+
+    def __init__(
+        self,
+        pipeline: PipelineConfig,
+        store: RunStore,
+        *,
+        validate: Callable[[RunRecord, VisitRecord, PhaseConfig], ValidationResult],
+        timestamp: Callable[[], str],
+    ) -> None:
+        self.pipeline = pipeline
+        self.store = store
+        self._perform_validation = validate
+        self._timestamp = timestamp
+
+    def invalidate_approval(
+        self,
+        manifest: RunRecord,
+        visit: VisitRecord,
+        approval: ApprovalRecord,
+        mismatches: list[str],
+    ) -> None:
+        decided_at = self._timestamp()
+
+        self.store.decide_approval(
+            manifest["run_id"],
+            lambda value: invalidate_decision(
+                value, approval, decided_at=decided_at, mismatches=mismatches,
+            ),
+        )
+
+    def advance_approved(
+        self,
+        manifest: RunRecord,
+        visit: VisitRecord,
+        approval: ApprovalRecord,
+    ) -> dict[str, Any]:
+        require_binding(manifest, approval)
+        transition = next((
+            item for item in self.pipeline.phase(visit["phase_id"]).transitions
+            if item.outcome == approval["outcome"]
+        ), None)
+        decision = self.store.decide_approval(
+            manifest["run_id"], lambda value: grant_decision(
+                value, approval, transition_target=transition.target if transition else None,
+                decided_at=None,
+            ),
+        )
+        manifest, approval = decision.manifest, decision.approval
+        if decision.disposition == "completed":
+            return responses.response_for_state(
+                self.pipeline, manifest, "approval was already recorded"
+            )
+        visit = current_visit(manifest)
+        try:
+            current_hash = self.artifact_hash(manifest, visit)
+        except EngineError:
+            current_hash = ""
+        mismatches = approval_integrity_errors(
+            approval,
+            artifact_sha256=current_hash,
+            pipeline_sha256=self.pipeline.config_hash,
+        )
+        if mismatches:
+            self.invalidate_approval(manifest, visit, approval, mismatches)
+            raise EngineError(
+                ExitCode.APPROVAL_REQUIRED,
+                "approval is stale because its artifact or pipeline changed",
+                "stale-approval",
+                phase=visit["phase_id"],
+                visit_number=visit["ordinal"],
+                mismatches=mismatches,
+            )
+        if transition is None:
+            raise conflict(approval)
+        phase = self.pipeline.phase(visit["phase_id"])
+        evidence = self._perform_validation(manifest, visit, phase)
+        updated = self.store.transition_visit(
+            manifest["run_id"],
+            self.pipeline,
+            visit["ordinal"],
+            outcome=approval["outcome"],
+            transition_target=transition.target,
+            terminal_result={
+                "outcome": approval["outcome"],
+                "phase": phase.id,
+                "visit_number": visit["ordinal"],
+                "approval_reason": approval["reason"],
+            },
+            validation_checks=evidence.checks,
+            mutation_result=evidence.mutation_result,
+            command_results=evidence.command_results,
+        )
+        return responses.after_transition(self.pipeline, updated, approval["outcome"])
+
+    def request_approval(
+        self,
+        manifest: RunRecord,
+        *,
+        reason: str | None,
+        details: str | None = None,
+        outcome: str | None = None,
+    ) -> dict[str, Any]:
+        run_id = manifest["run_id"]
+        visit = current_visit(manifest)
+        if visit is None or visit["status"] not in {"active", "awaiting-approval"}:
+            raise illegal_transition("only an active visit can request approval", manifest)
+        phase = self.pipeline.phase(visit["phase_id"])
+        chosen_reason = declared_reason(reason, phase.approval_conditions, "approval")
+        selected_outcome = select_outcome(phase, outcome)
+        evidence = self._perform_validation(manifest, visit, phase)
+        check = evidence.checks[0]
+        existing = pending_approval(manifest, visit["ordinal"])
+        if existing is not None:
+            require_binding(manifest, existing)
+            if not (
+                existing["reason"] == chosen_reason
+                and existing["details"] == details
+                and existing["artifact_sha256"] == check["sha256"]
+                and existing["outcome"] == selected_outcome
+            ):
+                raise illegal_transition("a different approval is already pending", manifest)
+        approved = approved_record(manifest, visit["ordinal"])
+        if approved is not None:
+            return self.advance_approved(manifest, visit, approved)
+
+        requested_at = existing["requested_at"] if existing else self._timestamp()
+        approval = build_approval_record(
+            run_id=run_id,
+            phase_id=phase.id,
+            visit_number=visit["ordinal"],
+            reason=chosen_reason,
+            details=details,
+            artifact_sha256=check["sha256"],
+            pipeline_sha256=self.pipeline.config_hash,
+            outcome=selected_outcome,
+            requested_at=requested_at,
+        )
+
+        decision = self.store.decide_approval(
+            run_id, lambda value: request_decision(
+                value, approval, validation_checks=evidence.checks,
+                mutation_result=evidence.mutation_result,
+                command_results=evidence.command_results,
+            ),
+        )
+        return responses.approval_response(
+            self.pipeline, decision.manifest, decision.approval,
+            "approval is required" if decision.disposition == "requested"
+            else "approval is already pending",
+        )
+
+    def approve(self, run_id: str, phase_id: str) -> dict[str, Any]:
+        # Approval verification intentionally loads persisted state before
+        # enforcing the current pipeline hash so drift can be recorded as a
+        # stale approval instead of becoming an unaudited early error.
+        manifest = self.store.load(run_id)
+        visit = current_visit(manifest)
+        if visit is None:
+            return self.idempotent_approval_result(manifest, phase_id)
+        if visit["phase_id"] != phase_id or visit["status"] != "awaiting-approval":
+            return self.idempotent_approval_result(manifest, phase_id)
+        approval = pending_approval(manifest, visit["ordinal"])
+        if approval is None:
+            approved = approved_record(manifest, visit["ordinal"])
+            if approved is not None:
+                return self.advance_approved(manifest, visit, approved)
+            raise illegal_transition("visit has no pending approval request", manifest)
+        require_binding(manifest, approval)
+        try:
+            current_hash = self.artifact_hash(manifest, visit)
+        except EngineError:
+            current_hash = ""
+        mismatches = approval_integrity_errors(
+            approval,
+            artifact_sha256=current_hash,
+            pipeline_sha256=self.pipeline.config_hash,
+        )
+        if mismatches:
+            self.invalidate_approval(manifest, visit, approval, mismatches)
+            raise EngineError(
+                ExitCode.APPROVAL_REQUIRED,
+                "approval request is stale because its artifact or pipeline changed",
+                "stale-approval",
+                phase=phase_id,
+                visit_number=visit["ordinal"],
+                mismatches=mismatches,
+            )
+        provenance_warnings = observe_provenance(self.pipeline, manifest)
+        if provenance_warnings:
+            warning = provenance_warnings[0]
+            raise EngineError(
+                ExitCode.INTERNAL_ERROR,
+                warning["message"],
+                warning["code"],
+                **warning.get("details", {}),
+            )
+        decided_at = self._timestamp()
+
+        transition = next((
+            item for item in self.pipeline.phase(phase_id).transitions
+            if item.outcome == approval["outcome"]
+        ), None)
+        if transition is None:
+            raise conflict(approval)
+        decision = self.store.decide_approval(
+            run_id, lambda value: grant_decision(
+                value, approval, decided_at=decided_at, transition_target=transition.target,
+            ),
+        )
+        if decision.disposition == "completed":
+            return responses.response_for_state(
+                self.pipeline, decision.manifest, "approval was already recorded"
+            )
+        return self.advance_approved(
+            decision.manifest, current_visit(decision.manifest), decision.approval,
+        )
+
+    def artifact_hash(
+        self, manifest: RunRecord, visit: VisitRecord
+    ) -> str:
+        try:
+            return artifact_record(
+                self.store.run_directory(manifest["run_id"]),
+                visit["output"]["path"],
+            )["sha256"]
+        except (ArtifactError, OSError) as exc:
+            details = dict(getattr(exc, "details", None) or {"error": str(exc)})
+            details.pop("error_code", None)
+            raise EngineError(
+                ExitCode.VALIDATION_FAILED,
+                "output artifact is missing or unreadable",
+                "invalid-output",
+                **details,
+            ) from exc
+
+    def idempotent_approval_result(
+        self, manifest: RunRecord, phase_id: str
+    ) -> dict[str, Any]:
+        approved = approved_for_phase(manifest, phase_id)
+        if approved is None:
+            raise illegal_transition(
+                f"phase {phase_id!r} has no pending approval", manifest
+            )
+        return responses.response_for_state(
+            self.pipeline, manifest, "approval was already recorded"
+        )

specromancy_engine/_engine/approvals.py

@@ -0,0 +1,248 @@
+"""Pure approval selectors, integrity checks, and detached state changes.
+
+Callers supply timestamps and observations; decisions run against locked state.
+"""
+
+from __future__ import annotations
+
+import copy
+from dataclasses import dataclass, field
+from typing import Any
+
+from .engine_errors import EngineError
+from ..exit_codes import ExitCode
+from .._runs.run_records import ApprovalRecord, RunRecord, VisitRecord, current_visit, latest_approval
+
+
+def build_approval_record(
+    *,
+    run_id: str,
+    phase_id: str,
+    visit_number: int,
+    reason: str,
+    details: str | None,
+    artifact_sha256: str,
+    pipeline_sha256: str,
+    outcome: str,
+    requested_at: str,
+) -> ApprovalRecord:
+    return {
+        "run_id": run_id,
+        "phase_id": phase_id,
+        "visit_number": visit_number,
+        "reason": reason,
+        "details": details,
+        "artifact_sha256": artifact_sha256,
+        "pipeline_sha256": pipeline_sha256,
+        "outcome": outcome,
+        "status": "pending",
+        "decision": None,
+        "actor": None,
+        "requested_at": requested_at,
+        "decided_at": None,
+    }
+
+
+def approval_integrity_errors(
+    approval: ApprovalRecord, *, artifact_sha256: str, pipeline_sha256: str
+) -> list[str]:
+    """Return stable mismatch labels for an approval's bound inputs."""
+
+    errors: list[str] = []
+    if approval.get("artifact_sha256") != artifact_sha256:
+        errors.append("artifact")
+    if approval.get("pipeline_sha256") != pipeline_sha256:
+        errors.append("pipeline")
+    return errors
+
+
+def pending_approval(manifest: RunRecord, visit_number: int) -> ApprovalRecord | None:
+    return latest_approval(manifest, "pending", visit_number=visit_number)
+
+
+def approved_record(manifest: RunRecord, visit_number: int) -> ApprovalRecord | None:
+    return latest_approval(manifest, "approved", visit_number=visit_number)
+
+
+def approved_for_phase(manifest: RunRecord, phase_id: str) -> ApprovalRecord | None:
+    return next(
+        (
+            item
+            for item in reversed(manifest["approvals"])
+            if item.get("phase_id") == phase_id and item.get("status") == "approved"
+        ),
+        None,
+    )
+
+
+def requested_state(
+    manifest: RunRecord,
+    approval: ApprovalRecord,
+    *,
+    validation_checks: list[dict[str, Any]],
+    command_results: list[dict[str, Any]],
+    mutation_result: dict[str, Any] | None,
+) -> RunRecord:
+    """Return a detached pending state using already collected evidence."""
+
+    updated = copy.deepcopy(manifest)
+    current = current_visit(updated)
+    assert current is not None
+    current["status"] = "awaiting-approval"
+    current["validation_checks"] = copy.deepcopy(validation_checks)
+    current["mutation_result"] = copy.deepcopy(mutation_result)
+    current["command_results"] = copy.deepcopy(command_results)
+    updated["status"] = "awaiting-approval"
+    updated["approvals"].append(copy.deepcopy(approval))
+    return updated
+
+
+IDENTITY_FIELDS = (
+    "run_id", "visit_number", "phase_id", "reason", "details", "requested_at",
+    "outcome", "pipeline_sha256", "artifact_sha256",
+)
+
+
+@dataclass
+class ApprovalDecision:
+    """A detached approval result; absent event means no durable change."""
+
+    manifest: RunRecord
+    approval: ApprovalRecord
+    disposition: str
+    event_type: str | None = None
+    visit_number: int | None = None
+    payload: dict[str, Any] = field(default_factory=dict)
+
+
+def conflict(observed: ApprovalRecord) -> EngineError:
+    return EngineError(
+        ExitCode.ILLEGAL_TRANSITION,
+        "approval state changed before the command could be applied",
+        "approval-state-changed",
+        run_id=observed.get("run_id"), phase=observed.get("phase_id"),
+        visit_number=observed.get("visit_number"),
+    )
+
+
+def require_binding(manifest: RunRecord, observed: ApprovalRecord) -> VisitRecord:
+    """Reject incomplete identities or a mismatched containing run/visit."""
+
+    if any(key not in observed for key in IDENTITY_FIELDS):
+        raise conflict(observed)
+    visits = [v for v in manifest["visits"]
+              if v["ordinal"] == observed["visit_number"]]
+    if (manifest["run_id"] != observed["run_id"] or len(visits) != 1
+            or visits[0]["phase_id"] != observed["phase_id"]):
+        raise conflict(observed)
+    return visits[0]
+
+
+def _matches(
+    record: ApprovalRecord, observed: ApprovalRecord, *, creation: bool = False,
+) -> bool:
+    return all(key in record and record[key] == observed[key]
+               for key in IDENTITY_FIELDS if not (creation and key == "requested_at"))
+
+
+def _eligible(
+    manifest: RunRecord, visit: VisitRecord, *, creation: bool = False,
+) -> bool:
+    statuses = ("active", "awaiting-approval") if creation else ("awaiting-approval",)
+    return (manifest["current_visit"] == visit["ordinal"]
+            and manifest["status"] in statuses and visit["status"] in statuses)
+
+
+def request_decision(
+    manifest: RunRecord, approval: ApprovalRecord, *,
+    validation_checks: list[dict[str, Any]], command_results: list[dict[str, Any]],
+    mutation_result: dict[str, Any] | None,
+) -> ApprovalDecision:
+    """Create once, or reuse the winning pending request without new evidence."""
+
+    visit = require_binding(manifest, approval)
+    if not _eligible(manifest, visit, creation=True):
+        raise conflict(approval)
+    records = [a for a in manifest["approvals"]
+               if a.get("visit_number") == visit["ordinal"]
+               and a.get("status") in ("pending", "approved")]
+    if records:
+        if (len(records) != 1 or records[0].get("status") != "pending"
+                or any(key not in records[0] for key in IDENTITY_FIELDS)
+                or not _matches(records[0], approval, creation=True)):
+            raise conflict(approval)
+        return ApprovalDecision(copy.deepcopy(manifest), copy.deepcopy(records[0]), "pending")
+    updated = requested_state(
+        manifest, approval, validation_checks=validation_checks,
+        command_results=command_results, mutation_result=mutation_result,
+    )
+    return ApprovalDecision(
+        updated, copy.deepcopy(approval), "requested", "approval-requested",
+        visit["ordinal"], {"reason": approval["reason"], "outcome": approval["outcome"]},
+    )
+
+
+def _identified(
+    manifest: RunRecord, observed: ApprovalRecord,
+) -> tuple[VisitRecord, ApprovalRecord]:
+    visit = require_binding(manifest, observed)
+    records = [a for a in manifest["approvals"] if _matches(a, observed)]
+    # A replacement on the same visit must not inherit an earlier decision.
+    competing = [a for a in manifest["approvals"]
+                 if a.get("visit_number") == visit["ordinal"]
+                 and a.get("status") in ("pending", "approved")
+                 and not _matches(a, observed)]
+    if len(records) != 1 or competing:
+        raise conflict(observed)
+    record = records[0]
+    if any(a.get("visit_number") == visit["ordinal"]
+           for a in manifest["approvals"][manifest["approvals"].index(record) + 1:]):
+        raise conflict(observed)
+    return visit, record
+
+
+def grant_decision(
+    manifest: RunRecord, observed: ApprovalRecord, *,
+    transition_target: str | None, decided_at: str | None,
+) -> ApprovalDecision:
+    """Grant exactly the observed request; None permits only existing grants."""
+
+    updated = copy.deepcopy(manifest)
+    visit, record = _identified(updated, observed)
+    if record.get("status") == "approved" and visit["status"] == "completed":
+        if (visit["chosen_outcome"] != record["outcome"]
+                or visit["transition_target"] != transition_target):
+            raise conflict(observed)
+        return ApprovalDecision(updated, copy.deepcopy(record), "completed")
+    if not _eligible(updated, visit):
+        raise conflict(observed)
+    if record.get("status") == "approved":
+        return ApprovalDecision(updated, copy.deepcopy(record), "granted")
+    if record.get("status") != "pending" or decided_at is None:
+        raise conflict(observed)
+    record.update(status="approved", decision="approved", actor="user", decided_at=decided_at)
+    return ApprovalDecision(
+        updated, copy.deepcopy(record), "granted", "approval-granted",
+        visit["ordinal"], {"phase_id": visit["phase_id"], "actor": "user"},
+    )
+
+
+def invalidate_decision(
+    manifest: RunRecord, observed: ApprovalRecord, *, decided_at: str,
+    mismatches: list[str],
+) -> ApprovalDecision:
+    """Invalidate only the eligible observed request, including stale retries."""
+
+    updated = copy.deepcopy(manifest)
+    visit, record = _identified(updated, observed)
+    if not _eligible(updated, visit):
+        raise conflict(observed)
+    if record.get("status") == "stale" and record.get("decision") == "invalidated":
+        return ApprovalDecision(updated, copy.deepcopy(record), "stale")
+    if record.get("status") not in ("pending", "approved"):
+        raise conflict(observed)
+    record.update(status="stale", decision="invalidated", actor="system", decided_at=decided_at)
+    return ApprovalDecision(
+        updated, copy.deepcopy(record), "stale", "approval-invalidated",
+        visit["ordinal"], {"mismatches": list(mismatches)},
+    )

specromancy_engine/_engine/command_decisions.py

@@ -0,0 +1,81 @@
+"""Shared, pure command argument resolution and transition diagnostics."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._config.config_models import PhaseConfig
+from .engine_errors import EngineError
+from ..errors import UsageError
+from ..exit_codes import ExitCode
+from .._runs.run_records import RunRecord
+
+
+def select_outcome(phase: PhaseConfig, requested: str | None) -> str:
+    outcomes = [
+        transition.outcome
+        for transition in phase.transitions
+        if transition.outcome != "blocked"
+    ]
+    if requested is not None:
+        if requested not in outcomes:
+            raise EngineError(
+                ExitCode.ILLEGAL_TRANSITION,
+                f"outcome {requested!r} is not declared by phase {phase.id!r}",
+                "undeclared-outcome",
+                phase=phase.id,
+                requested=requested,
+                declared=outcomes,
+            )
+        if len(outcomes) <= 1:
+            raise EngineError(
+                ExitCode.ILLEGAL_TRANSITION,
+                "--outcome is valid only when the phase has multiple successful outcomes",
+                "unnecessary-outcome",
+                phase=phase.id,
+                declared=outcomes,
+            )
+        return requested
+    if len(outcomes) != 1:
+        raise EngineError(
+            ExitCode.ILLEGAL_TRANSITION,
+            f"phase {phase.id!r} requires one of {outcomes!r}",
+            "outcome-required",
+            phase=phase.id,
+            declared=outcomes,
+        )
+    return outcomes[0]
+
+
+def declared_reason(
+    requested: str | None, declared: tuple[str, ...], kind: str
+) -> str:
+    if requested is None:
+        if len(declared) == 1:
+            return declared[0]
+        raise UsageError(
+            f"--reason is required; declared {kind} reasons: {', '.join(declared) or 'none'}",
+            {"declared": list(declared)},
+        )
+    if requested not in declared:
+        raise EngineError(
+            ExitCode.ILLEGAL_TRANSITION,
+            f"{kind} reason {requested!r} is not declared",
+            f"undeclared-{kind}-reason",
+            requested=requested,
+            declared=list(declared),
+        )
+    return requested
+
+
+def illegal_transition(
+    message: str, manifest: RunRecord, **details: Any
+) -> EngineError:
+    return EngineError(
+        ExitCode.ILLEGAL_TRANSITION,
+        message,
+        "illegal-transition",
+        status=manifest["status"],
+        **details,
+    )
+

specromancy_engine/_engine/engine_errors.py

@@ -0,0 +1,22 @@
+"""Expected engine rejections, independent of command orchestration."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..errors import SpecromancyError
+from ..exit_codes import ExitCode
+
+
+class EngineError(SpecromancyError):
+    """An expected state-machine rejection with a stable diagnostic."""
+
+    def __init__(
+        self,
+        code: ExitCode,
+        message: str,
+        diagnostic_code: str,
+        **details: Any,
+    ) -> None:
+        super().__init__(code, message, {"error_code": diagnostic_code, **details})
+        self.diagnostic_code = diagnostic_code

specromancy_engine/_engine/provenance.py

@@ -0,0 +1,58 @@
+"""Observe pipeline and prepared resource identity without choosing a policy."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._config.config_models import PipelineConfig
+from ..hashing import relative_path, sha256_file
+from .._runs.run_records import RunRecord
+
+
+def observe_provenance(
+    pipeline: PipelineConfig, manifest: RunRecord
+) -> list[dict[str, Any]]:
+    warnings: list[dict[str, Any]] = []
+    for visit in manifest["visits"]:
+        for kind in ("skill", "template"):
+            record = visit[kind]
+            if record is None:
+                continue
+            path = pipeline.repository_root / record["path"]
+            try:
+                actual = sha256_file(path)
+            except OSError as exc:
+                warnings.append(
+                    {
+                        "code": "provenance-missing",
+                        "message": f"visit {visit['ordinal']} {kind} provenance is missing",
+                        "details": {"path": record["path"], "error": str(exc)},
+                    }
+                )
+                continue
+            if actual != record["sha256"]:
+                warnings.append(
+                    {
+                        "code": "provenance-hash-mismatch",
+                        "message": f"visit {visit['ordinal']} {kind} changed after preparation",
+                        "details": {
+                            "path": record["path"],
+                            "expected": record["sha256"],
+                            "actual": actual,
+                        },
+                    }
+                )
+    return warnings
+
+
+def pipeline_matches(pipeline: PipelineConfig, manifest: RunRecord) -> bool:
+    return manifest["pipeline"] == pipeline_identity(pipeline)
+
+
+def pipeline_identity(pipeline: PipelineConfig) -> dict[str, Any]:
+    return {
+        "id": pipeline.id,
+        "version": pipeline.version,
+        "path": relative_path(pipeline.path, pipeline.repository_root),
+        "sha256": pipeline.config_hash,
+    }