303 lines
11 KiB
Python
303 lines
11 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 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"
|
|
)
|