specromancy-engine 0.1.3__py3-none-any.whl

specromancy_engine/_engine/responses.py

@@ -0,0 +1,129 @@
+"""Versioned command envelopes over the existing action and status payloads."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..actions import build_action_packet
+from .approvals import pending_approval
+from .._config.config_models import PipelineConfig
+from ..exit_codes import ExitCode
+from .._runs.run_records import ApprovalRecord, RunRecord, VisitRecord, current_visit
+from ..status import build_status
+
+
+RESPONSE_SCHEMA_VERSION = 1
+
+
+def after_transition(
+    pipeline: PipelineConfig, manifest: RunRecord, outcome: str
+) -> dict[str, Any]:
+    if manifest["status"] == "blocked":
+        return blocked_response(
+            pipeline,
+            manifest, "run blocked because a configured loop limit was reached"
+        )
+    if manifest["status"] == "completed":
+        return status_response(
+            pipeline,
+            manifest, f"run completed with outcome {outcome!r}"
+        )
+    if manifest["status"] == "paused":
+        return paused_response(
+            pipeline,
+            manifest, f"outcome {outcome!r} recorded; run paused at checkpoint"
+        )
+    visit = current_visit(manifest)
+    assert visit is not None
+    return action_response(
+        pipeline,
+        manifest,
+        visit,
+        f"outcome {outcome!r} recorded; next phase requires agent action",
+    )
+
+
+def response_for_state(
+    pipeline: PipelineConfig, manifest: RunRecord, message: str
+) -> dict[str, Any]:
+    visit = current_visit(manifest)
+    if manifest["status"] in {"awaiting-agent", "active"} and visit is not None:
+        return action_response(pipeline, manifest, visit, message)
+    if manifest["status"] == "awaiting-approval":
+        approval = pending_approval(
+            manifest, visit["ordinal"] if visit is not None else -1
+        )
+        return approval_response(pipeline, manifest, approval, "approval is required")
+    if manifest["status"] == "paused":
+        return paused_response(pipeline, manifest, message)
+    if manifest["status"] == "blocked":
+        return blocked_response(pipeline, manifest, message)
+    return status_response(pipeline, manifest, message)
+
+
+def action_response(
+    pipeline: PipelineConfig, manifest: RunRecord, visit: VisitRecord, message: str
+) -> dict[str, Any]:
+    return {
+        "schema_version": RESPONSE_SCHEMA_VERSION,
+        "kind": "action",
+        "code": int(ExitCode.AGENT_ACTION_REQUIRED),
+        "message": message,
+        "action": build_action_packet(pipeline, manifest, visit),
+    }
+
+
+def approval_response(
+    pipeline: PipelineConfig,
+    manifest: RunRecord,
+    approval: ApprovalRecord | None,
+    message: str,
+) -> dict[str, Any]:
+    return {
+        "schema_version": RESPONSE_SCHEMA_VERSION,
+        "kind": "approval",
+        "code": int(ExitCode.APPROVAL_REQUIRED),
+        "message": message,
+        "approval": approval,
+        "status": build_status(manifest, pipeline),
+    }
+
+
+def blocked_response(
+    pipeline: PipelineConfig, manifest: RunRecord, message: str
+) -> dict[str, Any]:
+    return {
+        "schema_version": RESPONSE_SCHEMA_VERSION,
+        "kind": "status",
+        "code": int(ExitCode.RUN_BLOCKED),
+        "message": message,
+        "status": build_status(manifest, pipeline),
+    }
+
+
+def paused_response(
+    pipeline: PipelineConfig, manifest: RunRecord, message: str
+) -> dict[str, Any]:
+    return {
+        "schema_version": RESPONSE_SCHEMA_VERSION,
+        "kind": "status",
+        "code": int(ExitCode.RUN_PAUSED),
+        "message": message,
+        "status": build_status(manifest, pipeline),
+    }
+
+
+def status_response(
+    pipeline: PipelineConfig,
+    manifest: RunRecord,
+    message: str,
+    *,
+    warnings: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    return {
+        "schema_version": RESPONSE_SCHEMA_VERSION,
+        "kind": "status",
+        "code": int(ExitCode.SUCCESS),
+        "message": message,
+        "status": build_status(manifest, pipeline, warnings=warnings),
+    }

specromancy_engine/_engine/validation_service.py

@@ -0,0 +1,112 @@
+"""Collect ordered validation evidence without committing run state.
+
+Command logs remain the responsibility of commands.py. Expected failures are
+returned with their evidence so orchestration can persist one attempt before
+raising; unexpected failures (including injected interruptions) propagate.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ..commands import execute_validation_commands, first_required_failure
+from .._config.config_models import PhaseConfig, PipelineConfig
+from .engine_errors import EngineError
+from ..exit_codes import ExitCode
+from ..git import GitError, capture_repository_snapshot, enforce_mutation_policy
+from .._runs.run_records import VisitRecord
+from ..validation import ValidationFailure, validate_artifact
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    checks: list[dict[str, Any]]
+    command_results: list[dict[str, Any]]
+    mutation_result: dict[str, Any] | None
+    failure: EngineError | None = None
+    cause: Exception | None = None
+
+
+def perform_validation(
+    pipeline: PipelineConfig,
+    run_directory: Path,
+    visit: VisitRecord,
+    phase: PhaseConfig,
+    *,
+    command_fault_injector: Callable[[str], None] | None = None,
+) -> ValidationResult:
+    """Validate the artifact, execute commands, then enforce mutation policy.
+
+    Mutation failure takes precedence over a required command failure, including
+    mutations made by that failing command.
+    """
+
+    try:
+        check = validate_artifact(
+            run_directory,
+            visit["output"]["path"],
+            phase.validator,
+            template_path=phase.output_template_path,
+        )
+    except ValidationFailure as exc:
+        failed = {
+            "type": phase.validator.type,
+            "status": "failed",
+            "error_code": exc.diagnostic_code,
+            **exc.details,
+        }
+        return ValidationResult(
+            [failed], [], None,
+            EngineError(
+                ExitCode.VALIDATION_FAILED, exc.message, exc.diagnostic_code,
+                **exc.details,
+            ),
+            exc,
+        )
+
+    checks = [check]
+    command_results = execute_validation_commands(
+        phase.validation_commands,
+        pipeline.repository_root,
+        run_directory,
+        visit["ordinal"],
+        fault_injector=command_fault_injector,
+    )
+    command_failure = first_required_failure(command_results)
+    try:
+        baseline = visit.get("mutation_baseline")
+        if not isinstance(baseline, dict):
+            raise GitError(
+                "missing-mutation-baseline",
+                "the visit has no repository mutation baseline",
+            )
+        current = capture_repository_snapshot(
+            pipeline.repository_root,
+            allow_non_git=pipeline.allow_non_git,
+        )
+        mutation_result = enforce_mutation_policy(
+            baseline, current, phase.mutation, phase.allowlist
+        )
+    except GitError as exc:
+        return ValidationResult(
+            checks, command_results, exc.details.get("mutation_result"),
+            EngineError(
+                ExitCode.VALIDATION_FAILED, exc.message, exc.diagnostic_code,
+                **exc.details,
+            ),
+            exc,
+        )
+    if command_failure is not None:
+        return ValidationResult(
+            checks, command_results, mutation_result,
+            EngineError(
+                ExitCode.VALIDATION_FAILED,
+                "a required validation command failed",
+                "validation-command-failed",
+                command=command_failure,
+            ),
+        )
+    return ValidationResult(checks, command_results, mutation_result)

specromancy_engine/_runs/__init__.py

@@ -0,0 +1 @@
+"""Private runs implementation components; use the public facades."""

specromancy_engine/_runs/run_errors.py

@@ -0,0 +1,51 @@
+"""Shared run persistence errors; re-exported by run_store."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from ..errors import SpecromancyError
+from ..exit_codes import ExitCode
+
+
+class RunStoreError(SpecromancyError):
+    """Base error for expected run-store failures."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        diagnostic_code: str,
+        details: Mapping[str, Any] | None = None,
+        code: ExitCode = ExitCode.INTERNAL_ERROR,
+    ) -> None:
+        values = {"error_code": diagnostic_code}
+        if details:
+            values.update(details)
+        super().__init__(code, message, values)
+        self.diagnostic_code = diagnostic_code
+
+
+class RunNotFoundError(RunStoreError):
+    def __init__(self, run_id: str) -> None:
+        super().__init__(
+            f"run not found: {run_id}",
+            diagnostic_code="run-not-found",
+            details={"run_id": run_id},
+            code=ExitCode.NOT_FOUND,
+        )
+
+
+class RunCorruptionError(RunStoreError):
+    def __init__(
+        self, message: str, *, run_id: str, details: Mapping[str, Any] | None = None
+    ) -> None:
+        values: dict[str, Any] = {"run_id": run_id}
+        if details:
+            values.update(details)
+        super().__init__(
+            message,
+            diagnostic_code="corrupt-run",
+            details=values,
+        )

specromancy_engine/_runs/run_identity.py

@@ -0,0 +1,66 @@
+"""Path-safe run identities and injectable UTC time/random helpers."""
+
+from __future__ import annotations
+
+import inspect
+import re
+import secrets
+from collections.abc import Callable
+from datetime import datetime, timezone
+
+
+RUN_ID_PATTERN = re.compile(r"^[0-9]{8}T[0-9]{6}Z-[0-9a-f]{8}$")
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def format_timestamp(value: datetime) -> str:
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc).isoformat(timespec="microseconds").replace(
+        "+00:00", "Z"
+    )
+
+
+def validate_run_id(run_id: str) -> str:
+    """Return a valid path-safe run ID or raise ``ValueError``."""
+
+    if not isinstance(run_id, str) or not RUN_ID_PATTERN.fullmatch(run_id):
+        raise ValueError(f"invalid run ID: {run_id!r}")
+    try:
+        datetime.strptime(run_id[:16], "%Y%m%dT%H%M%SZ")
+    except ValueError as exc:
+        raise ValueError(f"invalid run ID timestamp: {run_id!r}") from exc
+    return run_id
+
+
+def is_valid_run_id(run_id: str) -> bool:
+    try:
+        validate_run_id(run_id)
+    except (TypeError, ValueError):
+        return False
+    return True
+
+
+def generate_run_id(
+    *,
+    clock: Callable[[], datetime] = utc_now,
+    random_source: Callable[..., bytes | str] = secrets.token_bytes,
+) -> str:
+    """Generate a UTC timestamp plus four cryptographically random bytes."""
+
+    now = clock()
+    if now.tzinfo is None:
+        now = now.replace(tzinfo=timezone.utc)
+    timestamp = now.astimezone(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    try:
+        inspect.signature(random_source).bind(4)
+    except (TypeError, ValueError):
+        random_value = random_source()
+    else:
+        random_value = random_source(4)
+    suffix = random_value.hex() if isinstance(random_value, bytes) else random_value
+    run_id = f"{timestamp}-{suffix}"
+    return validate_run_id(run_id)

specromancy_engine/_runs/run_persistence.py

@@ -0,0 +1,303 @@
+"""Internal manifest/event durability protocol for already authorized run paths.
+
+The run store owns path authorization and domain decisions. This component owns
+serialization, event reconciliation, and ordered manifest replacement/event append.
+Locked helpers never acquire a lock; their caller must hold the run lock.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from ..hashing import sha256_json
+from ..locking import RunLock
+from .run_errors import RunCorruptionError
+from .run_records import EVENT_SCHEMA_VERSION, EventRecord, RunRecord
+from . import run_validation
+
+
+class RunPersistence:
+    """Implement schema-version-1 IO without workflow or artifact policies."""
+
+    def __init__(
+        self,
+        *,
+        clock: Callable[[], datetime],
+        timestamp: Callable[[], str],
+        fault: Callable[[str], None],
+    ) -> None:
+        self._clock = clock
+        self._timestamp = timestamp
+        self._fault = fault
+
+    def lock(self, directory: Path) -> RunLock:
+        """Return a lock for a path already authorized by the run store."""
+        return RunLock(directory / ".lock", clock=self._clock)
+
+    @contextmanager
+    def locked(
+        self, directory: Path, run_id: str, *, recover: bool = True
+    ) -> Iterator[tuple[RunRecord, list[EventRecord]]]:
+        """Hold one lock across loading, reconciliation, and the caller's changes.
+
+        Returning from this context does not commit implicitly. The caller must
+        explicitly advance a revision and commit a mutation, so idempotent returns
+        and artifact-only writes do not emit extra revisions or events. Creation
+        uses lock() separately because no manifest exists yet.
+        """
+        with self.lock(directory):
+            manifest = self._read_manifest(directory, run_id)
+            if recover:
+                events = self._ensure_event_consistency(directory, manifest)
+            else:
+                events = self._assert_event_consistency(directory, manifest)
+            yield manifest, events
+
+    def advance_revision(self, manifest: RunRecord, previous_revision: int) -> None:
+        """Stamp a mutation at the caller's established clock boundary."""
+        manifest["revision"] = previous_revision + 1
+        manifest["updated_at"] = self._timestamp()
+
+    def _read_manifest(self, directory: Path, run_id: str) -> RunRecord:
+        path = directory / "run.json"
+        try:
+            raw = path.read_text(encoding="utf-8")
+            value = json.loads(raw)
+        except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+            raise RunCorruptionError(
+                "run manifest is missing, unreadable, or malformed",
+                run_id=run_id,
+                details={"path": str(path), "error": str(exc)},
+            ) from exc
+        if not isinstance(value, dict):
+            raise RunCorruptionError(
+                "run manifest must be a JSON object", run_id=run_id
+            )
+        run_validation.validate_manifest(value, run_id)
+        return value
+
+    def _write_manifest_atomic(
+        self, directory: Path, manifest: RunRecord
+    ) -> None:
+        target = directory / "run.json"
+        self._fault("before-manifest-temporary-write")
+        descriptor, temporary_name = tempfile.mkstemp(
+            dir=directory, prefix=".run.json.", suffix=".tmp"
+        )
+        temporary = Path(temporary_name)
+        try:
+            with os.fdopen(descriptor, "w", encoding="utf-8", newline="\n") as stream:
+                json.dump(
+                    manifest,
+                    stream,
+                    ensure_ascii=False,
+                    allow_nan=False,
+                    sort_keys=True,
+                    indent=2,
+                )
+                stream.write("\n")
+                stream.flush()
+                os.fsync(stream.fileno())
+            self._fault("after-manifest-temporary-write")
+            self._fault("before-manifest-replace")
+            os.replace(temporary, target)
+            self._fsync_directory(directory)
+            self._fault("after-manifest-replace")
+        finally:
+            temporary.unlink(missing_ok=True)
+
+    def _append_event(self, directory: Path, event: EventRecord) -> None:
+        run_validation.validate_event(event, event["run_id"])
+        path = directory / "events.jsonl"
+        payload = (
+            json.dumps(
+                event,
+                ensure_ascii=False,
+                allow_nan=False,
+                sort_keys=True,
+                separators=(",", ":"),
+            )
+            + "\n"
+        ).encode("utf-8")
+        self._fault("before-event-append")
+        try:
+            with path.open("ab") as stream:
+                stream.write(payload)
+                stream.flush()
+                os.fsync(stream.fileno())
+        except OSError as exc:
+            raise RunCorruptionError(
+                "could not append the run audit event",
+                run_id=event["run_id"],
+                details={"path": str(path), "error": str(exc)},
+            ) from exc
+        self._fault("after-event-append")
+
+    def _read_events(self, directory: Path, run_id: str) -> list[EventRecord]:
+        path = directory / "events.jsonl"
+        try:
+            lines = path.read_text(encoding="utf-8").splitlines()
+        except (OSError, UnicodeError) as exc:
+            raise RunCorruptionError(
+                "run event log is missing or unreadable",
+                run_id=run_id,
+                details={"path": str(path), "error": str(exc)},
+            ) from exc
+        events: list[EventRecord] = []
+        for index, line in enumerate(lines, 1):
+            if not line:
+                raise RunCorruptionError(
+                    "run event log contains an empty record",
+                    run_id=run_id,
+                    details={"line": index},
+                )
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError as exc:
+                raise RunCorruptionError(
+                    "run event log contains malformed JSON",
+                    run_id=run_id,
+                    details={"line": index, "error": str(exc)},
+                ) from exc
+            if not isinstance(event, dict):
+                raise RunCorruptionError(
+                    "run event must be a JSON object",
+                    run_id=run_id,
+                    details={"line": index},
+                )
+            run_validation.validate_event(event, run_id)
+            if event["sequence"] != index:
+                raise RunCorruptionError(
+                    "run event sequence is not contiguous",
+                    run_id=run_id,
+                    details={"line": index, "sequence": event["sequence"]},
+                )
+            if event["manifest_revision"] != index:
+                raise RunCorruptionError(
+                    "run event revisions are not contiguous",
+                    run_id=run_id,
+                    details={
+                        "line": index,
+                        "manifest_revision": event["manifest_revision"],
+                    },
+                )
+            events.append(event)
+        return events
+
+    def _ensure_event_consistency(
+        self, directory: Path, manifest: RunRecord
+    ) -> list[EventRecord]:
+        events = self._read_events(directory, manifest["run_id"])
+        if self._events_match_manifest(events, manifest):
+            return events
+        last_revision = events[-1]["manifest_revision"] if events else 0
+        if last_revision == manifest["revision"] - 1:
+            event = self._event(
+                manifest,
+                sequence=len(events) + 1,
+                event_type="recovery",
+                visit_number=manifest["current_visit"],
+                payload={
+                    "reason": "manifest-event-gap",
+                    "previous_sequence": len(events),
+                    "previous_manifest_revision": last_revision,
+                },
+            )
+            self._append_event(directory, event)
+            events.append(event)
+            return events
+        raise RunCorruptionError(
+            "manifest and event log disagree in a way that cannot be recovered",
+            run_id=manifest["run_id"],
+            details={
+                "manifest_revision": manifest["revision"],
+                "last_event_revision": last_revision,
+            },
+        )
+
+    def _assert_event_consistency(
+        self, directory: Path, manifest: RunRecord
+    ) -> list[EventRecord]:
+        events = self._read_events(directory, manifest["run_id"])
+        if not self._events_match_manifest(events, manifest):
+            raise RunCorruptionError(
+                "manifest is newer than its final audit event; recovery is required",
+                run_id=manifest["run_id"],
+                details={"recoverable": True},
+            )
+        return events
+
+    @staticmethod
+    def _events_match_manifest(
+        events: list[EventRecord], manifest: RunRecord
+    ) -> bool:
+        if not events:
+            return False
+        final = events[-1]
+        return (
+            final["manifest_revision"] == manifest["revision"]
+            and final["manifest_hash"] == sha256_json(manifest)
+        )
+
+    def commit_locked(
+        self,
+        directory: Path,
+        manifest: RunRecord,
+        events: list[EventRecord],
+        event_type: str,
+        visit_number: int | None,
+        payload: dict[str, Any],
+    ) -> None:
+        """Replace the manifest then append its event under the caller's lock.
+
+        There is deliberately no lock acquisition or revision stamping here;
+        creation commits revision 1, while mutations stamp at their existing
+        clock boundary. A failure after replacement leaves the permitted gap.
+        """
+        run_id = manifest["run_id"]
+        run_validation.validate_manifest(manifest, run_id)
+        self._write_manifest_atomic(directory, manifest)
+        event = self._event(
+            manifest,
+            sequence=len(events) + 1,
+            event_type=event_type,
+            visit_number=visit_number,
+            payload=payload,
+        )
+        self._append_event(directory, event)
+
+    def _event(
+        self,
+        manifest: RunRecord,
+        *,
+        sequence: int,
+        event_type: str,
+        visit_number: int | None,
+        payload: dict[str, Any],
+    ) -> EventRecord:
+        return {
+            "schema_version": EVENT_SCHEMA_VERSION,
+            "sequence": sequence,
+            "timestamp": self._timestamp(),
+            "run_id": manifest["run_id"],
+            "visit_number": visit_number,
+            "type": event_type,
+            "payload": payload,
+            "manifest_revision": manifest["revision"],
+            "manifest_hash": sha256_json(manifest),
+        }
+
+    @staticmethod
+    def _fsync_directory(path: Path) -> None:
+        descriptor = os.open(path, os.O_RDONLY)
+        try:
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)