core-runtime 0.1.1__py3-none-any.whl

will/autonomy/proposal_state_manager.py

@@ -0,0 +1,239 @@
+# src/will/autonomy/proposal_state_manager.py
+
+"""
+Proposal State Manager - Lifecycle State Transitions
+
+CONSTITUTIONAL ALIGNMENT:
+- Single Responsibility: Manage proposal lifecycle states
+- Business logic separated from CRUD
+- Uses repository for persistence
+
+Handles state transitions:
+- mark_completed, mark_failed
+- approve, reject
+
+Extracted from ProposalRepository to separate state management concerns.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from sqlalchemy import update
+
+from shared.exceptions import CoreError
+from shared.logger import getLogger
+from shared.workers.base import _sanitize_payload
+from will.autonomy.proposal import ProposalStatus
+
+
+logger = getLogger(__name__)
+
+
+ALLOWED_APPROVAL_AUTHORITIES: frozenset[str] = frozenset(
+    {
+        "risk_classification.safe_auto_approval",
+        "principal.governor",
+    }
+)
+"""Closed set per .intent/META/enums.json proposal_approval_authority.
+Mirrored here for write-path validation; .intent/ is the canonical surface."""
+
+
+# ID: 59b43e1f-0d5e-4424-b9cc-1fdfaa22d1e3
+class ProposalNotFoundError(CoreError):
+    """Raised when an approve/reject UPDATE matches zero rows.
+
+    Indicates either the proposal_id does not exist or the row is not in a
+    state where the requested transition can land. Distinguishes silent
+    no-op from successful state change so callers and operators get a clear
+    failure signal instead of a false-success banner.
+    """
+
+
+# ID: 5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d
+class ProposalStateManager:
+    """
+    Manages proposal lifecycle state transitions.
+
+    Enforces valid state changes and updates timestamps appropriately.
+    """
+
+    def __init__(self, session: Any):
+        self._session = session
+
+    # -------------------------
+    # Execution State Transitions
+    # -------------------------
+
+    # ID: 360b7769-23e8-416d-875b-45e8d3c8194c
+    async def mark_completed(self, proposal_id: str, results: dict[str, Any]) -> None:
+        """Mark proposal as successfully completed."""
+        from shared.infrastructure.database.models.autonomous_proposals import (
+            AutonomousProposal,
+        )
+
+        stmt = (
+            update(AutonomousProposal)
+            .where(AutonomousProposal.proposal_id == proposal_id)
+            .values(
+                status=ProposalStatus.COMPLETED.value,
+                execution_completed_at=datetime.now(UTC),
+                execution_results=_sanitize_payload(results),
+            )
+        )
+        await self._session.execute(stmt)
+        await self._session.commit()
+        logger.info("Marked proposal as completed: %s", proposal_id)
+
+    # ID: 2f596c85-0d22-4de4-b919-791346cdb6aa
+    async def mark_failed(
+        self,
+        proposal_id: str,
+        reason: str,
+        results: dict[str, Any] | None = None,
+    ) -> None:
+        """Mark proposal as failed with reason and execution results.
+
+        UPDATE-only: transitions the proposal row on
+        core.autonomous_proposals to 'failed' status.
+
+        Revival of deferred findings and posting of the §7a revival report
+        are the calling Worker's orchestration responsibility per ADR-011.
+        The Worker detects ok=False from ProposalExecutor, invokes the
+        blackboard service's revival method (also UPDATE-only), and posts
+        the revival report via self.post_report() so the entry carries
+        Worker attribution. This method no longer invokes the blackboard
+        service directly.
+        """
+        from shared.infrastructure.database.models.autonomous_proposals import (
+            AutonomousProposal,
+        )
+
+        stmt = (
+            update(AutonomousProposal)
+            .where(AutonomousProposal.proposal_id == proposal_id)
+            .values(
+                status=ProposalStatus.FAILED.value,
+                execution_completed_at=datetime.now(UTC),
+                failure_reason=_sanitize_payload(reason),
+                execution_results=_sanitize_payload(results or {}),
+            )
+        )
+        await self._session.execute(stmt)
+        await self._session.commit()
+        logger.error("Marked proposal as failed: %s - %s", proposal_id, reason)
+
+    # -------------------------
+    # Approval State Transitions
+    # -------------------------
+
+    # ID: befa870d-148c-4f53-9c31-614380e93673
+    async def approve(
+        self,
+        proposal_id: str,
+        approved_by: str,
+        approval_authority: str,
+    ) -> None:
+        """Approve proposal for execution.
+
+        approval_authority is non-omittable per URS NFR.5: a proposal cannot
+        transition to status='approved' without recording the authority under
+        which approval was granted (21 CFR Part 11 §11.50 "meaning of
+        signature"; ALCOA+ "Attributable" extends "who" to include role).
+        Validation happens at the write path, before any database operation.
+
+        Args:
+            proposal_id: Public proposal id.
+            approved_by: Identity of the approver (worker tag, operator name).
+            approval_authority: Structured reference to the rule or role that
+                authorized approval. Must be one of
+                ALLOWED_APPROVAL_AUTHORITIES; mirrors the
+                proposal_approval_authority enum in .intent/META/enums.json.
+
+        Raises:
+            ValueError: If approval_authority is falsy or not in the closed set.
+        """
+        if not approval_authority:
+            raise ValueError(
+                "approval_authority is non-omittable per URS NFR.5; "
+                "approve() must receive a value from the proposal_approval_authority "
+                "closed set."
+            )
+        if approval_authority not in ALLOWED_APPROVAL_AUTHORITIES:
+            raise ValueError(
+                f"approval_authority {approval_authority!r} is not in the "
+                f"allowed set {sorted(ALLOWED_APPROVAL_AUTHORITIES)!r} "
+                "(per .intent/META/enums.json proposal_approval_authority)."
+            )
+
+        from shared.infrastructure.database.models.autonomous_proposals import (
+            AutonomousProposal,
+        )
+
+        stmt = (
+            update(AutonomousProposal)
+            .where(AutonomousProposal.proposal_id == proposal_id)
+            .values(
+                status=ProposalStatus.APPROVED.value,
+                approved_by=approved_by,
+                approved_at=datetime.now(UTC),
+                approval_authority=approval_authority,
+            )
+        )
+        result = await self._session.execute(stmt)
+        if result.rowcount == 0:
+            raise ProposalNotFoundError(
+                f"Proposal not found or not in an approvable state: {proposal_id!r}"
+            )
+        # Caller controls transactional scope (matches update_fields convention).
+        logger.info(
+            "Approved proposal: %s by %s under %s",
+            proposal_id,
+            approved_by,
+            approval_authority,
+        )
+
+    # ID: dbdfc785-73e1-47c5-a886-3a2435c8dc95
+    async def reject(self, proposal_id: str, reason: str) -> None:
+        """Reject proposal with reason."""
+        from shared.infrastructure.database.models.autonomous_proposals import (
+            AutonomousProposal,
+        )
+
+        stmt = (
+            update(AutonomousProposal)
+            .where(AutonomousProposal.proposal_id == proposal_id)
+            .values(
+                status=ProposalStatus.REJECTED.value,
+                failure_reason=reason,
+            )
+        )
+        result = await self._session.execute(stmt)
+        if result.rowcount == 0:
+            raise ProposalNotFoundError(
+                f"Proposal not found or not in a rejectable state: {proposal_id!r}"
+            )
+        await self._session.commit()
+        logger.info("Rejected proposal: %s - %s", proposal_id, reason)
+
+    # -------------------------
+    # Context Manager for Session Lifecycle
+    # -------------------------
+
+    @classmethod
+    # ID: eafbc456-17aa-4b5c-b0e8-ee8a697d0925
+    async def with_session(cls, proposal_id: str) -> ProposalStateManager:
+        """
+        Create state manager with shared session.
+
+        For use within existing repository context:
+            async with ProposalRepository.open() as repo:
+                manager = await ProposalStateManager.with_session(...)
+        """
+        # This is intentionally simple - callers should use the service_registry
+        # pattern or wrap in their own context manager
+        raise NotImplementedError(
+            "Use ProposalStateManager(session) within an existing session context"
+        )

will/deciders/__init__.py

@@ -0,0 +1,9 @@
+# src/will/deciders/__init__.py
+"""Deciders - RUNTIME phase components for final authorization."""
+
+from __future__ import annotations
+
+from .governance_decider import GovernanceDecider
+
+
+__all__ = ["GovernanceDecider"]

will/deciders/governance_decider.py

@@ -0,0 +1,207 @@
+# src/will/deciders/governance_decider.py
+"""
+Governance Decider — DECIDE phase component.
+
+The final gatekeeper that authorizes or blocks state-changing execution.
+
+Constitutional change (Logic Conservation Gate promotion):
+    GovernanceDecider now recognises ComponentResults from
+    LogicConservationValidator specifically. A logic evaporation verdict
+    is treated as a CRITICAL blocker regardless of risk tier — it cannot
+    be overridden by confidence thresholds or tier relaxation.
+
+    This makes the Anti-Lobotomy gate constitutional rather than local
+    to ComplexityRemediationService. Any workflow that routes through
+    GovernanceDecider receives the protection automatically.
+
+Constitutional alignment:
+- Layer:     will — decision-making, never execution
+- Phase:     RUNTIME — authorises or blocks before any state change
+- Authority: constitution — logic conservation blocks at all tiers
+- Boundary:  no get_session, no file writes, no Body implementation
+
+LAYER: will/deciders — RUNTIME phase decision component. Aggregates
+evaluator evidence and produces a formal Go/No-Go authorisation token.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from shared.component_primitive import ComponentResult
+from shared.logger import getLogger
+from will.orchestration.decision_tracer import DecisionTracer
+from will.strategists.base_strategist import BaseStrategist
+
+
+logger = getLogger(__name__)
+
+# Component ID of the logic conservation gate — used to detect its results
+# without creating a hard import dependency on the Body layer validator.
+_LOGIC_CONSERVATION_COMPONENT_ID = "logic_conservation_validator"
+
+# Verdict key written by LogicConservationValidator on evaporation
+_EVAPORATION_VERDICT = "logic_evaporation"
+
+
+# ID: 79a654be-b451-4932-93fe-d90b4a8f7a77
+class GovernanceDecider(BaseStrategist):
+    """
+    Evaluates cumulative evidence to authorise execution.
+
+    Responsibilities:
+    - Aggregate results from multiple Evaluators.
+    - Detect CRITICAL violations (logic evaporation, layer breaches).
+    - Check for any 'not ok' results from required Evaluators.
+    - Evaluate whether confidence meets the threshold for the Risk Tier.
+    - Produce a formal 'Authorization Token' or 'Halt' signal.
+
+    Logic Conservation Gate:
+        Results from LogicConservationValidator are treated as CRITICAL
+        blockers. A logic_evaporation verdict halts execution regardless
+        of risk tier, confidence level, or other passing evaluations.
+        This cannot be overridden at the Decider level — it requires an
+        explicit deletions_authorized=True flag upstream in the workflow.
+    """
+
+    def __init__(self) -> None:
+        self.tracer = DecisionTracer()
+
+    # ID: c2aeb827-6b0d-4036-8fca-a01fc2244524
+    async def execute(
+        self,
+        evaluation_results: list[ComponentResult],
+        risk_tier: str = "STANDARD",
+        **kwargs: Any,
+    ) -> ComponentResult:
+        """
+        Make a final Go/No-Go decision.
+
+        Args:
+            evaluation_results: Ordered list of ComponentResults from evaluators.
+                                 Must include LogicConservationValidator result
+                                 for any workflow that modifies source files.
+            risk_tier:          ROUTINE | STANDARD | ELEVATED | CRITICAL.
+                                 Higher tiers require higher average confidence.
+
+        Returns:
+            ComponentResult where:
+                data["can_proceed"] = True  → execution is authorised
+                data["can_proceed"] = False → execution is blocked
+                data["blockers"]            → list of reasons for halt
+                data["authorization_token"] → opaque token if authorised
+        """
+        start_time = time.time()
+
+        violations: list[str] = []
+        warnings: list[str] = []
+        critical_blocks: list[str] = []
+        total_confidence = 0.0
+
+        # ── 1. Aggregate Evidence ─────────────────────────────────────────────
+        for res in evaluation_results:
+            # CRITICAL path: Logic Conservation Gate.
+            # A logic_evaporation verdict is a hard constitutional block.
+            # It bypasses the normal violation aggregation and fires immediately.
+            if res.component_id == _LOGIC_CONSERVATION_COMPONENT_ID:
+                if not res.ok and res.data.get("verdict") == _EVAPORATION_VERDICT:
+                    msg = (
+                        f"CRITICAL — Logic evaporation detected by "
+                        f"{_LOGIC_CONSERVATION_COMPONENT_ID}: "
+                        f"{res.data.get('message', 'proposed code below mass threshold')}"
+                    )
+                    critical_blocks.append(msg)
+                    logger.error("GovernanceDecider: %s", msg)
+                # Whether ok or not, still accumulate confidence normally.
+
+            # Standard violation path: any not-ok evaluator blocks execution.
+            if not res.ok:
+                violations.append(
+                    f"{res.component_id}: {res.data.get('error', res.data.get('message', 'Unknown failure'))}"
+                )
+
+            # Collect warnings from evaluator metadata.
+            violation_count = res.metadata.get("violation_count", 0)
+            if violation_count > 0:
+                warnings.append(
+                    f"{res.component_id} reported {violation_count} issue(s)."
+                )
+
+            total_confidence += res.confidence
+
+        avg_confidence = (
+            total_confidence / len(evaluation_results) if evaluation_results else 1.0
+        )
+
+        # ── 2. Decision Logic (The Law) ───────────────────────────────────────
+
+        # Rule A: Critical constitutional blocks always halt — no tier override.
+        if critical_blocks:
+            can_proceed = False
+            all_blockers = critical_blocks + violations
+            decision = "HALT"
+            logger.warning(
+                "GovernanceDecider: HALT — %d critical block(s), %d violation(s).",
+                len(critical_blocks),
+                len(violations),
+            )
+
+        else:
+            # Rule B: Any not-ok result from a required evaluator blocks execution.
+            can_proceed = len(violations) == 0
+
+            # Rule C: High-risk tiers require higher average confidence.
+            confidence_threshold = 0.8 if risk_tier in ("ELEVATED", "CRITICAL") else 0.5
+            if avg_confidence < confidence_threshold:
+                can_proceed = False
+                violations.append(
+                    f"Confidence {avg_confidence:.2f} below threshold "
+                    f"{confidence_threshold} for {risk_tier} tier."
+                )
+
+            all_blockers = violations
+            decision = "PROCEED" if can_proceed else "HALT"
+
+        # ── 3. Mandatory Decision Tracing ─────────────────────────────────────
+        self.tracer.record(
+            agent=self.component_id,
+            decision_type="final_authorization",
+            rationale=(
+                f"Decision {decision} based on {len(evaluation_results)} evaluation(s) "
+                f"at {risk_tier} tier. "
+                f"Critical blocks: {len(critical_blocks)}. "
+                f"Violations: {len(violations)}. "
+                f"Avg confidence: {avg_confidence:.2f}."
+            ),
+            chosen_action=decision,
+            context={
+                "critical_blocks": critical_blocks,
+                "violations": all_blockers,
+                "warnings": warnings,
+                "avg_confidence": avg_confidence,
+                "risk_tier": risk_tier,
+            },
+            confidence=avg_confidence,
+        )
+
+        duration = time.time() - start_time
+
+        return ComponentResult(
+            component_id=self.component_id,
+            ok=True,  # The Decider itself succeeded in producing a decision.
+            data={
+                "decision": decision,
+                "can_proceed": can_proceed,
+                "authorization_token": (
+                    f"auth_{int(time.time())}" if can_proceed else None
+                ),
+                "blockers": all_blockers,
+                "critical_blocks": critical_blocks,
+                "warnings": warnings,
+            },
+            phase=self.phase,
+            confidence=1.0,
+            metadata={"verdict": decision, "risk_tier": risk_tier},
+            duration_sec=duration,
+        )

will/governance/__init__.py

@@ -0,0 +1,13 @@
+# src/will/governance/__init__.py
+
+"""
+Will-layer governance facades.
+
+This package exposes thin facades the API layer can import without
+reaching into mind.* or shared.infrastructure.* directly. ADR-054
+Phase 1 introduces the first such facade: run_and_persist_audit,
+which wraps mind.enforcement.audit.run_audit_workflow with persistence
+into core.audit_runs.
+"""
+
+from __future__ import annotations

will/governance/audit_remediation_runner.py

@@ -0,0 +1,197 @@
+# src/will/governance/audit_remediation_runner.py
+
+"""
+Audit-remediation runner facade — Will-layer entry point for
+POST /audit/remediations (ADR-057 D4).
+
+The /audit/remediations surface was deferred from ADR-055 Phase 2 because
+its resource model belongs alongside audit_runs, not fix_runs. It runs the
+AuditRemediationService against findings produced by a prior audit_runs
+row, persisting the cycle on core.audit_remediation_runs.
+
+Single entry point:
+
+* `run_and_persist_audit_remediation` — fire-and-forget runner. The
+  route handler INSERTs a pending row with status='pending', mode, and
+  audit_run_id; this function transitions it through executing →
+  completed | failed and writes the RemediationResult summary into the
+  result jsonb.
+
+The remediation path is guarded by the circuit breaker (ADR-038) at the
+service layer — this facade does not re-implement that check.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy import text
+
+from body.self_healing.remediation_models import RemediationMode
+from shared.context import CoreContext
+from shared.logger import getLogger
+from will.self_healing.audit_remediation_service import AuditRemediationService
+
+
+__all__ = [
+    "MODE_ALIASES",
+    "resolve_mode",
+    "run_and_persist_audit_remediation",
+]
+
+
+logger = getLogger(__name__)
+
+
+# The ADR-057 D4 wire vocabulary ('safe' | 'medium' | 'all') maps onto
+# the internal RemediationMode enum. Strict alias table — unknown values
+# raise at the route layer with a 422.
+MODE_ALIASES: dict[str, RemediationMode] = {
+    "safe": RemediationMode.SAFE_ONLY,
+    "medium": RemediationMode.MEDIUM_RISK,
+    "all": RemediationMode.ALL_DETERMINISTIC,
+}
+
+
+# ID: 9c14e8b3-2a47-4e9d-bef1-8c3d70a52f64
+def resolve_mode(mode: str) -> RemediationMode:
+    """Translate the ADR-057 D4 wire-format mode to RemediationMode.
+
+    Raises ValueError on unknown input; the route handler converts that
+    to a 422.
+    """
+    try:
+        return MODE_ALIASES[mode]
+    except KeyError as exc:
+        raise ValueError(
+            f"Unknown remediation mode: {mode!r}. "
+            f"Allowed: {sorted(MODE_ALIASES.keys())}"
+        ) from exc
+
+
+# ID: 5d2a90fc-7b8e-49c1-a3b0-9c8a4e1f6d72
+async def _update_remediation_run_status(
+    session: Any,
+    run_id: UUID,
+    status: str,
+    *,
+    started: bool = False,
+    finished: bool = False,
+    error: str | None = None,
+    result: dict | None = None,
+) -> None:
+    """Update an audit_remediation_runs row's lifecycle state.
+
+    Mirrors fix_runner._update_fix_run_status. Each call commits.
+    """
+    sets = ["status = :status"]
+    params: dict[str, Any] = {"status": status, "rid": run_id}
+
+    if started:
+        sets.append("started_at = now()")
+    if finished:
+        sets.append("finished_at = now()")
+    if error is not None:
+        sets.append("error = :err")
+        params["err"] = error
+    if result is not None:
+        sets.append("result = cast(:result as jsonb)")
+        params["result"] = json.dumps(result, default=str)
+
+    await session.execute(
+        text(
+            f"UPDATE core.audit_remediation_runs SET {', '.join(sets)} WHERE id = :rid"
+        ),
+        params,
+    )
+    await session.commit()
+
+
+# ID: 1f93b6e4-4c10-4e51-a72d-6e8e5c4f9013
+async def run_and_persist_audit_remediation(
+    context: CoreContext,
+    session: Any,
+    *,
+    run_id: UUID,
+    mode: str,
+    write: bool,
+) -> None:
+    """Execute autonomous audit remediation and persist on the run row.
+
+    The row has already been INSERTed by the route handler with
+    status='pending'. This function transitions it through executing →
+    completed | failed.
+
+    `mode` is the ADR-057 wire vocabulary ('safe' | 'medium' | 'all');
+    `write` honours the ADR-014 dev-phase dry-run-first discipline.
+
+    Errors are caught and recorded on the row; this function never
+    raises into the background-task scheduler.
+    """
+    await _update_remediation_run_status(session, run_id, "executing", started=True)
+
+    try:
+        resolved_mode = resolve_mode(mode)
+    except ValueError as exc:
+        await _update_remediation_run_status(
+            session,
+            run_id,
+            "failed",
+            finished=True,
+            error=str(exc),
+        )
+        return
+
+    try:
+        service = AuditRemediationService(
+            file_handler=context.file_handler,
+            auditor_context=context.auditor_context,
+            repo_root=context.git_service.repo_path,
+        )
+        result = await service.remediate(
+            mode=resolved_mode,
+            write=write,
+        )
+    except Exception as exc:
+        logger.exception("audit_remediation_runner: remediation raised for %s", run_id)
+        await _update_remediation_run_status(
+            session,
+            run_id,
+            "failed",
+            finished=True,
+            error=f"{type(exc).__name__}: {exc}",
+        )
+        return
+
+    summary = {
+        "total_findings": result.total_findings,
+        "fixes_attempted": result.fixes_attempted,
+        "fixes_succeeded": result.fixes_succeeded,
+        "improvement_delta": result.improvement_delta,
+        "validation_passed": result.validation_passed,
+        "findings_before": result.findings_before,
+        "findings_after": result.findings_after,
+        "duration_sec": result.duration_sec,
+        "audit_input_path": result.audit_input_path,
+        "remediation_output_path": result.remediation_output_path,
+        "validation_audit_path": result.validation_audit_path,
+    }
+    ok = result.fixes_succeeded > 0 or result.fixes_attempted == 0
+    await _update_remediation_run_status(
+        session,
+        run_id,
+        "completed" if ok else "failed",
+        finished=True,
+        error=None if ok else "No fixes succeeded",
+        result=summary,
+    )
+
+    logger.info(
+        "audit_remediation_runner: %s completed mode=%s succeeded=%d/%d",
+        run_id,
+        mode,
+        result.fixes_succeeded,
+        result.fixes_attempted,
+    )