devflow-toolkit 0.3.0__py3-none-any.whl

devflow/core/state/events.py

@@ -0,0 +1,725 @@
+"""Append-only workflow event log and its state projection."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Any
+
+from devflow.core.artifacts.models import (
+  ARTIFACT_SOURCES,
+  ArtifactRecord,
+  ArtifactStatus,
+)
+from devflow.core.state.errors import (
+  InvalidEventLogError,
+  InvalidTransitionError,
+)
+from devflow.core.state.models import (
+  STAGE_ARTIFACTS,
+  STAGE_OPTIONAL_ARTIFACTS,
+  STAGE_TARGETS,
+  WORKFLOW_STATUSES,
+  ApprovalRecord,
+  WorkflowState,
+  WorkflowStatus,
+)
+from devflow.core.state.transitions import ensure_transition
+
+WORKFLOW_INITIALIZED = "workflow_initialized"
+WORKFLOW_TRANSITION = "workflow_transition"
+
+WORKFLOW_EVENTS = frozenset({WORKFLOW_INITIALIZED, WORKFLOW_TRANSITION})
+ARTIFACT_EVENT_SUFFIXES = frozenset(
+  {"generated", "validated", "rejected", "stale"}
+)
+APPROVAL_EVENT_SUFFIX = "approved"
+
+_EVENT_KIND_WORKFLOW = "workflow"
+_EVENT_KIND_ARTIFACT = "artifact"
+_EVENT_KIND_APPROVAL = "approval"
+
+_EVENT_STATUSES = {
+  "generated": ArtifactStatus.GENERATED.value,
+  "validated": ArtifactStatus.VALIDATED.value,
+  "rejected": ArtifactStatus.REJECTED.value,
+  "stale": ArtifactStatus.STALE.value,
+}
+_SHA256_PATTERN = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
+@dataclass(frozen=True)
+class WorkflowEvent:
+  """One immutable entry in events.jsonl."""
+
+  seq: int
+  event_id: str
+  type: str
+  timestamp: str
+  actor: str
+  run_id: str | None = None
+  payload: dict[str, Any] = field(default_factory=dict)
+
+  def to_dict(self) -> dict[str, Any]:
+    return {
+      "seq": self.seq,
+      "event_id": self.event_id,
+      "type": self.type,
+      "timestamp": self.timestamp,
+      "actor": self.actor,
+      "run_id": self.run_id,
+      "payload": dict(self.payload),
+    }
+
+  def to_json(self) -> str:
+    return json.dumps(
+      self.to_dict(),
+      ensure_ascii=False,
+      separators=(",", ":"),
+    )
+
+  @classmethod
+  def from_dict(cls, data: dict[str, Any]) -> WorkflowEvent:
+    if not isinstance(data, dict):
+      msg = "Workflow event must be a mapping."
+      raise InvalidEventLogError(msg)
+
+    payload_value = data.get("payload", {})
+    if payload_value is None:
+      payload: dict[str, Any] = {}
+    elif isinstance(payload_value, dict):
+      payload = payload_value
+    else:
+      msg = "Workflow event payload must be a mapping."
+      raise InvalidEventLogError(msg)
+
+    return cls(
+      seq=_positive_int(data.get("seq"), "seq"),
+      event_id=_required_text(data.get("event_id"), "event_id"),
+      type=_required_text(data.get("type"), "type"),
+      timestamp=_required_text(data.get("timestamp"), "timestamp"),
+      actor=_required_text(data.get("actor", "system"), "actor"),
+      run_id=_optional_text(data.get("run_id"), "run_id"),
+      payload=payload,
+    )
+
+
+def read_events(path: Path) -> tuple[WorkflowEvent, ...]:
+  """Read and validate the structural invariants of the event log."""
+  if not path.is_file():
+    return ()
+  events: list[WorkflowEvent] = []
+  try:
+    lines = path.read_text(encoding="utf-8").splitlines()
+  except OSError as error:
+    msg = f"Could not read event log: {path}"
+    raise InvalidEventLogError(msg) from error
+
+  seen_ids: dict[str, int] = {}
+  for number, line in enumerate(lines, start=1):
+    if not line.strip():
+      continue
+    try:
+      data = json.loads(line)
+    except json.JSONDecodeError as error:
+      msg = f"Invalid JSON in event log at line {number}: {path}"
+      raise InvalidEventLogError(msg) from error
+    if not isinstance(data, dict):
+      msg = f"Event log line {number} must contain an object: {path}"
+      raise InvalidEventLogError(msg)
+    try:
+      event = WorkflowEvent.from_dict(data)
+      classify_event(event.type)
+    except InvalidEventLogError as error:
+      msg = f"Invalid event at line {number}: {error}"
+      raise InvalidEventLogError(msg) from error
+    except (KeyError, TypeError, ValueError) as error:
+      msg = f"Invalid event at line {number}: {path}"
+      raise InvalidEventLogError(msg) from error
+
+    if event.event_id in seen_ids:
+      first_seq = seen_ids[event.event_id]
+      msg = (
+        f"Duplicate event_id '{event.event_id}' at line {number} "
+        f"(seq {event.seq}); first seen at seq {first_seq}: {path}"
+      )
+      raise InvalidEventLogError(msg)
+    seen_ids[event.event_id] = event.seq
+    events.append(event)
+
+  expected = 1
+  for event in events:
+    if event.seq != expected:
+      msg = (
+        f"Event sequence is not contiguous at event {event.event_id}: "
+        f"expected {expected}, found {event.seq}."
+      )
+      raise InvalidEventLogError(msg)
+    expected += 1
+
+  if events and events[0].type != WORKFLOW_INITIALIZED:
+    msg = (
+      "Event log must start with "
+      f"{WORKFLOW_INITIALIZED}, found {events[0].type}."
+    )
+    raise InvalidEventLogError(msg)
+  for event in events[1:]:
+    if event.type == WORKFLOW_INITIALIZED:
+      msg = (
+        f"Duplicate {WORKFLOW_INITIALIZED} event at seq "
+        f"{event.seq} ({event.event_id})."
+      )
+      raise InvalidEventLogError(msg)
+  return tuple(events)
+
+
+def classify_event(
+  event_type: str,
+) -> tuple[str, str | None, str | None]:
+  """Classify an event without applying it to workflow state."""
+  if event_type in WORKFLOW_EVENTS:
+    return _EVENT_KIND_WORKFLOW, None, None
+
+  stage, separator, suffix = event_type.rpartition("_")
+  if separator and stage in STAGE_ARTIFACTS:
+    if suffix in ARTIFACT_EVENT_SUFFIXES:
+      return _EVENT_KIND_ARTIFACT, stage, suffix
+    if suffix == APPROVAL_EVENT_SUFFIX:
+      return _EVENT_KIND_APPROVAL, stage, suffix
+
+  msg = f"Unknown workflow event type: {event_type}"
+  raise InvalidEventLogError(msg)
+
+
+def replay_events(events: Iterable[WorkflowEvent]) -> WorkflowState:
+  """Replay a complete event history into a new workflow state."""
+  ordered = tuple(events)
+  if ordered and ordered[0].type != WORKFLOW_INITIALIZED:
+    raise _event_error(
+      ordered[0],
+      f"the first event must be {WORKFLOW_INITIALIZED}",
+    )
+  state = WorkflowState()
+  for event in ordered:
+    apply_event(state, event)
+  return state
+
+
+def append_event(path: Path, event: WorkflowEvent) -> None:
+  """Append one event durably."""
+  path.parent.mkdir(parents=True, exist_ok=True)
+  line = event.to_json() + "\n"
+  try:
+    descriptor = os.open(
+      path,
+      os.O_APPEND | os.O_CREAT | os.O_WRONLY,
+      0o644,
+    )
+    try:
+      data = line.encode("utf-8")
+      while data:
+        written = os.write(descriptor, data)
+        data = data[written:]
+      os.fsync(descriptor)
+    finally:
+      os.close(descriptor)
+  except OSError as error:
+    msg = f"Could not append to event log: {path}"
+    raise InvalidEventLogError(msg) from error
+
+
+def apply_event(state: WorkflowState, event: WorkflowEvent) -> WorkflowState:
+  """Validate and apply one event to a workflow projection."""
+  expected = state.last_event_seq + 1
+  if event.seq != expected:
+    raise _event_error(
+      event,
+      f"expected sequence {expected}, found {event.seq}",
+    )
+
+  try:
+    kind, stage, suffix = classify_event(event.type)
+  except InvalidEventLogError as error:
+    raise _event_error(event, str(error)) from error
+
+  if kind == _EVENT_KIND_WORKFLOW:
+    if event.type == WORKFLOW_INITIALIZED:
+      _apply_initialized(state, event)
+    else:
+      _apply_transition(state, event)
+  elif kind == _EVENT_KIND_ARTIFACT:
+    if stage is None or suffix is None:
+      raise _event_error(event, "artifact event is missing its stage.")
+    _apply_artifact_event(state, event, stage, suffix)
+  else:
+    if stage is None:
+      raise _event_error(event, "approval event is missing its stage.")
+    _apply_approval(state, event, stage)
+
+  state.last_event_seq = event.seq
+  state.updated_at = event.timestamp
+  return state
+
+
+def _apply_initialized(
+  state: WorkflowState,
+  event: WorkflowEvent,
+) -> None:
+  payload = event.payload
+  version_value = payload.get("version", 1)
+  if (
+    isinstance(version_value, bool)
+    or not isinstance(version_value, int)
+    or version_value != 1
+  ):
+    raise _event_error(event, "only workflow version 1 is supported.")
+
+  status_value = payload.get("status", WorkflowStatus.DRAFT.value)
+  if status_value != WorkflowStatus.DRAFT.value:
+    raise _event_error(
+      event,
+      "workflow_initialized must start in draft.",
+    )
+
+  if state.last_event_seq != 0:
+    raise _event_error(
+      event,
+      "workflow_initialized must be the first event.",
+    )
+
+  spec_id = payload.get("spec_id", state.spec_id)
+  change = payload.get("change", state.change)
+  created_at = payload.get("created_at", event.timestamp)
+  if not isinstance(spec_id, str):
+    raise _event_error(event, "spec_id must be a string.")
+  if not isinstance(change, str):
+    raise _event_error(event, "change must be a string.")
+  if not isinstance(created_at, str) or not created_at:
+    raise _event_error(event, "created_at must be a non-empty string.")
+
+  state.version = version_value
+  state.spec_id = spec_id
+  state.change = change
+  state.created_at = created_at
+  state.status = status_value
+
+
+def _apply_transition(
+  state: WorkflowState,
+  event: WorkflowEvent,
+) -> None:
+  target_value = event.payload.get("to")
+  if not isinstance(target_value, str) or target_value not in WORKFLOW_STATUSES:
+    raise _event_error(
+      event,
+      f"unknown workflow target: {target_value!r}.",
+    )
+  try:
+    ensure_transition(state.status, target_value)
+  except InvalidTransitionError as error:
+    raise _event_error(
+      event,
+      f"invalid workflow transition {state.status} -> {target_value}.",
+    ) from error
+  state.status = target_value
+
+
+def _apply_artifact_event(
+  state: WorkflowState,
+  event: WorkflowEvent,
+  stage: str,
+  suffix: str,
+) -> None:
+  payload = event.payload
+  payload_stage = payload.get("stage")
+  if payload_stage != stage:
+    raise _event_error(
+      event,
+      f"payload stage {payload_stage!r} does not match event type.",
+    )
+
+  kind_value = payload.get("kind", stage)
+  if (
+    not isinstance(kind_value, str)
+    or kind_value not in STAGE_ARTIFACTS[stage]
+  ):
+    raise _event_error(
+      event,
+      f"artifact kind {kind_value!r} does not belong to {stage}.",
+    )
+  kind = kind_value
+  previous = state.artifacts.get(kind)
+
+  path_value = payload.get("path", "")
+  if path_value is None:
+    path_value = ""
+  if not isinstance(path_value, str):
+    raise _event_error(event, "artifact path must be a string.")
+  path = path_value
+
+  digest_value = payload.get("digest", "")
+  if not isinstance(digest_value, str):
+    raise _event_error(event, "artifact digest must be a string.")
+  digest = _validated_digest(
+    event,
+    digest_value,
+    allow_empty=suffix == ArtifactStatus.STALE.value,
+  )
+
+  source_value = payload.get(
+    "source",
+    previous.source if previous is not None else "system",
+  )
+  if (
+    not isinstance(source_value, str)
+    or source_value not in ARTIFACT_SOURCES
+  ):
+    raise _event_error(
+      event,
+      f"unknown artifact source: {source_value!r}.",
+    )
+
+  metadata_value = payload.get("metadata", {})
+  if metadata_value is None:
+    metadata_value = {}
+  if not isinstance(metadata_value, dict):
+    raise _event_error(event, "artifact metadata must be a mapping.")
+
+  version_value = payload.get("version", 0)
+  if (
+    isinstance(version_value, bool)
+    or not isinstance(version_value, int)
+    or version_value < 0
+  ):
+    raise _event_error(event, "artifact version must be a positive integer.")
+
+  if suffix == ArtifactStatus.STALE.value:
+    _apply_stale_event(
+      state,
+      event,
+      kind=kind,
+      digest=digest,
+      previous=previous,
+    )
+    return
+
+  if not path:
+    raise _event_error(event, "artifact event is missing its path.")
+
+  if suffix == ArtifactStatus.GENERATED.value:
+    if previous is not None and previous.status == ArtifactStatus.APPROVED.value:
+      raise _event_error(
+        event,
+        f"artifact {kind!r} must be marked stale before regeneration.",
+      )
+  elif suffix == ArtifactStatus.VALIDATED.value:
+    if previous is None:
+      raise _event_error(
+        event,
+        f"cannot validate unknown artifact {kind!r}.",
+      )
+    if previous.digest != digest:
+      raise _event_error(
+        event,
+        f"validated digest for {kind!r} does not match the generated digest.",
+      )
+    if previous.status not in {
+      ArtifactStatus.GENERATED.value,
+      ArtifactStatus.VALIDATED.value,
+    }:
+      raise _event_error(
+        event,
+        f"artifact {kind!r} is {previous.status}, not generated.",
+      )
+  elif suffix == ArtifactStatus.REJECTED.value:
+    if previous is None:
+      raise _event_error(
+        event,
+        f"cannot reject unknown artifact {kind!r}.",
+      )
+    if previous.digest != digest:
+      raise _event_error(
+        event,
+        f"rejected digest for {kind!r} does not match the current digest.",
+      )
+    if previous.status not in {
+      ArtifactStatus.GENERATED.value,
+      ArtifactStatus.VALIDATED.value,
+    }:
+      raise _event_error(
+        event,
+        f"artifact {kind!r} is {previous.status} and cannot be rejected.",
+      )
+
+  version = version_value
+  if version < 1:
+    if previous is None:
+      version = 1
+    elif previous.digest != digest:
+      version = previous.version + 1
+    else:
+      version = previous.version
+
+  status = _EVENT_STATUSES[suffix]
+  record = ArtifactRecord(
+    kind=kind,
+    path=path,
+    digest=digest,
+    status=status,
+    source=source_value,
+    version=version,
+    updated_at=event.timestamp,
+    validated_at=(
+      event.timestamp
+      if status == ArtifactStatus.VALIDATED.value
+      else ""
+    ),
+    approved_at="",
+    stale_at="",
+    metadata={
+      **(previous.metadata if previous is not None else {}),
+      **metadata_value,
+    },
+  )
+  state.artifacts[kind] = record
+  if suffix in {
+    ArtifactStatus.GENERATED.value,
+    ArtifactStatus.VALIDATED.value,
+    ArtifactStatus.REJECTED.value,
+  }:
+    state.approvals.pop(stage, None)
+
+
+def _apply_stale_event(
+  state: WorkflowState,
+  event: WorkflowEvent,
+  *,
+  kind: str,
+  digest: str,
+  previous: ArtifactRecord | None,
+) -> None:
+  if previous is None:
+    raise _event_error(
+      event,
+      f"stale event for unknown artifact {kind!r}.",
+    )
+  if previous.status == ArtifactStatus.STALE.value:
+    raise _event_error(event, f"artifact {kind!r} is already stale.")
+
+  previous_digest_value = event.payload.get("previous_digest")
+  if previous_digest_value is not None:
+    if not isinstance(previous_digest_value, str):
+      raise _event_error(event, "previous_digest must be a string.")
+    previous_digest = _validated_digest(
+      event,
+      previous_digest_value,
+      field="previous_digest",
+    )
+    if previous_digest != previous.digest:
+      raise _event_error(
+        event,
+        f"previous_digest for {kind!r} does not match the current digest.",
+      )
+
+  state.artifacts[kind] = replace(
+    previous,
+    status=ArtifactStatus.STALE.value,
+    stale_at=event.timestamp,
+    updated_at=event.timestamp,
+    metadata={
+      **previous.metadata,
+      "observed_digest": digest,
+    },
+  )
+
+
+def _apply_approval(
+  state: WorkflowState,
+  event: WorkflowEvent,
+  stage: str,
+) -> None:
+  payload = event.payload
+  payload_stage = payload.get("stage")
+  if payload_stage != stage:
+    raise _event_error(
+      event,
+      f"payload stage {payload_stage!r} does not match event type.",
+    )
+  if stage in state.approvals:
+    raise _event_error(event, f"stage {stage!r} is already approved.")
+
+  target_value = payload.get("workflow_status")
+  if not isinstance(target_value, str) or not target_value:
+    raise _event_error(
+      event,
+      "approval event is missing workflow_status.",
+    )
+  expected_target = STAGE_TARGETS.get(stage)
+  if target_value != expected_target:
+    raise _event_error(
+      event,
+      f"approval target {target_value!r} is not {expected_target!r}.",
+    )
+
+  artifacts_value = payload.get("artifacts")
+  if not isinstance(artifacts_value, dict) or not artifacts_value:
+    raise _event_error(
+      event,
+      f"approval event for {stage!r} has no artifact digests.",
+    )
+  required_kinds = set(STAGE_ARTIFACTS[stage])
+  optional_kinds = set(STAGE_OPTIONAL_ARTIFACTS.get(stage, ()))
+  actual_kinds = set(artifacts_value)
+  if not required_kinds <= actual_kinds:
+    missing = ", ".join(sorted(required_kinds - actual_kinds))
+    raise _event_error(
+      event,
+      f"approval for {stage!r} is missing required artifacts: "
+      f"[{missing}].",
+    )
+  unknown = actual_kinds - required_kinds - optional_kinds
+  if unknown:
+    actual = ", ".join(sorted(str(key) for key in unknown))
+    allowed = ", ".join(sorted(required_kinds | optional_kinds))
+    raise _event_error(
+      event,
+      f"approval for {stage!r} binds unknown artifacts [{actual}]; "
+      f"allowed kinds are [{allowed}].",
+    )
+
+  replacements: dict[str, ArtifactRecord] = {}
+  bound: dict[str, str] = {}
+  for kind in sorted(actual_kinds):
+    digest = _validated_digest(
+      event,
+      artifacts_value.get(kind),
+      field=f"artifacts[{kind}]",
+    )
+    record = state.artifacts.get(kind)
+    if record is None:
+      raise _event_error(
+        event,
+        f"approval references unknown artifact {kind!r}.",
+      )
+    if record.digest != digest:
+      raise _event_error(
+        event,
+        f"approval for {kind!r} does not match its validated digest.",
+      )
+    if record.status != ArtifactStatus.VALIDATED.value:
+      raise _event_error(
+        event,
+        f"artifact {kind!r} is {record.status}, not validated.",
+      )
+    replacements[kind] = replace(
+      record,
+      digest=digest,
+      status=ArtifactStatus.APPROVED.value,
+      approved_at=event.timestamp,
+      updated_at=event.timestamp,
+      stale_at="",
+      metadata={
+        key: value
+        for key, value in record.metadata.items()
+        if key != "observed_digest"
+      },
+    )
+    bound[kind] = digest
+
+  architecture_value = payload.get("architecture_digest", "")
+  if architecture_value is None:
+    architecture_value = ""
+  if not isinstance(architecture_value, str):
+    raise _event_error(
+      event,
+      "architecture_digest must be a SHA-256 digest or empty.",
+    )
+  architecture_digest = ""
+  if architecture_value:
+    architecture_digest = _validated_digest(
+      event,
+      architecture_value,
+      field="architecture_digest",
+    )
+
+  by_value = payload.get("by", event.actor)
+  if not isinstance(by_value, str) or not by_value.strip():
+    raise _event_error(event, "approval author must be a non-empty string.")
+
+  try:
+    ensure_transition(state.status, target_value)
+  except InvalidTransitionError as error:
+    raise _event_error(
+      event,
+      f"invalid workflow transition {state.status} -> {target_value}.",
+    ) from error
+
+  approval = ApprovalRecord(
+    stage=stage,
+    by=by_value,
+    at=event.timestamp,
+    artifacts=bound,
+    architecture_digest=architecture_digest,
+  )
+  for kind, record in replacements.items():
+    state.artifacts[kind] = record
+  state.approvals[stage] = approval
+  state.status = target_value
+
+
+def _event_error(
+  event: WorkflowEvent,
+  reason: str,
+) -> InvalidEventLogError:
+  return InvalidEventLogError(
+    f"Invalid event {event.event_id} "
+    f"(seq {event.seq}, type {event.type}): {reason}"
+  )
+
+
+def _validated_digest(
+  event: WorkflowEvent,
+  value: object,
+  *,
+  field: str = "digest",
+  allow_empty: bool = False,
+) -> str:
+  if not isinstance(value, str):
+    raise _event_error(event, f"{field} must be a SHA-256 digest.")
+  if allow_empty and value == "":
+    return ""
+  if not _SHA256_PATTERN.fullmatch(value):
+    raise _event_error(
+      event,
+      f"{field} is not a valid SHA-256 digest: {value!r}.",
+    )
+  return value
+
+
+def _required_text(value: object, field: str) -> str:
+  if not isinstance(value, str) or not value.strip():
+    msg = (
+      f"Workflow event field '{field}' must be a non-empty string."
+    )
+    raise InvalidEventLogError(msg)
+  return value
+
+
+def _optional_text(value: object, field: str) -> str | None:
+  if value is None:
+    return None
+  if not isinstance(value, str):
+    msg = f"Workflow event field '{field}' must be a string."
+    raise InvalidEventLogError(msg)
+  return value or None
+
+
+def _positive_int(value: object, field: str) -> int:
+  if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+    msg = f"Workflow event field '{field}' must be a positive integer."
+    raise InvalidEventLogError(msg)
+  return value