This commit is contained in:
317
app/states/ledger.py
Normal file
317
app/states/ledger.py
Normal file
@@ -0,0 +1,317 @@
|
||||
"""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"
|
||||
)
|
||||
Reference in New Issue
Block a user