"""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 app.workflows.deliverables import ( DEPENDENCY_GRAPH, PHASE_ORDER, DeliverableKind, PhaseId, deliverables_in, ) 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 DeliverableKind or PhaseId value actor: str detail: str = "" @dataclass(frozen=True) class ReopenResult: reset: tuple[DeliverableKind, ...] withdrawn_approvals: tuple[PhaseId, ...] 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, pre_approved: bool = False, max_revisions: int = 3) -> None: self.pre_approved = pre_approved self.max_revisions = max_revisions self._deliverables = {kind: _DeliverableRecord() for kind in DEPENDENCY_GRAPH} self._phases = {phase: PhaseStatus.OPEN for phase in PHASE_ORDER} self._events: list[LedgerEvent] = [] # --- queries ----------------------------------------------------------------- @property def events(self) -> tuple[LedgerEvent, ...]: return tuple(self._events) def status(self, kind: DeliverableKind) -> DeliverableStatus: return self._deliverables[kind].status def phase_status(self, phase: PhaseId) -> PhaseStatus: return self._phases[phase] def revisions(self, kind: DeliverableKind) -> int: return self._deliverables[kind].revisions def feedback(self, kind: DeliverableKind) -> tuple[str, ...]: return tuple(self._deliverables[kind].feedback) def dependencies_met(self, kind: DeliverableKind) -> bool: spec = DEPENDENCY_GRAPH[kind] for dependency in spec.depends_on: dependency_phase = DEPENDENCY_GRAPH[dependency].phase if dependency_phase is 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[DeliverableKind, ...]: return tuple( kind for kind in DEPENDENCY_GRAPH if self.status(kind) is DeliverableStatus.PENDING and self.dependencies_met(kind) ) def phases_ready_for_approval(self) -> tuple[PhaseId, ...]: return tuple( phase for phase in PHASE_ORDER if self._phases[phase] is PhaseStatus.OPEN and not self._unsubmitted(phase) ) def can_finish(self) -> bool: return self._phases[PHASE_ORDER[-1]] is PhaseStatus.APPROVED # --- delegation and submission ----------------------------------------------- def start( self, kinds: Iterable[DeliverableKind], actor: str ) -> dict[DeliverableKind, 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: DeliverableKind, 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: DeliverableKind, 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, DEPENDENCY_GRAPH[kind].specialist, reason) # --- approvals --------------------------------------------------------------- def request_approval(self, phase: PhaseId, 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: PhaseId, actor: str) -> None: self._require_awaiting(phase) self._phases[phase] = PhaseStatus.APPROVED self._record("approved", phase, actor) def request_changes(self, phase: PhaseId, 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: DeliverableKind, 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._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 PHASE_ORDER: affected = any(DEPENDENCY_GRAPH[k].phase is 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": { kind.value: { "status": record.status.value, "attempt": record.attempt, "revisions": record.revisions, "feedback": list(record.feedback), } for kind, record in self._deliverables.items() }, "phases": { phase.value: status.value for phase, status in self._phases.items() }, "events": [asdict(event) for event in self._events], } @classmethod def from_dict(cls, data: dict[str, Any]) -> Ledger: ledger = cls( pre_approved=data["pre_approved"], max_revisions=data["max_revisions"] ) for kind_value, record in data["deliverables"].items(): ledger._deliverables[DeliverableKind(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[PhaseId(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: PhaseId) -> list[DeliverableKind]: return [ kind for kind in deliverables_in(phase) if self.status(kind) is not DeliverableStatus.SUBMITTED ] def _dependents_of(self, kind: DeliverableKind) -> list[DeliverableKind]: """Every Deliverable that depends on `kind`, directly or not, in graph order.""" dependents: set[DeliverableKind] = set() frontier = {kind} while frontier: frontier = { candidate for candidate, spec in DEPENDENCY_GRAPH.items() if candidate not in dependents and frontier & set(spec.depends_on) } dependents |= frontier return [candidate for candidate in DEPENDENCY_GRAPH if candidate in dependents] def _describe_unready(self, kind: DeliverableKind) -> 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: DeliverableKind, 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: PhaseId) -> None: if self._phases[phase] is not PhaseStatus.AWAITING_APPROVAL: raise LedgerRefusal( f"Phase {phase} is {self._phases[phase]}, not awaiting_approval" )