specromancy-engine 0.1.3__py3-none-any.whl

specromancy_engine/exit_codes.py

@@ -0,0 +1,53 @@
+"""Stable process exit codes for the public CLI contract."""
+
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    """Exit status returned by a Specromancy command."""
+
+    SUCCESS = 0
+    USAGE_ERROR = 2
+    INVALID_PIPELINE = 3
+    NOT_FOUND = 4
+    ILLEGAL_TRANSITION = 5
+    VALIDATION_FAILED = 6
+    APPROVAL_REQUIRED = 7
+    AGENT_ACTION_REQUIRED = 8
+    RUN_BLOCKED = 9
+    LOCK_HELD = 10
+    ADAPTER_DRIFT = 11
+    INTERNAL_ERROR = 12
+    RUN_PAUSED = 13
+
+
+EXIT_CODE_DESCRIPTIONS = {
+    ExitCode.SUCCESS: "Command completed successfully",
+    ExitCode.USAGE_ERROR: "CLI usage error",
+    ExitCode.INVALID_PIPELINE: "Invalid pipeline configuration",
+    ExitCode.NOT_FOUND: "Run or artifact not found",
+    ExitCode.ILLEGAL_TRANSITION: "Illegal state transition",
+    ExitCode.VALIDATION_FAILED: "Validation failed",
+    ExitCode.APPROVAL_REQUIRED: "Approval required",
+    ExitCode.AGENT_ACTION_REQUIRED: "Agent action required",
+    ExitCode.RUN_BLOCKED: "Run blocked or stopped",
+    ExitCode.LOCK_HELD: "Concurrent run lock held",
+    ExitCode.ADAPTER_DRIFT: "Adapter drift detected",
+    ExitCode.INTERNAL_ERROR: "Internal or corrupt-state error",
+    ExitCode.RUN_PAUSED: "Run paused at a configured checkpoint",
+}
+
+# Named integer constants are kept for callers that do not want to import the enum.
+SUCCESS = int(ExitCode.SUCCESS)
+USAGE_ERROR = int(ExitCode.USAGE_ERROR)
+INVALID_PIPELINE = int(ExitCode.INVALID_PIPELINE)
+NOT_FOUND = int(ExitCode.NOT_FOUND)
+ILLEGAL_TRANSITION = int(ExitCode.ILLEGAL_TRANSITION)
+VALIDATION_FAILED = int(ExitCode.VALIDATION_FAILED)
+APPROVAL_REQUIRED = int(ExitCode.APPROVAL_REQUIRED)
+AGENT_ACTION_REQUIRED = int(ExitCode.AGENT_ACTION_REQUIRED)
+RUN_BLOCKED = int(ExitCode.RUN_BLOCKED)
+LOCK_HELD = int(ExitCode.LOCK_HELD)
+ADAPTER_DRIFT = int(ExitCode.ADAPTER_DRIFT)
+INTERNAL_ERROR = int(ExitCode.INTERNAL_ERROR)
+RUN_PAUSED = int(ExitCode.RUN_PAUSED)

specromancy_engine/git.py

@@ -0,0 +1,264 @@
+"""Content-level Git repository snapshots and mutation-policy checks."""
+
+from __future__ import annotations
+
+import fnmatch
+import hashlib
+import os
+import stat
+import subprocess
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+
+class GitError(RuntimeError):
+    """Git metadata cannot be captured under the pipeline's policy."""
+
+    def __init__(self, diagnostic_code: str, message: str, **details: Any) -> None:
+        super().__init__(message)
+        self.diagnostic_code = diagnostic_code
+        self.message = message
+        self.details = details
+
+
+def capture_repository_snapshot(
+    root: Path, *, allow_non_git: bool = False
+) -> dict[str, Any]:
+    """Capture HEAD, branch, and content/mode for tracked and visible files."""
+
+    root = root.resolve(strict=True)
+    try:
+        inside = _git(root, "rev-parse", "--is-inside-work-tree", text=True)
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        if allow_non_git:
+            return _non_git_snapshot(root)
+        raise GitError("git-unavailable", "Git is unavailable", error=str(exc)) from exc
+    if inside.returncode != 0 or inside.stdout.strip() != "true":
+        if allow_non_git:
+            return _non_git_snapshot(root)
+        raise GitError(
+            "git-worktree-required",
+            "the pipeline requires a Git worktree",
+            stderr=inside.stderr.strip(),
+        )
+
+    try:
+        head_result = _git(root, "rev-parse", "HEAD", text=True)
+        branch_result = _git(
+            root, "symbolic-ref", "--quiet", "--short", "HEAD", text=True
+        )
+        listed = _git(
+            root, "ls-files", "-co", "--exclude-standard", "-z", text=False
+        )
+        index = _git(root, "ls-files", "--stage", "-z", text=False)
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise GitError(
+            "git-snapshot-failed", "Git metadata capture failed", error=str(exc)
+        ) from exc
+    if listed.returncode != 0:
+        raise GitError(
+            "git-snapshot-failed",
+            "Git could not enumerate repository files",
+            stderr=listed.stderr.decode("utf-8", "replace").strip(),
+        )
+    if index.returncode != 0:
+        raise GitError(
+            "git-snapshot-failed",
+            "Git could not inspect the repository index",
+            stderr=index.stderr.decode("utf-8", "replace").strip(),
+        )
+    files: dict[str, dict[str, Any]] = {}
+    for raw in listed.stdout.split(b"\0"):
+        if not raw:
+            continue
+        path = os.fsdecode(raw)
+        normalized = PurePosixPath(path).as_posix()
+        if normalized == ".git" or normalized.startswith(".git/"):
+            continue
+        if normalized == ".specromancy" or normalized.startswith(".specromancy/"):
+            continue
+        if not os.path.lexists(root / normalized):
+            # Deleted tracked files are represented by their absence and are
+            # therefore discovered by snapshot comparison.
+            continue
+        files[normalized] = _path_record(root, normalized)
+    return {
+        "is_worktree": True,
+        "head": head_result.stdout.strip() if head_result.returncode == 0 else None,
+        "branch": branch_result.stdout.strip() if branch_result.returncode == 0 else None,
+        "index_sha256": hashlib.sha256(index.stdout).hexdigest(),
+        "files": dict(sorted(files.items())),
+    }
+
+
+def compare_snapshots(
+    before: dict[str, Any], after: dict[str, Any]
+) -> dict[str, Any]:
+    """Return added/changed/deleted/mode/rename details for two snapshots."""
+
+    old = before.get("files", {})
+    new = after.get("files", {})
+    old_paths = set(old)
+    new_paths = set(new)
+    added = set(new_paths - old_paths)
+    deleted = set(old_paths - new_paths)
+    changed: set[str] = set()
+    mode_changed: set[str] = set()
+    for path in old_paths & new_paths:
+        if old[path].get("sha256") != new[path].get("sha256") or old[path].get(
+            "kind"
+        ) != new[path].get("kind"):
+            changed.add(path)
+        elif old[path].get("mode") != new[path].get("mode"):
+            mode_changed.add(path)
+
+    renames: list[dict[str, str]] = []
+    for source in sorted(tuple(deleted)):
+        source_record = old[source]
+        destination = next(
+            (
+                candidate
+                for candidate in sorted(added)
+                if new[candidate].get("sha256") == source_record.get("sha256")
+                and new[candidate].get("kind") == source_record.get("kind")
+            ),
+            None,
+        )
+        if destination is not None:
+            deleted.remove(source)
+            added.remove(destination)
+            renames.append({"from": source, "to": destination})
+    paths = set(added) | set(deleted) | changed | mode_changed
+    for rename in renames:
+        paths.update(rename.values())
+    metadata_changed = [
+        name
+        for name in ("head", "branch", "index_sha256")
+        if before.get(name) != after.get(name)
+    ]
+    return {
+        "added": sorted(added),
+        "changed": sorted(changed),
+        "deleted": sorted(deleted),
+        "mode_changed": sorted(mode_changed),
+        "renamed": renames,
+        "paths": sorted(paths),
+        "metadata_changed": metadata_changed,
+        "before_head": before.get("head"),
+        "after_head": after.get("head"),
+    }
+
+
+def enforce_mutation_policy(
+    before: dict[str, Any],
+    after: dict[str, Any],
+    policy: str,
+    allowlist: tuple[str, ...] | list[str] = (),
+) -> dict[str, Any]:
+    """Compare snapshots and raise when changed paths violate the policy."""
+
+    comparison = compare_snapshots(before, after)
+    comparison["policy"] = policy
+    comparison["status"] = "passed"
+    comparison["head"] = {
+        "is_worktree": after.get("is_worktree", False),
+        "head": after.get("head"),
+        "branch": after.get("branch"),
+    }
+    metadata_violations = [
+        f"@git/{name.removesuffix('_sha256')}"
+        for name in comparison["metadata_changed"]
+    ]
+    violations: list[str] = []
+    if policy == "read-only":
+        violations = [*comparison["paths"], *metadata_violations]
+    elif policy == "allowlist":
+        violations = [
+            path
+            for path in comparison["paths"]
+            if not any(_glob_matches(path, pattern) for pattern in allowlist)
+        ] + metadata_violations
+    elif policy != "repository-write":
+        raise ValueError(f"unsupported mutation policy: {policy!r}")
+    if violations:
+        comparison["status"] = "failed"
+        comparison["violations"] = violations
+        raise GitError(
+            "mutation-policy-violation",
+            f"repository changes violate the {policy!r} mutation policy",
+            mutation_result=comparison,
+            paths=violations,
+        )
+    comparison["violations"] = []
+    return comparison
+
+
+def _path_record(root: Path, relative: str) -> dict[str, Any]:
+    path = root / relative
+    try:
+        metadata = path.lstat()
+    except OSError as exc:
+        raise GitError(
+            "git-snapshot-failed", "an enumerated path cannot be inspected", path=relative
+        ) from exc
+    mode = stat.S_IMODE(metadata.st_mode)
+    if stat.S_ISLNK(metadata.st_mode):
+        target = os.readlink(path)
+        content = os.fsencode(target)
+        kind = "symlink"
+    elif stat.S_ISREG(metadata.st_mode):
+        try:
+            content = path.read_bytes()
+        except OSError as exc:
+            raise GitError(
+                "git-snapshot-failed", "an enumerated file cannot be read", path=relative
+            ) from exc
+        kind = "file"
+    else:
+        raise GitError(
+            "git-snapshot-failed",
+            "an enumerated path is neither a regular file nor a symlink",
+            path=relative,
+        )
+    return {"sha256": hashlib.sha256(content).hexdigest(), "mode": mode, "kind": kind}
+
+
+def _git(root: Path, *arguments: str, text: bool) -> subprocess.CompletedProcess[Any]:
+    return subprocess.run(
+        ["git", "-C", str(root), *arguments],
+        check=False,
+        capture_output=True,
+        text=text,
+        timeout=15,
+    )
+
+
+def _non_git_snapshot(root: Path) -> dict[str, Any]:
+    files: dict[str, dict[str, Any]] = {}
+    for path in sorted(root.rglob("*")):
+        relative = path.relative_to(root).as_posix()
+        if relative == ".git" or relative.startswith(".git/"):
+            continue
+        if relative == ".specromancy" or relative.startswith(".specromancy/"):
+            continue
+        if path.is_symlink() or path.is_file():
+            files[relative] = _path_record(root, relative)
+    return {
+        "is_worktree": False,
+        "head": None,
+        "branch": None,
+        "index_sha256": None,
+        "files": files,
+    }
+
+
+def _glob_matches(path: str, pattern: str) -> bool:
+    if fnmatch.fnmatchcase(path, pattern):
+        return True
+    if pattern.endswith("/**") and path == pattern[:-3].rstrip("/"):
+        return True
+    return False
+
+
+# A concise public alias matches the terminology used in action records.
+snapshot_repository = capture_repository_snapshot

specromancy_engine/graph.py

@@ -0,0 +1,321 @@
+"""Generic directed-graph validation for configured pipelines."""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Callable, Iterable, Sequence
+from typing import Any
+
+
+GraphFailure = Callable[..., None]
+
+
+def reachable_from(start: str, edges: dict[str, set[str]]) -> frozenset[str]:
+    """Return all vertices reachable from *start*, including *start*."""
+
+    seen: set[str] = set()
+    pending = [start]
+    while pending:
+        current = pending.pop()
+        if current in seen:
+            continue
+        seen.add(current)
+        pending.extend(edges.get(current, set()) - seen)
+    return frozenset(seen)
+
+
+def strongly_connected_components(
+    vertices: Iterable[str], edges: dict[str, set[str]]
+) -> tuple[frozenset[str], ...]:
+    """Return Tarjan strongly connected components in deterministic order."""
+
+    index = 0
+    indices: dict[str, int] = {}
+    lowlinks: dict[str, int] = {}
+    stack: list[str] = []
+    on_stack: set[str] = set()
+    components: list[frozenset[str]] = []
+
+    def visit(vertex: str) -> None:
+        nonlocal index
+        indices[vertex] = index
+        lowlinks[vertex] = index
+        index += 1
+        stack.append(vertex)
+        on_stack.add(vertex)
+
+        for target in sorted(edges.get(vertex, set())):
+            if target not in indices:
+                visit(target)
+                lowlinks[vertex] = min(lowlinks[vertex], lowlinks[target])
+            elif target in on_stack:
+                lowlinks[vertex] = min(lowlinks[vertex], indices[target])
+
+        if lowlinks[vertex] == indices[vertex]:
+            component: set[str] = set()
+            while True:
+                member = stack.pop()
+                on_stack.remove(member)
+                component.add(member)
+                if member == vertex:
+                    break
+            components.append(frozenset(component))
+
+    for vertex in sorted(vertices):
+        if vertex not in indices:
+            visit(vertex)
+    return tuple(components)
+
+
+def _cyclic_components(
+    vertices: Iterable[str], edges: dict[str, set[str]]
+) -> tuple[frozenset[str], ...]:
+    return tuple(
+        component
+        for component in strongly_connected_components(vertices, edges)
+        if len(component) > 1
+        or any(vertex in edges.get(vertex, set()) for vertex in component)
+    )
+
+
+def _producer_is_guaranteed(
+    start: str,
+    consumer: str,
+    producer: str,
+    edges: dict[str, set[str]],
+) -> bool:
+    """Whether every first route completes *producer* before *consumer*."""
+
+    # Search for a counterexample route while treating arrival at the producer
+    # as completion only when traversing an edge away from it. An immediate
+    # arrival at a consumer cannot consume that visit's not-yet-written output.
+    pending = [start]
+    seen: set[str] = set()
+    while pending:
+        current = pending.pop()
+        if current in seen:
+            continue
+        seen.add(current)
+        if current == consumer:
+            return False
+        if current == producer:
+            continue
+        pending.extend(edges.get(current, set()))
+    return True
+
+
+def _visit_is_guaranteed(
+    start: str, consumer: str, ordinal: int, edges: dict[str, set[str]]
+) -> bool:
+    """Whether at least *ordinal* outputs exist on every route to *consumer*."""
+
+    pending = deque([(start, 0)])
+    seen: set[str] = set()
+    while pending:
+        current, completed = pending.popleft()
+        if current in seen:
+            continue
+        seen.add(current)
+        if current == consumer:
+            return completed >= ordinal
+        after_current = completed + 1
+        pending.extend(
+            (target, after_current)
+            for target in sorted(edges.get(current, set()))
+        )
+    return True
+
+
+def validate_graph(
+    phases: Sequence[Any],
+    start: str,
+    terminal_outcomes: frozenset[str] | set[str],
+    fail: GraphFailure,
+) -> None:
+    """Validate phase connectivity, bounded cycles, and input producers.
+
+    ``fail`` is supplied by the configuration layer so this module remains
+    independent of diagnostic and domain-model implementation details.
+    """
+
+    phase_by_id: dict[str, Any] = {}
+    for phase in phases:
+        if phase.id in phase_by_id:
+            fail(
+                "duplicate-phase",
+                f"phase id {phase.id!r} is declared more than once",
+                phase=phase.id,
+                field="id",
+                value=phase.id,
+                remediation="give every phase a unique id",
+            )
+        phase_by_id[phase.id] = phase
+
+    if start not in phase_by_id:
+        fail(
+            "missing-start-phase",
+            f"start phase {start!r} is not declared",
+            field="start",
+            value=start,
+            remediation="set start to the id of a declared phase",
+        )
+
+    edges: dict[str, set[str]] = {phase.id: set() for phase in phases}
+    bounded_edges: set[tuple[str, str]] = set()
+    unbounded_edges: set[tuple[str, str]] = set()
+    for phase in phases:
+        seen_outcomes: set[str] = set()
+        if not phase.transitions:
+            fail(
+                "missing-transition",
+                f"phase {phase.id!r} has no possible outcome",
+                phase=phase.id,
+                field="transitions",
+                value=[],
+                remediation="declare at least one phase or terminal transition",
+            )
+        for transition in phase.transitions:
+            if transition.outcome in seen_outcomes:
+                fail(
+                    "duplicate-outcome",
+                    f"phase {phase.id!r} declares outcome {transition.outcome!r} more than once",
+                    phase=phase.id,
+                    field="transitions.outcome",
+                    value=transition.outcome,
+                    remediation="make transition outcomes unique within the phase",
+                )
+            seen_outcomes.add(transition.outcome)
+            is_terminal = transition.outcome in terminal_outcomes
+            if is_terminal:
+                if transition.pause:
+                    fail(
+                        "terminal-transition-pause",
+                        f"terminal outcome {transition.outcome!r} cannot pause",
+                        phase=phase.id,
+                        field="transitions.pause",
+                        value=True,
+                        remediation="remove pause or target a non-terminal phase",
+                    )
+                if transition.target is not None:
+                    fail(
+                        "terminal-outcome-target",
+                        f"terminal outcome {transition.outcome!r} cannot target a phase",
+                        phase=phase.id,
+                        field="transitions.target",
+                        value=transition.target,
+                        remediation="remove target from the terminal transition",
+                    )
+                continue
+            if transition.target is None:
+                fail(
+                    "missing-transition-target",
+                    f"non-terminal outcome {transition.outcome!r} needs a target",
+                    phase=phase.id,
+                    field="transitions.target",
+                    value=None,
+                    remediation="name a declared phase or use a terminal outcome",
+                )
+            if transition.target not in phase_by_id:
+                fail(
+                    "unknown-transition-target",
+                    f"outcome {transition.outcome!r} targets unknown phase {transition.target!r}",
+                    phase=phase.id,
+                    field="transitions.target",
+                    value=transition.target,
+                    remediation="target a declared phase",
+                )
+            edges[phase.id].add(transition.target)
+            if transition.max_traversals is not None:
+                bounded_edges.add((phase.id, transition.target))
+            else:
+                unbounded_edges.add((phase.id, transition.target))
+
+    # Parallel outcomes are distinct runtime edges. Collapsing them for graph
+    # traversal is safe only when every outcome between the pair is bounded.
+    bounded_edges -= unbounded_edges
+
+    reachable = reachable_from(start, edges)
+    unreachable = sorted(set(phase_by_id) - reachable)
+    if unreachable:
+        fail(
+            "unreachable-phase",
+            f"phases are unreachable from {start!r}: {', '.join(unreachable)}",
+            field="phases",
+            value=unreachable,
+            remediation="add transitions from the reachable graph or remove the phases",
+        )
+
+    # A collection of bounds is mechanically sufficient only if removing the
+    # bounded phases and edges leaves no cycle. This is stronger than merely
+    # finding one bound somewhere in a large strongly connected component.
+    unbounded_vertices = {
+        phase.id for phase in phases if phase.max_visits is None
+    }
+    unbounded_edges = {
+        source: {
+            target
+            for target in targets
+            if target in unbounded_vertices
+            and (source, target) not in bounded_edges
+        }
+        for source, targets in edges.items()
+        if source in unbounded_vertices
+    }
+    unbounded_cycles = _cyclic_components(unbounded_vertices, unbounded_edges)
+    if unbounded_cycles:
+        members = sorted(set().union(*unbounded_cycles))
+        fail(
+            "unbounded-cycle",
+            f"cycle has no finite visit or traversal bound: {', '.join(members)}",
+            field="phases.transitions",
+            value=members,
+            remediation="set max_visits on a phase or max_traversals on an edge in every cycle",
+        )
+
+    for phase in phases:
+        for reference in phase.inputs:
+            if reference == "request":
+                continue
+            if reference.startswith("visit:"):
+                ordinal = int(reference.removeprefix("visit:"))
+                if not _visit_is_guaranteed(start, phase.id, ordinal, edges):
+                    fail(
+                        "unavailable-input",
+                        f"input {reference!r} cannot exist before phase {phase.id!r}",
+                        phase=phase.id,
+                        field="inputs",
+                        value=reference,
+                        remediation="reference an earlier visit or change the incoming graph",
+                    )
+                continue
+            if not reference.startswith("latest:"):
+                fail(
+                    "invalid-input-reference",
+                    f"phase {phase.id!r} has invalid input reference {reference!r}",
+                    phase=phase.id,
+                    field="inputs",
+                    value=reference,
+                    remediation="use request, latest:<phase>, or visit:<positive-number>",
+                )
+            producer = reference.removeprefix("latest:")
+            if producer not in phase_by_id:
+                fail(
+                    "unknown-input-producer",
+                    f"input {reference!r} names unknown phase {producer!r}",
+                    phase=phase.id,
+                    field="inputs",
+                    value=reference,
+                    remediation="name a phase that can produce an earlier artifact",
+                )
+            if not _producer_is_guaranteed(start, phase.id, producer, edges):
+                fail(
+                    "unavailable-input",
+                    f"input {reference!r} is not produced on every route to phase {phase.id!r}",
+                    phase=phase.id,
+                    field="inputs",
+                    value=reference,
+                    remediation=(
+                        "make the producer precede every incoming route or "
+                        "remove the input"
+                    ),
+                )