"""The Ledger: every rule code owns about Deliverable progress, Approvals and Revisions. Pure and synchronous: no I/O, no framework types. Invalid requests raise LedgerRefusal and leave the Ledger unchanged; tools turn refusals into messages the agent can act on. """ from __future__ import annotations from collections.abc import Iterable from dataclasses import asdict, dataclass, field from enum import StrEnum from typing import Any from execution_engine.workflows.workflow import Workflow PRE_APPROVED_ACTOR = "pre-approved" class DeliverableStatus(StrEnum): PENDING = "pending" IN_PROGRESS = "in_progress" SUBMITTED = "submitted" class PhaseStatus(StrEnum): OPEN = "open" AWAITING_APPROVAL = "awaiting_approval" APPROVED = "approved" class LedgerRefusal(Exception): """A request the Ledger's rules don't allow. Nothing was changed.""" @dataclass(frozen=True) class LedgerEvent: sequence: int type: str # started | released | submitted | approval_requested | approved | # changes_requested | reopened | reset | approval_withdrawn | escalated subject: str # a Deliverable kind or a Phase id actor: str detail: str = "" @dataclass(frozen=True) class ReopenResult: reset: tuple[str, ...] withdrawn_approvals: tuple[str, ...] escalation: str | None = None @dataclass class _DeliverableRecord: status: DeliverableStatus = DeliverableStatus.PENDING attempt: int = 0 revisions: int = 0 feedback: list[str] = field(default_factory=list) class Ledger: def __init__( self, workflow: Workflow, pre_approved: bool = False, max_revisions: int = 3 ) -> None: self.workflow = workflow self.pre_approved = pre_approved self.max_revisions = max_revisions self._graph = workflow.deliverables self._deliverables = {kind: _DeliverableRecord() for kind in self._graph} self._phases = {phase: PhaseStatus.OPEN for phase in workflow.phases} self._events: list[LedgerEvent] = [] # --- queries ----------------------------------------------------------------- @property def events(self) -> tuple[LedgerEvent, ...]: return tuple(self._events) def status(self, kind: str) -> DeliverableStatus: return self._deliverables[kind].status def phase_status(self, phase: str) -> PhaseStatus: return self._phases[phase] def revisions(self, kind: str) -> int: return self._deliverables[kind].revisions def feedback(self, kind: str) -> tuple[str, ...]: return tuple(self._deliverables[kind].feedback) def dependencies_met(self, kind: str) -> bool: spec = self._graph[kind] for dependency in spec.depends_on: dependency_phase = self._graph[dependency].phase if dependency_phase == spec.phase: if self.status(dependency) is not DeliverableStatus.SUBMITTED: return False elif self._phases[dependency_phase] is not PhaseStatus.APPROVED: return False return True def ready_work(self) -> tuple[str, ...]: return tuple( kind for kind in self._graph if self.status(kind) is DeliverableStatus.PENDING and self.dependencies_met(kind) ) def phases_ready_for_approval(self) -> tuple[str, ...]: return tuple( phase for phase in self.workflow.phases if self._phases[phase] is PhaseStatus.OPEN and not self._unsubmitted(phase) ) def can_finish(self) -> bool: return self._phases[self.workflow.phases[-1]] is PhaseStatus.APPROVED # --- delegation and submission ----------------------------------------------- def start(self, kinds: Iterable[str], actor: str) -> dict[str, int]: """Move ready Deliverables in progress; returns the attempt number for each.""" kinds = list(dict.fromkeys(kinds)) ready = set(self.ready_work()) not_ready = [kind for kind in kinds if kind not in ready] if not_ready: raise LedgerRefusal( "Not ready to start: " + ", ".join(self._describe_unready(k) for k in not_ready) ) attempts = {} for kind in kinds: record = self._deliverables[kind] record.status = DeliverableStatus.IN_PROGRESS record.attempt += 1 attempts[kind] = record.attempt self._record("started", kind, actor, f"attempt {record.attempt}") return attempts def submit(self, kind: str, attempt: int, actor: str) -> None: """Accept the current attempt. Any later start, release or reopen supersedes it.""" self._require_current_attempt(kind, attempt) self._deliverables[kind].status = DeliverableStatus.SUBMITTED self._record("submitted", kind, actor, f"attempt {attempt}") def release(self, kind: str, attempt: int, reason: str) -> None: """Return in-progress work to pending (e.g. the Specialist needs input).""" self._require_current_attempt(kind, attempt) record = self._deliverables[kind] record.status = DeliverableStatus.PENDING self._record("released", kind, self._graph[kind].specialist, reason) # --- approvals --------------------------------------------------------------- def request_approval(self, phase: str, actor: str) -> None: if self._phases[phase] is not PhaseStatus.OPEN: raise LedgerRefusal(f"Phase {phase} is {self._phases[phase]}, not open") unsubmitted = self._unsubmitted(phase) if unsubmitted: raise LedgerRefusal( f"Phase {phase} has unsubmitted Deliverables: {', '.join(unsubmitted)}" ) self._phases[phase] = PhaseStatus.AWAITING_APPROVAL self._record("approval_requested", phase, actor) if self.pre_approved: self.approve(phase, actor=PRE_APPROVED_ACTOR) def approve(self, phase: str, actor: str) -> None: self._require_awaiting(phase) self._phases[phase] = PhaseStatus.APPROVED self._record("approved", phase, actor) def request_changes(self, phase: str, feedback: str, actor: str) -> None: self._require_awaiting(phase) self._phases[phase] = PhaseStatus.OPEN self._record("changes_requested", phase, actor, feedback) # --- revisions --------------------------------------------------------------- def reopen( self, kind: str, reason: str, actor: str, override_cap: bool = False, ) -> ReopenResult: record = self._deliverables[kind] if record.status is not DeliverableStatus.SUBMITTED: raise LedgerRefusal( f"Only submitted Deliverables can be reopened; {kind} is {record.status}" ) if record.revisions >= self.max_revisions and not override_cap: escalation = ( f"{kind} has reached its revision limit ({self.max_revisions}). " f"Requested change: {reason}. Ask the user whether to revise it again " "or accept it as it stands." ) self._record("escalated", kind, actor, reason) return ReopenResult(reset=(), withdrawn_approvals=(), escalation=escalation) record.status = DeliverableStatus.PENDING record.revisions += 1 record.feedback.append(reason) self._record("reopened", kind, actor, reason) reset = [kind] for dependent in self.workflow.dependents_of(kind): dependent_record = self._deliverables[dependent] if dependent_record.status is DeliverableStatus.PENDING: continue dependent_record.status = DeliverableStatus.PENDING dependent_record.feedback.append(f"Dependency {kind} was revised: {reason}") self._record("reset", dependent, actor, f"dependency {kind} reopened") reset.append(dependent) withdrawn = [] for phase in self.workflow.phases: affected = any(self._graph[k].phase == phase for k in reset) if affected and self._phases[phase] is not PhaseStatus.OPEN: self._phases[phase] = PhaseStatus.OPEN self._record("approval_withdrawn", phase, actor, f"{kind} reopened") withdrawn.append(phase) return ReopenResult(reset=tuple(reset), withdrawn_approvals=tuple(withdrawn)) # --- persistence ------------------------------------------------------------- def to_dict(self) -> dict[str, Any]: return { "pre_approved": self.pre_approved, "max_revisions": self.max_revisions, "deliverables": { str(kind): { "status": record.status.value, "attempt": record.attempt, "revisions": record.revisions, "feedback": list(record.feedback), } for kind, record in self._deliverables.items() }, "phases": { str(phase): status.value for phase, status in self._phases.items() }, "events": [asdict(event) for event in self._events], } @classmethod def from_dict(cls, workflow: Workflow, data: dict[str, Any]) -> Ledger: ledger = cls( workflow, pre_approved=data["pre_approved"], max_revisions=data["max_revisions"], ) for kind_value, record in data["deliverables"].items(): ledger._deliverables[workflow.kind(kind_value)] = _DeliverableRecord( status=DeliverableStatus(record["status"]), attempt=record["attempt"], revisions=record["revisions"], feedback=list(record["feedback"]), ) for phase_value, status in data["phases"].items(): ledger._phases[workflow.phase(phase_value)] = PhaseStatus(status) ledger._events = [LedgerEvent(**event) for event in data["events"]] return ledger # --- internals --------------------------------------------------------------- def _record(self, type_: str, subject: str, actor: str, detail: str = "") -> None: self._events.append( LedgerEvent(len(self._events) + 1, type_, str(subject), actor, detail) ) def _unsubmitted(self, phase: str) -> list[str]: return [ kind for kind in self.workflow.deliverables_in(phase) if self.status(kind) is not DeliverableStatus.SUBMITTED ] def _describe_unready(self, kind: str) -> str: status = self.status(kind) if status is not DeliverableStatus.PENDING: return f"{kind} ({status})" return f"{kind} (dependencies not met)" def _require_current_attempt(self, kind: str, attempt: int) -> None: record = self._deliverables[kind] if ( record.status is not DeliverableStatus.IN_PROGRESS or attempt != record.attempt ): raise LedgerRefusal( f"{kind} is {record.status}, not in_progress with attempt {attempt}; " "this attempt is not current" ) def _require_awaiting(self, phase: str) -> None: if self._phases[phase] is not PhaseStatus.AWAITING_APPROVAL: raise LedgerRefusal( f"Phase {phase} is {self._phases[phase]}, not awaiting_approval" )