specromancy-engine 0.1.3__py3-none-any.whl

specromancy_engine/_runs/visit_transitions.py

@@ -0,0 +1,311 @@
+"""Pure visit decisions over validated records and explicitly collected evidence.
+
+No clocks, artifact reads, locks, revisions, or durable writes belong here.
+These internal helpers preserve the distinct RunStore operation contracts.
+"""
+
+from __future__ import annotations
+
+import copy
+from dataclasses import dataclass, field
+from typing import Any
+
+from .._config.config_models import PipelineConfig
+from ..exit_codes import ExitCode
+from .run_errors import RunCorruptionError, RunStoreError
+from .run_records import (
+    InputArtifactRecord, RunRecord, SealedArtifactRecord, VisitRecord, visit_by_number,
+)
+
+
+def transition_limit_block(
+    manifest: RunRecord,
+    pipeline: PipelineConfig,
+    visit: VisitRecord,
+    outcome: str,
+    transition_target: str | None,
+    *,
+    timestamp: str,
+) -> dict[str, Any] | None:
+    """Return a persisted block record before a disallowed loop traversal."""
+
+    phase = pipeline.phase(visit["phase_id"])
+    transition = next(
+        item for item in phase.transitions if item.outcome == outcome
+    )
+    if transition.max_traversals is not None:
+        traversals = sum(
+            item["phase_id"] == phase.id
+            and item.get("chosen_outcome") == outcome
+            for item in manifest["visits"]
+        )
+        if traversals >= transition.max_traversals:
+            return {
+                "reason": "transition-traversal-limit",
+                "phase_id": phase.id,
+                "visit_number": visit["ordinal"],
+                "outcome": outcome,
+                "target": transition_target,
+                "limit": transition.max_traversals,
+                "recorded_at": timestamp,
+                "required_action": "new-run",
+                "remediation": "start a new run; this pipeline declares no counter-reset approval",
+            }
+    if transition_target is not None:
+        target_phase = pipeline.phase(transition_target)
+        if target_phase.max_visits is not None:
+            visits = sum(
+                item["phase_id"] == transition_target
+                for item in manifest["visits"]
+            )
+            if visits >= target_phase.max_visits:
+                return {
+                    "reason": "phase-visit-limit",
+                    "phase_id": transition_target,
+                    "source_phase": phase.id,
+                    "visit_number": visit["ordinal"],
+                    "outcome": outcome,
+                    "limit": target_phase.max_visits,
+                    "recorded_at": timestamp,
+                    "required_action": "new-run",
+                    "remediation": "start a new run; this pipeline declares no counter-reset approval",
+                }
+    return None
+
+
+@dataclass(frozen=True)
+class Decision:
+    """A detached proposed record and event, or an explicit unchanged result."""
+
+    manifest: RunRecord
+    event_type: str | None = None
+    visit_number: int | None = None
+    payload: dict[str, Any] = field(default_factory=dict)
+
+
+def new_visit(
+    *,
+    phase_id: str,
+    ordinal: int,
+    attempt: int,
+    status: str,
+    inputs: list[InputArtifactRecord],
+    output_path: str,
+    mutation_policy: str,
+    mutation_baseline: Any,
+    skill: SealedArtifactRecord,
+    template: SealedArtifactRecord | None,
+    started_at: str | None,
+    deviations: list[Any] | None = None,
+) -> VisitRecord:
+    """Construct a visit from literal evidence collected at preparation time."""
+
+    if status not in {"pending", "active"}:
+        raise ValueError(f"invalid initial visit status: {status!r}")
+    return copy.deepcopy({
+        "phase_id": phase_id,
+        "ordinal": ordinal,
+        "attempt": attempt,
+        "status": status,
+        "inputs": inputs,
+        "output": {"path": output_path, "sha256": None},
+        "mutation_policy": mutation_policy,
+        "mutation_baseline": mutation_baseline,
+        "mutation_result": None,
+        "validation_checks": [],
+        "command_results": [],
+        "chosen_outcome": None,
+        "transition_target": None,
+        "skill": skill,
+        "template": template,
+        "started_at": started_at,
+        "completed_at": None,
+        "deviations": list(deviations or []),
+    })
+
+
+def append_visit(manifest: RunRecord, visit: VisitRecord) -> Decision:
+    updated = copy.deepcopy(manifest)
+    updated["status"] = "active" if visit["status"] == "active" else "awaiting-agent"
+    updated["current_visit"] = visit["ordinal"]
+    updated["visits"].append(copy.deepcopy(visit))
+    return Decision(
+        updated,
+        "visit-started" if visit["status"] == "active" else "visit-prepared",
+        visit["ordinal"],
+        {"phase_id": visit["phase_id"], "attempt": visit["attempt"]},
+    )
+
+
+def activation_needed(manifest: RunRecord, visit_number: int) -> bool:
+    """Preflight before the store observes the activation clock."""
+
+    if manifest["status"] == "paused":
+        raise RunStoreError(
+            "paused run must be resumed before its next visit can start",
+            diagnostic_code="run-paused",
+            details={"run_id": manifest["run_id"], "visit_number": visit_number},
+            code=ExitCode.RUN_PAUSED,
+        )
+    existing = visit_by_number(manifest, visit_number)
+    if existing["status"] == "active":
+        return False
+    if existing["status"] != "pending":
+        raise RunStoreError(
+            f"visit {visit_number} cannot be activated from {existing['status']}",
+            diagnostic_code="illegal-visit-status",
+            details={"visit_number": visit_number, "status": existing["status"],
+                     "expected": "pending"},
+            code=ExitCode.ILLEGAL_TRANSITION,
+        )
+    return True
+
+
+def activate_visit(
+    manifest: RunRecord, visit_number: int, *,
+    mutation_baseline: Any, started_at: str | None,
+) -> Decision:
+    updated = copy.deepcopy(manifest)
+    if not activation_needed(manifest, visit_number):
+        return Decision(updated)
+    visit = visit_by_number(updated, visit_number)
+    visit["status"] = "active"
+    visit["mutation_baseline"] = copy.deepcopy(mutation_baseline)
+    visit["started_at"] = started_at
+    updated["status"] = "active"
+    return Decision(updated, "visit-activated", visit_number,
+                    {"phase_id": visit["phase_id"]})
+
+
+def require_incomplete(manifest: RunRecord, visit_number: int) -> None:
+    if visit_by_number(manifest, visit_number)["status"] == "completed":
+        raise RunStoreError(
+            f"visit {visit_number} is already completed",
+            diagnostic_code="visit-already-completed",
+            details={"visit_number": visit_number},
+            code=ExitCode.ILLEGAL_TRANSITION,
+        )
+
+
+def transition_needed(
+    manifest: RunRecord, visit_number: int, outcome: str, target: str | None,
+) -> bool:
+    """Check retry/status before reading output or observing clocks."""
+
+    existing = visit_by_number(manifest, visit_number)
+    if existing["status"] == "completed":
+        if (existing["chosen_outcome"] == outcome
+                and existing["transition_target"] == target):
+            return False
+        raise RunStoreError(
+            f"visit {visit_number} already completed with another transition",
+            diagnostic_code="visit-already-completed",
+            details={"visit_number": visit_number},
+            code=ExitCode.ILLEGAL_TRANSITION,
+        )
+    if existing["status"] not in {"active", "awaiting-approval"}:
+        raise RunStoreError(
+            f"visit {visit_number} cannot complete from {existing['status']}",
+            diagnostic_code="illegal-visit-status",
+            details={"visit_number": visit_number, "status": existing["status"]},
+            code=ExitCode.ILLEGAL_TRANSITION,
+        )
+    return True
+
+
+def _record_evidence(
+    manifest: RunRecord, visit: VisitRecord, *, mutation_result: Any,
+    validation_checks: list[Any] | None, command_results: list[Any] | None,
+) -> None:
+    visit["mutation_result"] = copy.deepcopy(mutation_result)
+    visit["validation_checks"] = copy.deepcopy(list(validation_checks or []))
+    visit["command_results"] = copy.deepcopy(list(command_results or []))
+    if isinstance(mutation_result, dict) and isinstance(mutation_result.get("head"), dict):
+        manifest["git"]["head"] = copy.deepcopy(mutation_result["head"])
+
+
+def seal_visit(
+    manifest: RunRecord, visit_number: int, *, output_sha256: str,
+    outcome: str | None, transition_target: str | None, completed_at: str,
+    mutation_result: Any = None, validation_checks: list[Any] | None = None,
+    command_results: list[Any] | None = None, deviations: list[Any] | None = None,
+) -> RunRecord:
+    """Propose a sealed record for completion or successor input resolution.
+
+    This intermediate record is never committed by a graph transition: the
+    store gathers successor evidence under the same lock, then finishes it.
+    """
+
+    require_incomplete(manifest, visit_number)
+    updated = copy.deepcopy(manifest)
+    visit = visit_by_number(updated, visit_number)
+    visit["status"] = "completed"
+    visit["output"]["sha256"] = output_sha256
+    _record_evidence(updated, visit, mutation_result=mutation_result,
+                     validation_checks=validation_checks, command_results=command_results)
+    visit["chosen_outcome"] = outcome
+    visit["transition_target"] = transition_target
+    visit["completed_at"] = completed_at
+    if deviations is not None:
+        visit["deviations"] = copy.deepcopy(list(deviations))
+    return updated
+
+
+def completion_decision(sealed: RunRecord, visit_number: int) -> Decision:
+    visit = visit_by_number(sealed, visit_number)
+    return Decision(copy.deepcopy(sealed), "visit-completed", visit_number,
+                    {"phase_id": visit["phase_id"], "outcome": visit["chosen_outcome"]})
+
+
+def blocked_transition(
+    manifest: RunRecord, visit_number: int, reason: dict[str, Any], *,
+    mutation_result: Any = None, validation_checks: list[Any] | None = None,
+    command_results: list[Any] | None = None,
+) -> Decision:
+    updated = copy.deepcopy(manifest)
+    visit = visit_by_number(updated, visit_number)
+    visit["status"] = "blocked"
+    _record_evidence(updated, visit, mutation_result=mutation_result,
+                     validation_checks=validation_checks, command_results=command_results)
+    updated["status"] = "blocked"
+    updated["block_reason"] = copy.deepcopy(reason)
+    return Decision(updated, "loop-limit-exceeded", visit_number, copy.deepcopy(reason))
+
+
+def finish_transition(
+    sealed: RunRecord, visit_number: int, *, next_visit: VisitRecord | None,
+    pause: bool, terminal_result: Any = None,
+) -> Decision:
+    updated = copy.deepcopy(sealed)
+    visit = visit_by_number(updated, visit_number)
+    if next_visit is None:
+        updated["status"] = "completed"
+        updated["terminal_result"] = copy.deepcopy(
+            terminal_result if terminal_result is not None
+            else {"outcome": visit["chosen_outcome"], "visit_number": visit_number}
+        )
+    else:
+        updated["visits"].append(copy.deepcopy(next_visit))
+        updated["current_visit"] = next_visit["ordinal"]
+        updated["status"] = "paused" if pause else "awaiting-agent"
+    return Decision(updated, "visit-transitioned", visit_number, {
+        "phase_id": visit["phase_id"], "outcome": visit["chosen_outcome"],
+        "target": visit["transition_target"], "paused": pause,
+        "next_visit": next_visit["ordinal"] if next_visit is not None else None,
+    })
+
+
+def resume_paused(manifest: RunRecord) -> Decision:
+    updated = copy.deepcopy(manifest)
+    if manifest["status"] != "paused":
+        return Decision(updated)
+    visit_number = manifest["current_visit"]
+    if visit_number is None:
+        raise RunCorruptionError("paused run has no current visit", run_id=manifest["run_id"])
+    current = visit_by_number(manifest, visit_number)
+    if current["status"] != "pending":
+        raise RunCorruptionError(
+            "paused run does not point to a pending visit", run_id=manifest["run_id"]
+        )
+    updated["status"] = "awaiting-agent"
+    return Decision(updated, "run-resumed", visit_number, {"phase_id": current["phase_id"]})

specromancy_engine/_version.py

@@ -0,0 +1,18 @@
+"""Resolve the version from this source checkout or installed metadata."""
+
+from importlib.metadata import version
+from pathlib import Path
+import tomllib
+
+
+def get_version() -> str:
+    package = Path(__file__).resolve().parent
+    project_file = package.parent.parent / "pyproject.toml"
+    # Only the producer's src layout can supply checkout metadata. Never search
+    # the working directory or prefer an unrelated installed distribution.
+    if package.parent.name == "src" and project_file.is_file():
+        with project_file.open("rb") as stream:
+            project = tomllib.load(stream).get("project", {})
+        if project.get("name") == "specromancy-engine":
+            return project["version"]
+    return version("specromancy-engine")

specromancy_engine/actions.py

@@ -0,0 +1,118 @@
+"""Stable action packets for harness-neutral phase execution."""
+
+from __future__ import annotations
+
+import shlex
+from pathlib import Path
+from typing import Any
+
+from ._config.config_models import PipelineConfig
+from ._runs.run_records import RunRecord, SealedArtifactRecord, VisitRecord
+
+
+ACTION_PACKET_SCHEMA_VERSION = 1
+
+
+def build_action_packet(
+    pipeline: PipelineConfig,
+    manifest: RunRecord,
+    visit: VisitRecord,
+) -> dict[str, Any]:
+    """Return a fully resolved, versioned packet for one visit."""
+
+    phase = pipeline.phase(visit["phase_id"])
+    run_directory = (
+        pipeline.repository_root / ".specromancy" / "runs" / manifest["run_id"]
+    )
+    validate_command = [
+        "specromancy",
+        "--root",
+        str(pipeline.repository_root),
+        "validate",
+        manifest["run_id"],
+        phase.id,
+    ]
+    return {
+        "schema_version": ACTION_PACKET_SCHEMA_VERSION,
+        "run_id": manifest["run_id"],
+        "visit_id": visit["ordinal"],
+        "visit_attempt": visit["attempt"],
+        "visit_status": visit["status"],
+        "phase": phase.id,
+        "skill": _repository_record(pipeline.repository_root, visit["skill"]),
+        "inputs": [
+            {
+                **record,
+                "absolute_path": str(run_directory / record["path"]),
+            }
+            for record in visit["inputs"]
+        ],
+        "output": {
+            **visit["output"],
+            "absolute_path": str(run_directory / visit["output"]["path"]),
+        },
+        "template": (
+            _repository_record(pipeline.repository_root, visit["template"])
+            if visit["template"] is not None
+            else None
+        ),
+        "mutation": {
+            "policy": phase.mutation,
+            "allowlist": list(phase.allowlist),
+        },
+        "completion_criteria": list(phase.completion_criteria),
+        "validation": {
+            "type": phase.validator.type,
+            "required_headings": list(phase.validator.required_headings),
+            "heading_occurrence": phase.validator.heading_occurrence,
+            "schema": phase.validator.declared_path,
+            "commands": [
+                {
+                    "argv": list(command.argv),
+                    "timeout_seconds": command.timeout_seconds,
+                    "required": command.required,
+                }
+                for command in phase.validation_commands
+            ],
+        },
+        "approval_conditions": list(phase.approval_conditions),
+        "stop_conditions": list(phase.stop_conditions),
+        "outcomes": [transition.outcome for transition in phase.transitions],
+        "final_validation_command": validate_command,
+    }
+
+
+def render_action_packet(packet: dict[str, Any]) -> str:
+    """Render a concise terminal representation without losing exact paths."""
+
+    inputs = "\n".join(
+        f"- {item['reference']}: {item['absolute_path']} ({item['sha256']})"
+        for item in packet["inputs"]
+    )
+    criteria = "\n".join(
+        f"- {criterion}" for criterion in packet["completion_criteria"]
+    )
+    mutation = packet["mutation"]["policy"]
+    allowlist = packet["mutation"]["allowlist"]
+    if allowlist:
+        mutation += f" ({', '.join(allowlist)})"
+    return "\n".join(
+        (
+            f"Run: {packet['run_id']}",
+            f"Visit: {packet['visit_id']} ({packet['visit_status']})",
+            f"Phase: {packet['phase']}",
+            f"Skill: {packet['skill']['absolute_path']}",
+            "Inputs:",
+            inputs or "- none",
+            f"Output: {packet['output']['absolute_path']}",
+            f"Mutation: {mutation}",
+            "Completion criteria:",
+            criteria or "- none",
+            "Validate: "
+            + shlex.join(str(part) for part in packet["final_validation_command"]),
+        )
+    )
+
+
+def _repository_record(root: Path, record: SealedArtifactRecord) -> dict[str, Any]:
+    return {**record, "absolute_path": str(root / record["path"])}

specromancy_engine/adapters.py

@@ -0,0 +1,97 @@
+"""Deterministic, safely owned adapters for supported agent harnesses."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from ._adapters.adapter_contracts import (
+    ADAPTER_COMMANDS, ADAPTER_SCHEMA_VERSION, GENERATOR_VERSION, HARNESS_MODES,
+    MANIFEST_PATH, REGENERATION_COMMAND, AdapterCommand, AdapterError,
+)
+from ._adapters.adapter_ownership import _compare, _has_drift, write_adapters
+from ._adapters.adapter_rendering import expected_manifest, render_sources
+from ._adapters.adapter_sources import capture_sources
+from .exit_codes import ExitCode
+from .hashing import canonical_json_bytes
+from .registry import PipelineRegistry
+
+
+def generate_adapters(
+    repository_root: Path,
+    registry: PipelineRegistry,
+    command_metadata: Mapping[str, Any] | None = None,
+    *,
+    check: bool = False,
+) -> dict[str, Any]:
+    """Generate adapters or compare the worktree to deterministic output.
+
+    Omitted metadata is derived from the graphs captured for this invocation.
+    Explicit caller-supplied metadata retains its existing hash contract.
+    """
+
+    root = repository_root.resolve(strict=True)
+    sources = capture_sources(root, registry, command_metadata)
+    rendered = render_sources(sources)
+    manifest = expected_manifest(sources, rendered)
+    manifest_bytes = canonical_json_bytes(manifest) + b"\n"
+
+    if check:
+        drift = _compare(root, rendered, manifest_bytes)
+        if _has_drift(drift):
+            raise AdapterError("generated adapter drift detected", drift)
+        return _result(
+            "generated adapters are up to date",
+            checked=True,
+            paths=tuple(rendered),
+            canonical_source_sha256=manifest["canonical_source"][
+                "sha256"
+            ],
+        )
+
+    removed = write_adapters(root, rendered, manifest_bytes)
+    return _result(
+        f"generated {len(rendered)} harness adapter files",
+        checked=False,
+        paths=tuple(rendered),
+        canonical_source_sha256=manifest["canonical_source"]["sha256"],
+        removed=removed,
+    )
+
+
+def render_adapters(
+    repository_root: Path,
+    registry: PipelineRegistry,
+    command_metadata: Mapping[str, Any],
+) -> dict[str, bytes]:
+    """Render all generated adapter files in stable path order."""
+
+    root = repository_root.resolve(strict=True)
+    sources = capture_sources(
+        root, registry, command_metadata, include_manifest_inputs=False
+    )
+    return render_sources(sources)
+
+
+def _result(
+    message: str,
+    *,
+    checked: bool,
+    paths: tuple[str, ...],
+    canonical_source_sha256: str,
+    removed: tuple[str, ...] = (),
+) -> dict[str, Any]:
+    return {
+        "schema_version": 1,
+        "kind": "adapters",
+        "code": int(ExitCode.SUCCESS),
+        "message": message,
+        "adapters": {
+            "checked": checked,
+            "manifest": MANIFEST_PATH,
+            "canonical_source_sha256": canonical_source_sha256,
+            "paths": list(paths),
+            "removed": list(removed),
+        },
+    }