318 lines
12 KiB
Python
318 lines
12 KiB
Python
"""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"
|
|
)
|