continuous-refactoring 0.1.0__py3-none-any.whl

continuous_refactoring/migration_manifest_codec.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from typing import cast
+
+from continuous_refactoring.artifacts import ContinuousRefactorError
+from continuous_refactoring.effort import EffortTier, require_effort_tier
+from continuous_refactoring.migrations import (
+    MIGRATION_STATUSES,
+    MigrationManifest,
+    MigrationStatus,
+    PhaseSpec,
+)
+
+__all__ = ("decode_manifest_payload", "encode_manifest_payload")
+
+_VALID_STATUSES: frozenset[str] = frozenset(
+    cast(tuple[str, ...], MIGRATION_STATUSES)
+)
+
+
+def _require_status(raw_status: object) -> MigrationStatus:
+    if not isinstance(raw_status, str):
+        raise ContinuousRefactorError(
+            f"Migration status must be a string: {raw_status!r}"
+        )
+    if raw_status not in _VALID_STATUSES:
+        raise ContinuousRefactorError(f"Unknown migration status: {raw_status!r}")
+    return cast(MigrationStatus, raw_status)
+
+
+def _require_mapping(value: object, *, field: str) -> dict[str, object]:
+    if not isinstance(value, dict):
+        raise ContinuousRefactorError(
+            f"Migration field {field!r} must be an object: {value!r}"
+        )
+    return value
+
+
+def _require_str(value: object, *, field: str) -> str:
+    if not isinstance(value, str):
+        raise ContinuousRefactorError(
+            f"Migration field {field!r} must be a string: {value!r}"
+        )
+    return value
+
+
+def _optional_str(value: object, *, field: str) -> str | None:
+    if value is None:
+        return None
+    return _require_str(value, field=field)
+
+
+def _require_bool(value: object, *, field: str) -> bool:
+    if not isinstance(value, bool):
+        raise ContinuousRefactorError(
+            f"Migration field {field!r} must be a boolean: {value!r}"
+        )
+    return value
+
+
+def _require_unique_phase_names(phases: tuple[PhaseSpec, ...]) -> None:
+    seen: set[str] = set()
+    duplicates: list[str] = []
+    for phase in phases:
+        if phase.name in seen:
+            duplicates.append(phase.name)
+            continue
+        seen.add(phase.name)
+    if duplicates:
+        repeated = ", ".join(sorted(set(duplicates)))
+        raise ContinuousRefactorError(
+            f"Duplicate phase names are not allowed: {repeated}"
+        )
+
+
+def _require_phase_precondition(phase: dict[str, object], *, prefix: str) -> str:
+    if "precondition" in phase:
+        return _require_str(phase.get("precondition"), field=f"{prefix}.precondition")
+    if "ready_when" in phase:
+        return _require_str(phase.get("ready_when"), field=f"{prefix}.ready_when")
+    raise ContinuousRefactorError(
+        f"Migration field {prefix!r} must include 'precondition' "
+        "(or legacy 'ready_when')"
+    )
+
+
+def _require_phase(raw_phase: object, *, index: int) -> PhaseSpec:
+    phase = _require_mapping(raw_phase, field=f"phases[{index}]")
+    prefix = f"phases[{index}]"
+    required_effort_raw = phase.get("required_effort")
+    required_effort: EffortTier | None = None
+    if required_effort_raw is not None:
+        required_effort = require_effort_tier(
+            required_effort_raw,
+            field=f"{prefix}.required_effort",
+        )
+    return PhaseSpec(
+        name=_require_str(phase.get("name"), field=f"{prefix}.name"),
+        file=_require_str(phase.get("file"), field=f"{prefix}.file"),
+        done=_require_bool(phase.get("done"), field=f"{prefix}.done"),
+        precondition=_require_phase_precondition(phase, prefix=prefix),
+        required_effort=required_effort,
+        effort_reason=_optional_str(
+            phase.get("effort_reason"), field=f"{prefix}.effort_reason"
+        ),
+    )
+
+
+def _require_phases(raw_phases: object) -> tuple[PhaseSpec, ...]:
+    if raw_phases is None:
+        return ()
+    if not isinstance(raw_phases, list):
+        raise ContinuousRefactorError(
+            f"Migration field 'phases' must be a list: {raw_phases!r}"
+        )
+    phases = tuple(
+        _require_phase(raw_phase, index=index)
+        for index, raw_phase in enumerate(raw_phases)
+    )
+    _require_unique_phase_names(phases)
+    return phases
+
+
+def _legacy_current_phase_name(
+    legacy_cursor: int, phases: tuple[PhaseSpec, ...],
+) -> str:
+    if not phases:
+        return ""
+    if 0 <= legacy_cursor < len(phases):
+        return phases[legacy_cursor].name
+    return ""
+
+
+def _require_current_phase(value: object, *, phases: tuple[PhaseSpec, ...]) -> str:
+    if isinstance(value, bool):
+        raise ContinuousRefactorError(
+            f"Migration field 'current_phase' must be a string or legacy int: {value!r}"
+        )
+    if isinstance(value, str):
+        if value == "":
+            return ""
+        if not any(phase.name == value for phase in phases):
+            raise ContinuousRefactorError(
+                f"Migration field 'current_phase' names an unknown phase: {value!r}"
+            )
+        return value
+    if isinstance(value, int):
+        return _legacy_current_phase_name(value, phases)
+    raise ContinuousRefactorError(
+        f"Migration field 'current_phase' must be a string or legacy int: {value!r}"
+    )
+
+
+def decode_manifest_payload(raw_payload: object) -> MigrationManifest:
+    raw = _require_mapping(raw_payload, field="manifest")
+    phases = _require_phases(raw.get("phases"))
+    return MigrationManifest(
+        name=_require_str(raw.get("name"), field="name"),
+        created_at=_require_str(raw.get("created_at"), field="created_at"),
+        last_touch=_require_str(raw.get("last_touch"), field="last_touch"),
+        wake_up_on=_optional_str(raw.get("wake_up_on"), field="wake_up_on"),
+        awaiting_human_review=_require_bool(
+            raw.get("awaiting_human_review", False), field="awaiting_human_review"
+        ),
+        status=_require_status(raw.get("status")),
+        current_phase=_require_current_phase(
+            raw.get("current_phase"), phases=phases,
+        ),
+        phases=phases,
+        human_review_reason=_optional_str(
+            raw.get("human_review_reason"), field="human_review_reason"
+        ),
+        cooldown_until=_optional_str(
+            raw.get("cooldown_until"), field="cooldown_until"
+        ),
+    )
+
+
+def encode_manifest_payload(manifest: MigrationManifest) -> str:
+    _require_status(manifest.status)
+    _require_unique_phase_names(manifest.phases)
+    if manifest.current_phase and not any(
+        phase.name == manifest.current_phase for phase in manifest.phases
+    ):
+        raise ContinuousRefactorError(
+            f"Cannot save manifest with unknown current phase {manifest.current_phase!r}"
+        )
+    return json.dumps(asdict(manifest), indent=2, sort_keys=True) + "\n"

continuous_refactoring/migration_tick.py

@@ -0,0 +1,468 @@
+"""Migration tick orchestration."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from continuous_refactoring.artifacts import RunArtifacts
+    from continuous_refactoring.migrations import MigrationManifest, PhaseSpec
+    from continuous_refactoring.phases import ExecutePhaseOutcome
+
+__all__ = [
+    "enumerate_eligible_manifests",
+    "try_migration_tick",
+]
+
+from continuous_refactoring.artifacts import ContinuousRefactorError
+from continuous_refactoring.commit_messages import build_commit_message
+from continuous_refactoring.decisions import (
+    DecisionRecord,
+    RouteOutcome,
+    error_failure_kind,
+    sanitize_text,
+)
+from continuous_refactoring.effort import (
+    EffortBudget,
+    effort_exceeds,
+    resolve_effort_budget,
+    resolve_phase_effort,
+)
+from continuous_refactoring.git import get_head_sha
+from continuous_refactoring.migrations import (
+    bump_last_touch,
+    eligible_now,
+    has_executable_phase,
+    load_manifest,
+    phase_file_reference,
+    resolve_current_phase,
+    save_manifest,
+)
+from continuous_refactoring.phases import (
+    ReadyVerdict,
+    check_phase_ready,
+    execute_phase,
+)
+
+
+_BASELINE_VALIDATION_UNCERTAINTY_PHRASES = (
+    "baseline green",
+    "baseline validation",
+    "current tests pass",
+    "fresh test evidence",
+    "fresh validation evidence",
+    "full test suite passes",
+    "tests pass now",
+)
+
+
+class _FinalizeCommit(Protocol):
+    def __call__(
+        self,
+        repo_root: Path,
+        head_before: str,
+        commit_message: str,
+        *,
+        artifacts: RunArtifacts,
+        attempt: int,
+        phase: str,
+    ) -> str | None:
+        ...
+
+
+def enumerate_eligible_manifests(
+    live_dir: Path,
+    now: datetime,
+    effort_budget: EffortBudget | None = None,
+) -> list[tuple[MigrationManifest, Path]]:
+    if not live_dir.is_dir():
+        return []
+    candidates: list[tuple[MigrationManifest, Path]] = []
+    for entry in sorted(live_dir.iterdir()):
+        if not entry.is_dir() or entry.name.startswith("__"):
+            continue
+        manifest_path = entry / "manifest.json"
+        if not manifest_path.exists():
+            continue
+        manifest = load_manifest(manifest_path)
+        if manifest.status not in ("ready", "in-progress"):
+            continue
+        if manifest.awaiting_human_review:
+            continue
+        if not has_executable_phase(manifest):
+            continue
+        if not eligible_now(manifest, now):
+            continue
+        candidates.append((manifest, manifest_path))
+    if effort_budget is not None:
+        seen_paths = {path for _, path in candidates}
+        for manifest, manifest_path in _cooling_effort_candidates(
+            live_dir, now, effort_budget,
+        ):
+            if manifest_path not in seen_paths:
+                candidates.append((manifest, manifest_path))
+    candidates.sort(key=lambda pair: datetime.fromisoformat(pair[0].created_at))
+    return candidates
+
+
+def _cooling_effort_candidates(
+    live_dir: Path,
+    now: datetime,
+    budget: EffortBudget,
+) -> list[tuple[MigrationManifest, Path]]:
+    if not live_dir.is_dir():
+        return []
+    candidates: list[tuple[MigrationManifest, Path]] = []
+    for entry in sorted(live_dir.iterdir()):
+        if not entry.is_dir() or entry.name.startswith("__"):
+            continue
+        manifest_path = entry / "manifest.json"
+        if not manifest_path.exists():
+            continue
+        manifest = load_manifest(manifest_path)
+        if not _can_ignore_effort_cooldown(manifest, now, budget):
+            continue
+        candidates.append((manifest, manifest_path))
+    return candidates
+
+
+def _can_ignore_effort_cooldown(
+    manifest: MigrationManifest,
+    now: datetime,
+    budget: EffortBudget,
+) -> bool:
+    if manifest.status not in ("ready", "in-progress"):
+        return False
+    if manifest.awaiting_human_review or not has_executable_phase(manifest):
+        return False
+    if manifest.cooldown_until is None:
+        return False
+    if datetime.fromisoformat(manifest.cooldown_until) <= now:
+        return False
+    phase = resolve_current_phase(manifest)
+    return (
+        phase.required_effort is not None
+        and not effort_exceeds(phase.required_effort, budget.max_allowed_effort)
+    )
+
+
+def try_migration_tick(
+    live_dir: Path,
+    taste: str,
+    repo_root: Path,
+    artifacts: RunArtifacts,
+    *,
+    agent: str,
+    model: str,
+    effort: str,
+    timeout: int | None,
+    commit_message_prefix: str,
+    validation_command: str,
+    max_attempts: int | None,
+    attempt: int,
+    finalize_commit: _FinalizeCommit,
+    effort_budget: EffortBudget | None = None,
+) -> tuple[RouteOutcome, DecisionRecord | None]:
+    resolved_budget = effort_budget or resolve_effort_budget(effort, None)
+    now = datetime.now(timezone.utc)
+    candidates = enumerate_eligible_manifests(live_dir, now, resolved_budget)
+    deferred_record: DecisionRecord | None = None
+    pending_defers: list[tuple[MigrationManifest, Path]] = []
+
+    for manifest, manifest_path in candidates:
+        phase = resolve_current_phase(manifest)
+        target_label = _target_label(manifest, phase)
+        if (
+            phase.required_effort is not None
+            and effort_exceeds(
+                phase.required_effort,
+                resolved_budget.max_allowed_effort,
+            )
+        ):
+            reason = _effort_defer_reason(
+                phase,
+                max_allowed_effort=resolved_budget.max_allowed_effort,
+            )
+            _log_phase_effort_deferred(
+                artifacts,
+                target_label,
+                phase,
+                reason,
+                max_allowed_effort=resolved_budget.max_allowed_effort,
+            )
+            pending_defers.append(
+                (
+                    _defer_manifest(
+                        manifest,
+                        now,
+                        verdict="effort-over-budget",
+                        reason=reason,
+                    ),
+                    manifest_path,
+                )
+            )
+            deferred_record = _effort_deferred_record(reason, repo_root, target_label)
+            continue
+
+        phase_resolution = resolve_phase_effort(
+            resolved_budget,
+            phase.required_effort,
+            reason=phase.effort_reason,
+        )
+        phase_effort = phase_resolution.effective_effort
+        effort_metadata = phase_resolution.event_fields()
+        try:
+            verdict, reason = check_phase_ready(
+                phase,
+                manifest,
+                repo_root,
+                artifacts,
+                taste=taste,
+                attempt=attempt,
+                retry=1,
+                agent=agent,
+                model=model,
+                effort=phase_effort,
+                effort_metadata=effort_metadata,
+                timeout=timeout,
+            )
+        except ContinuousRefactorError as error:
+            return "abandon", _ready_check_failure_record(error, repo_root, target_label)
+
+        verdict, reason = _normalize_ready_verdict(verdict, reason)
+
+        if verdict == "yes":
+            head_before = get_head_sha(repo_root)
+            outcome = execute_phase(
+                phase,
+                manifest,
+                taste,
+                repo_root,
+                live_dir,
+                artifacts,
+                attempt=attempt,
+                retry=1,
+                agent=agent,
+                model=model,
+                effort=phase_effort,
+                effort_metadata=effort_metadata,
+                timeout=timeout,
+                validation_command=validation_command,
+                max_attempts=max_attempts,
+            )
+
+            if outcome.status != "failed":
+                finalize_commit(
+                    repo_root,
+                    head_before,
+                    build_commit_message(
+                        f"{commit_message_prefix}: migration/{manifest.name}"
+                        f"/{phase_file_reference(phase)}",
+                        why=sanitize_text(outcome.reason, repo_root) or outcome.reason,
+                        validation=validation_command,
+                    ),
+                    artifacts=artifacts,
+                    attempt=attempt,
+                    phase="migration",
+                )
+
+            print(
+                f"Migration: {outcome.status}"
+                f" — {manifest.name} {phase_file_reference(phase)} ({phase.name})"
+            )
+            if outcome.status == "failed":
+                return "abandon", _phase_failure_record(outcome, repo_root, target_label)
+            return "commit", _phase_commit_record(outcome, repo_root, target_label)
+
+        pending_defers.append(
+            (
+                _defer_manifest(manifest, now, verdict=verdict, reason=reason),
+                manifest_path,
+            )
+        )
+        if verdict == "unverifiable":
+            _save_pending_defers(pending_defers)
+            return "blocked", _human_review_record(reason, repo_root, target_label)
+        deferred_record = _deferred_record(reason, repo_root, target_label)
+
+    _save_pending_defers(pending_defers)
+    return "not-routed", deferred_record
+
+
+def _target_label(manifest: MigrationManifest, phase: PhaseSpec) -> str:
+    return f"{manifest.name} {phase_file_reference(phase)} ({phase.name})"
+
+
+def _normalize_ready_verdict(
+    verdict: ReadyVerdict,
+    reason: str,
+) -> tuple[ReadyVerdict, str]:
+    if verdict != "unverifiable":
+        return verdict, reason
+    if not _is_baseline_validation_uncertainty(reason):
+        return verdict, reason
+    return "no", reason
+
+
+def _is_baseline_validation_uncertainty(reason: str) -> bool:
+    reason_lower = reason.lower()
+    return any(
+        phrase in reason_lower
+        for phrase in _BASELINE_VALIDATION_UNCERTAINTY_PHRASES
+    )
+
+
+def _save_pending_defers(
+    pending_defers: list[tuple[MigrationManifest, Path]],
+) -> None:
+    for deferred_manifest, manifest_path in pending_defers:
+        save_manifest(deferred_manifest, manifest_path)
+
+
+def _effort_defer_reason(
+    phase: PhaseSpec,
+    *,
+    max_allowed_effort: str,
+) -> str:
+    detail = (
+        f" Reason: {phase.effort_reason}."
+        if phase.effort_reason
+        else ""
+    )
+    return (
+        f"Phase requires {phase.required_effort} effort, above this run's "
+        f"max allowed effort {max_allowed_effort}.{detail}"
+    )
+
+
+def _log_phase_effort_deferred(
+    artifacts: RunArtifacts,
+    target_label: str,
+    phase: PhaseSpec,
+    reason: str,
+    *,
+    max_allowed_effort: str,
+) -> None:
+    artifacts.log(
+        "INFO",
+        f"phase effort deferred: {target_label}",
+        event="phase_effort_deferred",
+        target=target_label,
+        required_effort=phase.required_effort,
+        max_allowed_effort=max_allowed_effort,
+        effort_reason=phase.effort_reason,
+        summary=reason,
+    )
+
+
+def _ready_check_failure_record(
+    error: ContinuousRefactorError, repo_root: Path, target_label: str,
+) -> DecisionRecord:
+    summary = sanitize_text(str(error), repo_root) or str(error)
+    return DecisionRecord(
+        decision="abandon",
+        retry_recommendation="new-target",
+        target=target_label,
+        call_role="phase.ready-check",
+        phase_reached="phase.ready-check",
+        failure_kind=error_failure_kind(str(error)),
+        summary=summary,
+    )
+
+
+def _phase_failure_record(
+    outcome: ExecutePhaseOutcome, repo_root: Path, target_label: str,
+) -> DecisionRecord:
+    return DecisionRecord(
+        decision="abandon",
+        retry_recommendation="new-target",
+        target=target_label,
+        call_role=outcome.call_role or "phase.execute",
+        phase_reached=outcome.phase_reached or "phase.execute",
+        failure_kind=outcome.failure_kind or "phase-failed",
+        summary=sanitize_text(outcome.reason, repo_root) or outcome.reason,
+        retry_used=outcome.retry,
+    )
+
+
+def _phase_commit_record(
+    outcome: ExecutePhaseOutcome,
+    repo_root: Path,
+    target_label: str,
+) -> DecisionRecord:
+    return DecisionRecord(
+        decision="commit",
+        retry_recommendation="none",
+        target=target_label,
+        call_role="phase.execute",
+        phase_reached="phase.execute",
+        failure_kind="none",
+        summary=sanitize_text(outcome.reason, repo_root) or outcome.reason,
+    )
+
+
+def _defer_manifest(
+    manifest: MigrationManifest,
+    now: datetime,
+    *,
+    verdict: str,
+    reason: str,
+) -> MigrationManifest:
+    updated = replace(
+        bump_last_touch(manifest, now),
+        cooldown_until=(now + timedelta(hours=6)).isoformat(timespec="milliseconds"),
+    )
+    if updated.wake_up_on is None:
+        wake = (now + timedelta(days=7)).isoformat(timespec="milliseconds")
+        updated = replace(updated, wake_up_on=wake)
+    if verdict == "unverifiable":
+        updated = replace(
+            updated,
+            awaiting_human_review=True,
+            human_review_reason=reason,
+        )
+    return updated
+
+
+def _human_review_record(
+    reason: str, repo_root: Path, target_label: str,
+) -> DecisionRecord:
+    summary = sanitize_text(reason, repo_root) or "Phase requires human review"
+    return DecisionRecord(
+        decision="blocked",
+        retry_recommendation="human-review",
+        target=target_label,
+        call_role="phase.ready-check",
+        phase_reached="phase.ready-check",
+        failure_kind="phase-ready-unverifiable",
+        summary=summary,
+    )
+
+
+def _deferred_record(reason: str, repo_root: Path, target_label: str) -> DecisionRecord:
+    return DecisionRecord(
+        decision="retry",
+        retry_recommendation="same-target",
+        target=target_label,
+        call_role="phase.ready-check",
+        phase_reached="phase.ready-check",
+        failure_kind="phase-ready-no",
+        summary=sanitize_text(reason, repo_root) or "Migration phase not ready",
+    )
+
+
+def _effort_deferred_record(
+    reason: str, repo_root: Path, target_label: str,
+) -> DecisionRecord:
+    return DecisionRecord(
+        decision="retry",
+        retry_recommendation="same-target",
+        target=target_label,
+        call_role="phase.effort-budget",
+        phase_reached="phase.effort-budget",
+        failure_kind="phase-effort-over-budget",
+        summary=sanitize_text(reason, repo_root) or "Migration phase over effort budget",
+    )