specromancy-engine 0.1.3__py3-none-any.whl

specromancy_engine/commands.py

@@ -0,0 +1,140 @@
+"""Run trusted validation commands without a shell and capture bounded summaries."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import time
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from ._config.config_models import ValidationCommand
+
+
+DEFAULT_SUMMARY_BYTES = 4096
+
+
+def execute_validation_commands(
+    commands: tuple[ValidationCommand, ...] | list[ValidationCommand],
+    repository_root: Path,
+    run_directory: Path,
+    visit_number: int,
+    *,
+    summary_bytes: int = DEFAULT_SUMMARY_BYTES,
+    fault_injector: Callable[[str], None] | None = None,
+) -> list[dict[str, Any]]:
+    """Execute commands sequentially, stopping at the first required failure."""
+
+    results: list[dict[str, Any]] = []
+    secret_values = _secret_environment_values()
+    command_directory = run_directory / "commands"
+    command_directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+    for index, command in enumerate(commands, 1):
+        stdout_path = command_directory / f"{visit_number:03}-{index:02}-stdout.txt"
+        stderr_path = command_directory / f"{visit_number:03}-{index:02}-stderr.txt"
+        started = time.monotonic()
+        timed_out = False
+        missing = False
+        try:
+            completed = subprocess.run(
+                list(command.argv),
+                cwd=repository_root,
+                check=False,
+                shell=False,
+                capture_output=True,
+                timeout=command.timeout_seconds,
+                env=os.environ.copy(),
+            )
+            stdout = completed.stdout
+            stderr = completed.stderr
+            exit_code: int | None = completed.returncode
+        except subprocess.TimeoutExpired as exc:
+            timed_out = True
+            stdout = _as_bytes(exc.stdout)
+            stderr = _as_bytes(exc.stderr)
+            exit_code = None
+        except OSError as exc:
+            missing = isinstance(exc, FileNotFoundError)
+            stdout = b""
+            stderr = str(exc).encode("utf-8", "replace")
+            exit_code = None
+        duration = max(0.0, time.monotonic() - started)
+        if fault_injector is not None:
+            fault_injector("before-command-output-write")
+        stdout_path.write_bytes(stdout)
+        if fault_injector is not None:
+            fault_injector("after-command-stdout-write")
+        stderr_path.write_bytes(stderr)
+        if fault_injector is not None:
+            fault_injector("after-command-output-write")
+        failed = timed_out or missing or exit_code != 0
+        result = {
+            "executable": command.argv[0],
+            "arguments": list(command.argv[1:]),
+            "required": command.required,
+            "exit_code": exit_code,
+            "duration_seconds": round(duration, 6),
+            "timed_out": timed_out,
+            "missing_executable": missing,
+            "status": "failed" if failed else "passed",
+            "stdout_path": stdout_path.relative_to(run_directory).as_posix(),
+            "stderr_path": stderr_path.relative_to(run_directory).as_posix(),
+            "stdout_summary": _summary(stdout, summary_bytes, secret_values),
+            "stderr_summary": _summary(stderr, summary_bytes, secret_values),
+        }
+        results.append(result)
+        if failed and command.required:
+            break
+    return results
+
+
+def first_required_failure(results: list[dict[str, Any]]) -> dict[str, Any] | None:
+    return next(
+        (
+            result
+            for result in results
+            if result.get("required") and result.get("status") == "failed"
+        ),
+        None,
+    )
+
+
+def _summary(content: bytes, limit: int, secret_values: tuple[str, ...] = ()) -> str:
+    if limit < 0:
+        raise ValueError("summary byte limit must not be negative")
+    text = content.decode("utf-8", "replace")
+    for value in secret_values:
+        text = text.replace(value, "[REDACTED]")
+    redacted = text.encode("utf-8")
+    prefix = redacted[:limit].decode("utf-8", "replace")
+    if len(redacted) > limit:
+        prefix += f"\n...[truncated {len(redacted) - limit} bytes]"
+    return prefix
+
+
+def _secret_environment_values() -> tuple[str, ...]:
+    sensitive = re.compile(
+        r"(?:SECRET|TOKEN|PASSWORD|PASSWD|CREDENTIAL|PRIVATE|API[_-]?KEY|AUTH)",
+        re.IGNORECASE,
+    )
+    return tuple(
+        sorted(
+            {
+                value
+                for name, value in os.environ.items()
+                if value and sensitive.search(name)
+            },
+            key=len,
+            reverse=True,
+        )
+    )
+
+
+def _as_bytes(value: bytes | str | None) -> bytes:
+    if value is None:
+        return b""
+    if isinstance(value, bytes):
+        return value
+    return value.encode("utf-8", "replace")

specromancy_engine/config.py

@@ -0,0 +1,63 @@
+"""Public compatibility facade for declarative pipeline configuration.
+
+Parsing, immutable records, diagnostics, and canonical encoding live in separate
+internal modules. Existing imports here continue to reference those same objects.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ._config.config_errors import PipelineConfigError, _MISSING, _json_value
+from ._config.config_loader import (
+    IDENTIFIER_PATTERN,
+    MUTATION_POLICIES,
+    SUPPORTED_SCHEMA_VERSION,
+    VALIDATOR_TYPES,
+    _Loader,
+    _discover_root,
+    _safe_declared_path,
+    _validate_inputs,
+    _validate_output_pattern,
+    load_pipeline,
+)
+from ._config.config_models import (
+    PhaseConfig,
+    PipelineConfig,
+    TransitionConfig,
+    ValidationCommand,
+    ValidatorConfig,
+)
+from ._config.config_serialization import _canonical_document
+from .contracts import RESERVED_COMMANDS
+
+
+def load_config(
+    path: str | Path,
+    repository_root: str | Path | None = None,
+) -> PipelineConfig:
+    """Backward-compatible descriptive alias for :func:`load_pipeline`."""
+
+    return load_pipeline(path, repository_root)
+
+
+def canonicalize_pipeline(pipeline: PipelineConfig) -> str:
+    return pipeline.canonical_json
+
+
+def hash_pipeline(pipeline: PipelineConfig) -> str:
+    return pipeline.config_hash
+
+
+def require_pipeline_hash(pipeline: PipelineConfig, expected_hash: str) -> None:
+    """Reject configuration drift for a persisted in-progress run."""
+
+    if pipeline.config_hash != expected_hash:
+        raise PipelineConfigError(
+            "pipeline-hash-mismatch",
+            "pipeline configuration changed after the run was created",
+            path=pipeline.path,
+            field="config_hash",
+            value={"expected": expected_hash, "actual": pipeline.config_hash},
+            remediation="restore the original pipeline or start a new run",
+        )

specromancy_engine/contracts.py

@@ -0,0 +1,20 @@
+"""Small public constants shared across configuration and CLI boundaries."""
+
+from __future__ import annotations
+
+
+RESERVED_COMMANDS = frozenset(
+    {
+        "init",
+        "phase",
+        "validate",
+        "approve",
+        "request-approval",
+        "block",
+        "status",
+        "resume",
+        "run",
+        "adapters",
+    }
+)
+

specromancy_engine/engine.py

@@ -0,0 +1,423 @@
+"""Generic, deterministic state-machine execution."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from ._engine import responses
+from ._engine.approval_service import ApprovalService
+from ._engine.approvals import approved_record, pending_approval
+from ._engine.command_decisions import (
+    declared_reason as _declared_reason, illegal_transition, select_outcome,
+)
+from .artifacts import ArtifactError, verify_manifest_artifacts
+from ._config.config_models import PhaseConfig, PipelineConfig
+from ._engine.engine_errors import EngineError
+from .errors import UsageError
+from .exit_codes import ExitCode
+from .git import GitError, capture_repository_snapshot
+from ._engine.provenance import observe_provenance, pipeline_identity, pipeline_matches
+from ._engine.responses import RESPONSE_SCHEMA_VERSION  # Backward-compatible re-export.
+from .run_store import RunStore, format_timestamp, utc_now
+from ._runs.run_records import (
+    ApprovalRecord, RunRecord, VisitRecord, current_visit,
+)
+from ._engine.validation_service import ValidationResult, perform_validation
+
+
+class Engine:
+    """Advance runs using only configured outcomes and persisted state."""
+
+    def __init__(
+        self,
+        pipeline: PipelineConfig,
+        store: RunStore | None = None,
+        *,
+        command_fault_injector: Callable[[str], None] | None = None,
+    ) -> None:
+        self.pipeline = pipeline
+        self.store = store or RunStore(pipeline.repository_root)
+        self._command_fault_injector = command_fault_injector
+
+    def initialize(self, description: str) -> dict[str, Any]:
+        if not description.strip():
+            raise UsageError("DESCRIPTION must not be empty")
+        try:
+            git = capture_repository_snapshot(
+                self.pipeline.repository_root,
+                allow_non_git=self.pipeline.allow_non_git,
+            )
+        except GitError as exc:
+            raise EngineError(
+                ExitCode.INVALID_PIPELINE,
+                exc.message,
+                exc.diagnostic_code,
+                **exc.details,
+            ) from exc
+        manifest = self.store.create(
+            self.pipeline,
+            description,
+            git_base=git,
+            git_head=git,
+        )
+        visit = self.store.prepare_visit(
+            manifest["run_id"], self.pipeline, self.pipeline.start
+        )
+        manifest = self.store.load(manifest["run_id"])
+        return responses.action_response(
+            self.pipeline,
+            manifest,
+            visit,
+            f"run {manifest['run_id']} initialized; agent action is required",
+        )
+
+    def start_phase(self, run_id: str, phase_id: str) -> dict[str, Any]:
+        manifest = self._load(run_id)
+        if manifest["status"] == "paused":
+            return responses.paused_response(
+                self.pipeline, manifest, "run is paused; resume it first"
+            )
+        visit = self._current_visit(manifest)
+        if visit is None or visit["phase_id"] != phase_id:
+            expected = visit["phase_id"] if visit is not None else None
+            raise EngineError(
+                ExitCode.ILLEGAL_TRANSITION,
+                f"cannot start phase {phase_id!r}; expected {expected!r}",
+                "unexpected-phase",
+                requested=phase_id,
+                expected=expected,
+                status=manifest["status"],
+            )
+        if visit["status"] == "pending":
+            try:
+                baseline = capture_repository_snapshot(
+                    self.pipeline.repository_root,
+                    allow_non_git=self.pipeline.allow_non_git,
+                )
+            except GitError as exc:
+                raise EngineError(
+                    ExitCode.VALIDATION_FAILED,
+                    exc.message,
+                    exc.diagnostic_code,
+                    **exc.details,
+                ) from exc
+            visit = self.store.activate_visit(
+                run_id,
+                self.pipeline,
+                visit["ordinal"],
+                mutation_baseline=baseline,
+            )
+            manifest = self.store.load(run_id)
+        elif visit["status"] != "active":
+            raise EngineError(
+                ExitCode.ILLEGAL_TRANSITION,
+                f"phase {phase_id!r} cannot start from {visit['status']}",
+                "illegal-visit-status",
+                phase=phase_id,
+                status=visit["status"],
+            )
+        return responses.action_response(
+            self.pipeline,
+            manifest, visit, f"phase {phase_id} is active; agent action is required"
+        )
+
+    def validate(
+        self,
+        run_id: str,
+        phase_id: str | None = None,
+        *,
+        outcome: str | None = None,
+    ) -> dict[str, Any]:
+        manifest = self._load(run_id)
+        if manifest["status"] == "completed":
+            return responses.status_response(
+                self.pipeline, manifest, "run is already completed"
+            )
+        if manifest["status"] == "paused":
+            return responses.paused_response(
+                self.pipeline, manifest, "run is paused; resume it first"
+            )
+        visit = self._current_visit(manifest)
+        if visit is None:
+            raise self._illegal("run has no current visit", manifest)
+        if visit["status"] == "pending":
+            previous = manifest["visits"][-2] if len(manifest["visits"]) > 1 else None
+            if previous is not None and previous["status"] == "completed" and (
+                phase_id is None or phase_id == previous["phase_id"]
+            ):
+                return responses.action_response(
+                    self.pipeline,
+                    manifest,
+                    visit,
+                    "validation was already recorded; the next phase requires agent action",
+                )
+            raise self._illegal(
+                f"phase {visit['phase_id']!r} must be started before validation",
+                manifest,
+                expected_phase=visit["phase_id"],
+            )
+        if visit["status"] != "active":
+            raise self._illegal(
+                f"visit cannot be validated from {visit['status']}", manifest
+            )
+        self._require_phase(visit, phase_id)
+        phase = self.pipeline.phase(visit["phase_id"])
+        selected = self._select_outcome(phase, outcome)
+        transition = next(item for item in phase.transitions if item.outcome == selected)
+        evidence = self._perform_validation(manifest, visit, phase)
+        updated = self.store.transition_visit(
+            run_id,
+            self.pipeline,
+            visit["ordinal"],
+            outcome=selected,
+            transition_target=transition.target,
+            terminal_result={
+                "outcome": selected,
+                "phase": phase.id,
+                "visit_number": visit["ordinal"],
+            },
+            validation_checks=evidence.checks,
+            mutation_result=evidence.mutation_result,
+            command_results=evidence.command_results,
+        )
+        return responses.after_transition(self.pipeline, updated, selected)
+
+    def request_approval(
+        self,
+        run_id: str,
+        *,
+        reason: str | None,
+        details: str | None = None,
+        outcome: str | None = None,
+    ) -> dict[str, Any]:
+        manifest = self._load(run_id)
+        return self._approval_service().request_approval(
+            manifest, reason=reason, details=details, outcome=outcome
+        )
+
+    def approve(self, run_id: str, phase_id: str) -> dict[str, Any]:
+        return self._approval_service().approve(run_id, phase_id)
+
+    def block(
+        self,
+        run_id: str,
+        *,
+        reason: str | None,
+        details: str | None = None,
+    ) -> dict[str, Any]:
+        manifest = self._load(run_id)
+        if manifest["status"] == "blocked":
+            recorded = manifest["block_reason"] or {}
+            if reason is not None and reason != recorded.get("reason"):
+                raise self._illegal(
+                    "run is already blocked for a different reason", manifest
+                )
+            if details is not None and details != recorded.get("details"):
+                raise self._illegal(
+                    "run is already blocked with different details", manifest
+                )
+            return responses.blocked_response(
+                self.pipeline, manifest, "run is already blocked"
+            )
+        visit = self._current_visit(manifest)
+        if visit is None or visit["status"] != "active":
+            raise self._illegal("only an active visit can be blocked", manifest)
+        phase = self.pipeline.phase(visit["phase_id"])
+        chosen_reason = _declared_reason(reason, phase.stop_conditions, "stop")
+        block = {
+            "phase_id": phase.id,
+            "visit_number": visit["ordinal"],
+            "reason": chosen_reason,
+            "details": details,
+            "recorded_at": format_timestamp(utc_now()),
+        }
+
+        def change(value: RunRecord) -> None:
+            current = self._current_visit(value)
+            assert current is not None
+            current["status"] = "blocked"
+            value["status"] = "blocked"
+            value["block_reason"] = block
+
+        manifest = self.store.mutate(
+            run_id,
+            "run-blocked",
+            change,
+            visit_number=visit["ordinal"],
+            payload={"reason": chosen_reason, "details": details},
+        )
+        return responses.blocked_response(self.pipeline, manifest, "run is blocked")
+
+    def status(self, run_id: str) -> dict[str, Any]:
+        manifest = self.store.load(run_id, verify_artifacts=False)
+        warnings: list[dict[str, Any]] = []
+        if not pipeline_matches(self.pipeline, manifest):
+            warnings.append(
+                {
+                    "code": "pipeline-drift",
+                    "message": "pipeline configuration differs from the run provenance",
+                }
+            )
+        try:
+            verify_manifest_artifacts(manifest, self.store.run_directory(run_id))
+        except ArtifactError as exc:
+            warnings.append(
+                {
+                    "code": exc.diagnostic_code,
+                    "message": exc.message,
+                    "details": exc.details,
+                }
+            )
+        warnings.extend(observe_provenance(self.pipeline, manifest))
+        return responses.status_response(
+            self.pipeline, manifest, "run status", warnings=warnings
+        )
+
+    def resume(self, run_id: str) -> dict[str, Any]:
+        manifest = self._load(run_id)
+        if manifest["status"] == "paused":
+            manifest = self.store.resume_paused(run_id, self.pipeline)
+        return responses.response_for_state(self.pipeline, manifest, "run resumed")
+
+    def run(self, run_id: str) -> dict[str, Any]:
+        manifest = self._load(run_id)
+        visit = self._current_visit(manifest)
+        if manifest["status"] == "awaiting-approval" and visit is not None:
+            approved = approved_record(manifest, visit["ordinal"])
+            if approved is not None:
+                return self._advance_approved(manifest, visit, approved)
+        if visit is not None and visit["status"] == "pending":
+            return self.start_phase(run_id, visit["phase_id"])
+        return responses.response_for_state(
+            self.pipeline, manifest, "run reached a boundary"
+        )
+
+    def _approval_service(self) -> ApprovalService:
+        # Resolve validation and the engine clock at their original call sites,
+        # including hooks replaced after a grant has committed.
+        return ApprovalService(
+            self.pipeline,
+            self.store,
+            validate=lambda manifest, visit, phase: self._perform_validation(
+                manifest, visit, phase
+            ),
+            timestamp=lambda: format_timestamp(utc_now()),
+        )
+
+    def _advance_approved(
+        self,
+        manifest: RunRecord,
+        visit: VisitRecord,
+        approval: ApprovalRecord,
+    ) -> dict[str, Any]:
+        return self._approval_service().advance_approved(manifest, visit, approval)
+
+    def _load(self, run_id: str) -> RunRecord:
+        manifest = self.store.load(run_id)
+        if not pipeline_matches(self.pipeline, manifest):
+            raise EngineError(
+                ExitCode.INVALID_PIPELINE,
+                "pipeline configuration changed after the run was created",
+                "pipeline-hash-mismatch",
+                expected=manifest["pipeline"],
+                actual=pipeline_identity(self.pipeline),
+            )
+        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", {}),
+            )
+        return manifest
+
+    def _perform_validation(
+        self,
+        manifest: RunRecord,
+        visit: VisitRecord,
+        phase: PhaseConfig,
+    ) -> ValidationResult:
+        # Keep this orchestration seam for overlapping-attempt fault injection.
+        result = perform_validation(
+            self.pipeline,
+            self.store.run_directory(manifest["run_id"]),
+            visit,
+            phase,
+            command_fault_injector=self._command_fault_injector,
+        )
+        if result.failure is not None:
+            self.store.record_validation_attempt(
+                manifest["run_id"],
+                visit["ordinal"],
+                validation_checks=result.checks,
+                command_results=result.command_results,
+                mutation_result=result.mutation_result,
+                diagnostic={"error_code": result.failure.diagnostic_code},
+            )
+            raise result.failure from result.cause
+        return result
+
+    def _artifact_hash(
+        self, manifest: RunRecord, visit: VisitRecord
+    ) -> str:
+        return self._approval_service().artifact_hash(manifest, visit)
+
+    def _invalidate_approval(
+        self,
+        manifest: RunRecord,
+        visit: VisitRecord,
+        approval: ApprovalRecord,
+        mismatches: list[str],
+    ) -> None:
+        self._approval_service().invalidate_approval(manifest, visit, approval, mismatches)
+
+    def _select_outcome(self, phase: PhaseConfig, requested: str | None) -> str:
+        return select_outcome(phase, requested)
+
+    @staticmethod
+    def _current_visit(manifest: RunRecord) -> VisitRecord | None:
+        return current_visit(manifest)
+
+    # Preserve selector entry points used by existing callers and tests.
+    _pending_approval = staticmethod(pending_approval)
+    _approved_record = staticmethod(approved_record)
+
+    @staticmethod
+    def _require_phase(visit: VisitRecord, requested: str | None) -> None:
+        if requested is not None and requested != visit["phase_id"]:
+            raise EngineError(
+                ExitCode.ILLEGAL_TRANSITION,
+                f"requested phase {requested!r}; expected {visit['phase_id']!r}",
+                "unexpected-phase",
+                requested=requested,
+                expected=visit["phase_id"],
+            )
+
+    @staticmethod
+    def _illegal(
+        message: str, manifest: RunRecord, **details: Any
+    ) -> EngineError:
+        return illegal_transition(message, manifest, **details)
+
+    def _idempotent_approval_result(
+        self, manifest: RunRecord, phase_id: str
+    ) -> dict[str, Any]:
+        return self._approval_service().idempotent_approval_result(manifest, phase_id)
+
+
+def capture_git_metadata(root: Path, *, include_status: bool = False) -> dict[str, Any]:
+    """Backward-compatible alias for content-level repository capture."""
+
+    snapshot = capture_repository_snapshot(root, allow_non_git=True)
+    if include_status:
+        return {**snapshot, "status": []}
+    return {
+        "is_worktree": snapshot["is_worktree"],
+        "head": snapshot["head"],
+        "branch": snapshot["branch"],
+        "status": [],
+    }

specromancy_engine/errors.py

@@ -0,0 +1,42 @@
+"""Expected, user-facing failures raised by the Specromancy engine."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from .exit_codes import ExitCode
+
+
+class SpecromancyError(Exception):
+    """A failure with a stable exit code and serializable diagnostics."""
+
+    def __init__(
+        self,
+        code: ExitCode | int,
+        message: str,
+        details: Mapping[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = ExitCode(code)
+        self.message = message
+        self.details = dict(details) if details is not None else None
+
+    def as_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "code": int(self.code),
+            "message": self.message,
+        }
+        if self.details is not None:
+            payload["details"] = self.details
+        return payload
+
+
+class UsageError(SpecromancyError):
+    """Invalid command-line input."""
+
+    def __init__(
+        self, message: str, details: Mapping[str, Any] | None = None
+    ) -> None:
+        super().__init__(ExitCode.USAGE_ERROR, message, details)
+