devflow-toolkit 0.3.0__py3-none-any.whl

devflow/core/state/manager.py

@@ -0,0 +1,960 @@
+"""Workflow state, approvals and append-only event projection."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from devflow.core.artifacts.errors import ArtifactError
+from devflow.core.artifacts.models import (
+  ARTIFACT_SOURCES,
+  ArtifactRecord,
+  ArtifactStatus,
+)
+from devflow.core.artifacts.store import ArtifactStore
+from devflow.core.architecture import ARCHITECTURE_RELATIVE_PATH
+from devflow.core.clock import (
+  Clock,
+  IdGenerator,
+  SystemClock,
+  UuidIdGenerator,
+  format_timestamp,
+)
+from devflow.core.discovery import (
+  DISCOVERY_FILENAME,
+  DiscoveryIncompleteError,
+  DiscoveryManager,
+)
+from devflow.core.state.errors import (
+  ArtifactNotValidatedError,
+  ChangeNotFoundError,
+  InvalidStateError,
+  StaleArtifactError,
+  StateError,
+  UnsupportedStageError,
+)
+from devflow.core.state.events import (
+  WORKFLOW_INITIALIZED,
+  WORKFLOW_TRANSITION,
+  WorkflowEvent,
+  append_event,
+  apply_event,
+  read_events,
+  replay_events,
+)
+from devflow.core.state.lock import ChangeLock
+from devflow.core.state.locator import (
+  ChangeLocation,
+  WorkflowLocator,
+)
+from devflow.core.state.models import (
+  STAGE_ARTIFACTS,
+  STAGE_TARGETS,
+  WORKFLOW_STATUSES,
+  ApprovalRecord,
+  WorkflowState,
+  WorkflowStatus,
+)
+from devflow.core.state.transitions import (
+  artifact_blockers,
+  ensure_transition,
+  required_artifacts,
+)
+
+_PROJECTION_HEADER = (
+  "# DevFlow workflow state.\n"
+  "# This file is a projection of events.jsonl and may be rebuilt.\n"
+)
+_ORPHAN_CANDIDATES = (
+  "discovery.yaml",
+  "spec.md",
+  "plan.md",
+  "tasks.yaml",
+  "review.md",
+)
+_TIMESTAMP_FIELDS = frozenset(
+  {
+    "created_at",
+    "updated_at",
+    "validated_at",
+    "approved_at",
+    "stale_at",
+    "at",
+  }
+)
+
+
+def _canonical_state(state: WorkflowState) -> Any:
+  """Return a representation-independent form of persisted state."""
+  return _canonical_value(state.to_dict())
+
+
+def _canonical_value(value: Any, *, timestamp: bool = False) -> Any:
+  if isinstance(value, dict):
+    return {
+      str(key): _canonical_value(
+        value[key],
+        timestamp=str(key) in _TIMESTAMP_FIELDS,
+      )
+      for key in sorted(value, key=lambda item: str(item))
+    }
+  if isinstance(value, (list, tuple)):
+    return [_canonical_value(item) for item in value]
+  if timestamp and isinstance(value, str):
+    return _canonical_timestamp(value)
+  return value
+
+
+def _canonical_timestamp(value: str) -> str:
+  if not value:
+    return value
+  try:
+    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+  except ValueError:
+    return value
+  if parsed.tzinfo is None:
+    parsed = parsed.replace(tzinfo=timezone.utc)
+  else:
+    parsed = parsed.astimezone(timezone.utc)
+  return parsed.isoformat(timespec="microseconds").replace("+00:00", "Z")
+
+
+@dataclass(frozen=True)
+class ChangeStatus:
+  """Current state and diagnostics for one change."""
+
+  location: ChangeLocation
+  state: WorkflowState
+  warnings: tuple[str, ...]
+  orphans: tuple[str, ...]
+  last_event: WorkflowEvent | None
+
+
+@dataclass(frozen=True)
+class ApprovalResult:
+  """Outcome of an approval operation."""
+
+  location: ChangeLocation
+  state: WorkflowState
+  stage: str
+  approval: ApprovalRecord
+  changed: bool
+  warnings: tuple[str, ...] = ()
+
+
+class WorkflowStateManager:
+  """Own workflow state, artifact registration and human approvals."""
+
+  def __init__(
+    self,
+    specs_path: Path,
+    *,
+    project_root: Path | None = None,
+    clock: Clock | None = None,
+    ids: IdGenerator | None = None,
+  ) -> None:
+    self.specs_path = specs_path.resolve()
+    self.root = (
+      project_root.resolve()
+      if project_root is not None
+      else self.specs_path.parent.parent
+    )
+    self.store = ArtifactStore(self.root)
+    self.locator = WorkflowLocator(self.specs_path)
+    self.clock = clock or SystemClock()
+    self.ids = ids or UuidIdGenerator()
+
+  def initialize_change(
+    self,
+    directory: Path,
+    *,
+    spec_id: str | None = None,
+    change: str | None = None,
+  ) -> WorkflowState:
+    """Create workflow metadata for a change if it does not exist."""
+    location = self.locator.from_directory(directory)
+    with self._lock(location):
+      if location.workflow_path.is_file() or location.events_path.is_file():
+        return self._load_state(location, persist=True)
+      return self._initialize_locked(
+        location,
+        spec_id=spec_id,
+        change=change,
+      )
+
+  def _initialize_locked(
+    self,
+    location: ChangeLocation,
+    *,
+    spec_id: str | None = None,
+    change: str | None = None,
+  ) -> WorkflowState:
+    location.directory.mkdir(parents=True, exist_ok=True)
+    location.runs_path.mkdir(parents=True, exist_ok=True)
+    state = WorkflowState(
+      spec_id=spec_id or location.spec_id,
+      change=change or location.change,
+    )
+    return self._append_and_save(
+      location,
+      state,
+      WORKFLOW_INITIALIZED,
+      {
+        "version": 1,
+        "spec_id": state.spec_id,
+        "change": state.change,
+        "status": WorkflowStatus.DRAFT.value,
+        "created_at": format_timestamp(self.clock.now()),
+      },
+      actor="devflow",
+      run_id=None,
+    )
+
+  def record_artifact(
+    self,
+    location: ChangeLocation,
+    *,
+    stage: str,
+    path: Path,
+    validated: bool,
+    source: str,
+    kind: str | None = None,
+    metadata: dict[str, Any] | None = None,
+    actor: str = "devflow",
+    run_id: str | None = None,
+  ) -> WorkflowState:
+    """Register a written artifact and optionally mark it validated."""
+    if stage not in STAGE_ARTIFACTS:
+      msg = (
+        f"Unknown workflow stage: {stage}. "
+        f"Supported values: {', '.join(STAGE_ARTIFACTS)}."
+      )
+      raise UnsupportedStageError(msg)
+    if source not in ARTIFACT_SOURCES:
+      source = "system"
+    artifact_kind = kind or stage
+    merged_metadata = {"stage": stage, **(metadata or {})}
+
+    with self._lock(location):
+      if (
+        not location.workflow_path.is_file()
+        and not location.events_path.is_file()
+      ):
+        self._initialize_locked(location)
+      state = self._load_state(location, persist=True)
+      relative = self._relative_artifact_path(path)
+      digest = self.store.digest_file(path)
+      existing = state.artifacts.get(artifact_kind)
+
+      if (
+        existing is not None
+        and existing.digest == digest
+        and all(
+          existing.metadata.get(key) == value
+          for key, value in merged_metadata.items()
+        )
+        and (
+          existing.status == ArtifactStatus.APPROVED.value
+          or (validated and existing.status == ArtifactStatus.VALIDATED.value)
+        )
+      ):
+        return state
+
+      if (
+        existing is not None
+        and existing.status == ArtifactStatus.APPROVED.value
+        and existing.digest != digest
+      ):
+        state = self._mark_stale(
+          location,
+          state,
+          stage=stage,
+          kind=artifact_kind,
+          observed_digest=digest,
+          actor=actor,
+          run_id=run_id,
+        )
+
+      state = self._append_and_save(
+        location,
+        state,
+        f"{stage}_generated",
+        {
+          "stage": stage,
+          "kind": artifact_kind,
+          "path": relative,
+          "digest": digest,
+          "source": source,
+          "metadata": merged_metadata,
+        },
+        actor=actor,
+        run_id=run_id,
+      )
+
+      if validated:
+        state = self._append_and_save(
+          location,
+          state,
+          f"{stage}_validated",
+          {
+            "stage": stage,
+            "kind": artifact_kind,
+            "path": relative,
+            "digest": digest,
+            "source": source,
+            "metadata": merged_metadata,
+          },
+          actor=actor,
+          run_id=run_id,
+        )
+      return state
+
+  def load(self, location: ChangeLocation) -> WorkflowState:
+    """Load, replay and reconcile the current state."""
+    return self.reconcile(location)
+
+  def reconcile(self, location: ChangeLocation) -> WorkflowState:
+    """Refresh artifact digests and mark changed artifacts as stale."""
+    with self._lock(location):
+      state = self._load_state(location, persist=True)
+      return self._reconcile_locked(location, state)
+
+  def status(self, location: ChangeLocation) -> ChangeStatus:
+    """Return the reconciled state and its diagnostics."""
+    state = self.reconcile(location)
+    events = read_events(location.events_path)
+    warnings, orphans = self._diagnostics(location, state)
+    return ChangeStatus(
+      location=location,
+      state=state,
+      warnings=warnings,
+      orphans=orphans,
+      last_event=events[-1] if events else None,
+    )
+
+  def transition(
+    self,
+    location: ChangeLocation,
+    target: str,
+    *,
+    actor: str = "devflow",
+    run_id: str | None = None,
+  ) -> WorkflowState:
+    """Move a workflow to a new state when the transition is allowed."""
+    with self._lock(location):
+      state = self._load_state(location, persist=True)
+      ensure_transition(state.status, target)
+      if state.status == target:
+        return state
+      return self._append_and_save(
+        location,
+        state,
+        WORKFLOW_TRANSITION,
+        {"to": target},
+        actor=actor,
+        run_id=run_id,
+      )
+
+  def invalidate_artifact(
+    self,
+    location: ChangeLocation,
+    *,
+    stage: str,
+    kind: str,
+    actor: str = "devflow",
+    run_id: str | None = None,
+  ) -> WorkflowState:
+    """Mark a registered artifact stale without changing its content."""
+    if stage not in STAGE_ARTIFACTS:
+      msg = (
+        f"Unknown workflow stage: {stage}. "
+        f"Supported values: {', '.join(STAGE_ARTIFACTS)}."
+      )
+      raise UnsupportedStageError(msg)
+    with self._lock(location):
+      state = self._load_state(location, persist=True)
+      state = self._reconcile_locked(location, state)
+      record = state.artifacts.get(kind)
+      if record is None or record.status == ArtifactStatus.STALE.value:
+        return state
+      try:
+        observed = self.store.digest_file(
+          self._artifact_path(record.path)
+        )
+      except ArtifactError:
+        observed = ""
+      return self._mark_stale(
+        location,
+        state,
+        stage=stage,
+        kind=kind,
+        observed_digest=observed,
+        actor=actor,
+        run_id=run_id,
+      )
+
+  def approve(
+    self,
+    location: ChangeLocation,
+    stage: str,
+    *,
+    by: str = "user",
+    actor: str | None = None,
+    run_id: str | None = None,
+  ) -> ApprovalResult:
+    """Approve the artifacts of a stage, bound to their digests."""
+    normalized = stage.strip().lower()
+    if normalized not in STAGE_ARTIFACTS:
+      msg = (
+        f"Unknown workflow stage: {stage}. "
+        f"Supported values: {', '.join(STAGE_ARTIFACTS)}."
+      )
+      raise UnsupportedStageError(msg)
+    if normalized not in STAGE_TARGETS:
+      msg = f"Stage '{stage}' cannot be approved."
+      raise UnsupportedStageError(msg)
+
+    warnings: list[str] = []
+
+    with self._lock(location):
+      state = self._load_state(location, persist=True)
+      state = self._reconcile_locked(location, state)
+      kinds = STAGE_ARTIFACTS[normalized]
+      digests: dict[str, str] = {}
+      discovery_digest = ""
+
+      if normalized == "spec":
+        discovery_path = location.directory / DISCOVERY_FILENAME
+        if discovery_path.exists() or discovery_path.is_symlink():
+          discovery = DiscoveryManager(self.root).load(
+            location.directory,
+            required=True,
+          )
+          if discovery is None or not discovery.is_complete:
+            blockers = (
+              discovery.blockers()
+              if discovery is not None
+              else ("Discovery is missing.",)
+            )
+            msg = (
+              "Cannot approve stage 'spec': discovery is not complete. "
+              "Resolve: "
+              + "; ".join(blockers).rstrip(".")
+              + ". Then run 'devflow spec --continue "
+              + location.spec_id
+              + "'."
+            )
+            raise DiscoveryIncompleteError(msg)
+          try:
+            discovery_digest = self.store.digest_file(discovery_path)
+          except ArtifactError as error:
+            msg = (
+              "Cannot approve stage 'spec': discovery.yaml cannot be "
+              "read. Regenerate discovery first."
+            )
+            raise StaleArtifactError(msg) from error
+
+          discovery_record = state.artifacts.get("discovery")
+          if discovery_record is None:
+            msg = (
+              "Cannot approve stage 'spec': discovery is not registered "
+              "in the workflow. Run 'devflow spec --continue "
+              f"{location.spec_id}' to register it."
+            )
+            raise ArtifactNotValidatedError(msg)
+          self._ensure_artifact_current(
+            location,
+            state,
+            normalized,
+            "discovery",
+            discovery_record,
+            actor or by,
+            run_id,
+          )
+          if discovery_record.status not in {
+            ArtifactStatus.VALIDATED.value,
+            ArtifactStatus.APPROVED.value,
+          }:
+            msg = (
+              "Cannot approve stage 'spec': discovery is "
+              f"{discovery_record.status}, not validated."
+            )
+            raise ArtifactNotValidatedError(msg)
+          digests["discovery"] = discovery_digest
+        else:
+          warnings.append(
+            "This change has no discovery.yaml. It is approved as a "
+            "legacy 0.2.0 change."
+          )
+
+      for kind in kinds:
+        record = state.artifacts.get(kind)
+        if record is None:
+          msg = (
+            f"Cannot approve stage '{normalized}': artifact "
+            f"'{kind}' is not registered for {location.change}."
+          )
+          raise ArtifactNotValidatedError(msg)
+        self._ensure_artifact_current(
+          location,
+          state,
+          normalized,
+          kind,
+          record,
+          actor or by,
+          run_id,
+        )
+        if record.status not in {
+          ArtifactStatus.VALIDATED.value,
+          ArtifactStatus.APPROVED.value,
+        }:
+          msg = (
+            f"Cannot approve stage '{normalized}': artifact "
+            f"'{kind}' is {record.status}, not validated."
+          )
+          raise ArtifactNotValidatedError(msg)
+        digests[kind] = record.digest
+
+      spec_record = state.artifacts.get("spec")
+      architecture_digest = ""
+      if spec_record is not None:
+        architecture_digest = str(
+          spec_record.metadata.get("architecture_digest", "")
+        )
+        if architecture_digest:
+          manifest_path = self.root / ARCHITECTURE_RELATIVE_PATH
+          try:
+            current_manifest = self.store.digest_file(manifest_path)
+          except ArtifactError as error:
+            msg = (
+              "Cannot approve stage 'spec': the declared architecture "
+              "manifest is missing. Restore it or regenerate the "
+              "specification."
+            )
+            raise StaleArtifactError(msg) from error
+          if current_manifest != architecture_digest:
+            msg = (
+              "Cannot approve stage 'spec': the declared architecture "
+              "manifest changed after the specification was generated. "
+              f"Run 'devflow spec --continue {location.spec_id}' to "
+              "regenerate it."
+            )
+            raise StaleArtifactError(msg)
+        if discovery_digest:
+          recorded_discovery = str(
+            spec_record.metadata.get("discovery_digest", "")
+          )
+          if recorded_discovery != discovery_digest:
+            msg = (
+              "Cannot approve stage 'spec': discovery changed after the "
+              "specification was generated. Run 'devflow spec --continue "
+              f"{location.spec_id}' to regenerate it."
+            )
+            raise ArtifactNotValidatedError(msg)
+
+      existing = state.approvals.get(normalized)
+      if existing is not None:
+        if (
+          existing.artifacts == digests
+          and existing.architecture_digest == architecture_digest
+          and all(
+            state.artifacts[kind].status
+            == ArtifactStatus.APPROVED.value
+            for kind in digests
+          )
+        ):
+          return ApprovalResult(
+            location=location,
+            state=state,
+            stage=normalized,
+            approval=existing,
+            changed=False,
+            warnings=tuple(warnings),
+          )
+        msg = (
+          f"Cannot approve stage '{normalized}': it is already approved "
+          "with different artifacts. Start a new change or request an "
+          "explicit revision."
+        )
+        raise StateError(msg)
+
+      if state.status == WorkflowStatus.AWAITING_CLARIFICATION.value:
+        state = self._append_and_save(
+          location,
+          state,
+          WORKFLOW_TRANSITION,
+          {"to": WorkflowStatus.DRAFT.value},
+          actor=actor or by,
+          run_id=run_id,
+        )
+
+      target = STAGE_TARGETS[normalized]
+      if state.status != target:
+        ensure_transition(state.status, target)
+      blockers = self._approval_blockers(
+        state,
+        target,
+        tuple(digests),
+      )
+      if blockers:
+        msg = (
+          f"Cannot approve stage '{normalized}': required artifacts "
+          "are not approved: " + ", ".join(blockers) + "."
+        )
+        raise ArtifactNotValidatedError(msg)
+
+      payload: dict[str, Any] = {
+        "stage": normalized,
+        "by": by,
+        "artifacts": digests,
+        "workflow_status": target,
+      }
+      if architecture_digest:
+        payload["architecture_digest"] = architecture_digest
+      state = self._append_and_save(
+        location,
+        state,
+        f"{normalized}_approved",
+        payload,
+        actor=actor or by,
+        run_id=run_id,
+      )
+      return ApprovalResult(
+        location=location,
+        state=state,
+        stage=normalized,
+        approval=state.approvals[normalized],
+        changed=True,
+        warnings=tuple(warnings),
+      )
+
+  def _ensure_artifact_current(
+    self,
+    location: ChangeLocation,
+    state: WorkflowState,
+    stage: str,
+    kind: str,
+    record: ArtifactRecord,
+    actor: str,
+    run_id: str | None,
+  ) -> None:
+    """Raise when a registered artifact no longer matches its digest."""
+    if record.status == ArtifactStatus.STALE.value:
+      msg = (
+        f"Cannot approve stage '{stage}': artifact '{kind}' is stale. "
+        "Regenerate and validate it first."
+      )
+      raise StaleArtifactError(msg)
+    try:
+      current_digest = self.store.digest_file(
+        self._artifact_path(record.path)
+      )
+    except ArtifactError as error:
+      msg = (
+        f"Cannot approve stage '{stage}': artifact '{kind}' cannot be "
+        "read. Regenerate it first."
+      )
+      raise StaleArtifactError(msg) from error
+    if current_digest == record.digest:
+      return
+    self._mark_stale(
+      location,
+      state,
+      stage=stage,
+      kind=kind,
+      observed_digest=current_digest,
+      actor=actor,
+      run_id=run_id,
+    )
+    msg = (
+      f"Cannot approve stage '{stage}': artifact '{kind}' changed after "
+      "validation. Regenerate and validate it before approving."
+    )
+    raise StaleArtifactError(msg)
+
+  def _reconcile_locked(
+    self,
+    location: ChangeLocation,
+    state: WorkflowState,
+  ) -> WorkflowState:
+    for kind, record in sorted(state.artifacts.items()):
+      if record.status == ArtifactStatus.STALE.value:
+        continue
+      try:
+        current_digest = self.store.digest_file(
+          self._artifact_path(record.path)
+        )
+      except ArtifactError:
+        current_digest = ""
+      if current_digest == record.digest:
+        continue
+      state = self._mark_stale(
+        location,
+        state,
+        stage=record.metadata.get("stage", kind),
+        kind=kind,
+        observed_digest=current_digest,
+        actor="devflow",
+        run_id=None,
+      )
+    return state
+
+  def _mark_stale(
+    self,
+    location: ChangeLocation,
+    state: WorkflowState,
+    *,
+    stage: str,
+    kind: str,
+    observed_digest: str,
+    actor: str,
+    run_id: str | None,
+  ) -> WorkflowState:
+    record = state.artifacts.get(kind)
+    if record is None or record.status == ArtifactStatus.STALE.value:
+      return state
+    return self._append_and_save(
+      location,
+      state,
+      f"{stage}_stale",
+      {
+        "stage": stage,
+        "kind": kind,
+        "path": record.path,
+        "digest": observed_digest,
+        "previous_digest": record.digest,
+      },
+      actor=actor,
+      run_id=run_id,
+    )
+
+  def _approval_blockers(
+    self,
+    state: WorkflowState,
+    target: str,
+    approving: tuple[str, ...],
+  ) -> tuple[str, ...]:
+    blockers: list[str] = []
+    for kind in required_artifacts(target):
+      record = state.artifacts.get(kind)
+      if record is None:
+        blockers.append(f"{kind} (missing)")
+      elif kind in approving:
+        if record.status not in {
+          ArtifactStatus.VALIDATED.value,
+          ArtifactStatus.APPROVED.value,
+        }:
+          blockers.append(f"{kind} ({record.status})")
+      elif record.status != ArtifactStatus.APPROVED.value:
+        blockers.append(f"{kind} ({record.status})")
+    return tuple(blockers)
+
+  def _diagnostics(
+    self,
+    location: ChangeLocation,
+    state: WorkflowState,
+  ) -> tuple[tuple[str, ...], tuple[str, ...]]:
+    warnings: list[str] = []
+    for kind, record in sorted(state.artifacts.items()):
+      try:
+        current_digest = self.store.digest_file(
+          self._artifact_path(record.path)
+        )
+      except ArtifactError:
+        warnings.append(
+          f"Artifact '{kind}' is registered but missing from disk."
+        )
+        continue
+      if record.status == ArtifactStatus.STALE.value:
+        warnings.append(
+          f"Artifact '{kind}' changed after validation or approval."
+        )
+      elif current_digest != record.digest:
+        warnings.append(
+          f"Artifact '{kind}' no longer matches its recorded digest."
+        )
+
+    orphans: list[str] = []
+    for name in _ORPHAN_CANDIDATES:
+      candidate = location.directory / name
+      key = _KIND_BY_FILENAME.get(name, name)
+      if candidate.is_file() and key not in state.artifacts:
+        orphans.append(name)
+        warnings.append(
+          f"Artifact '{name}' exists but is not registered in "
+          "events.jsonl."
+        )
+
+    discovery_record = state.artifacts.get("discovery")
+    if state.status == WorkflowStatus.AWAITING_CLARIFICATION.value:
+      if discovery_record is None:
+        warnings.append(
+          "Workflow is awaiting clarification but discovery is not "
+          "registered."
+        )
+      elif discovery_record.status != ArtifactStatus.VALIDATED.value:
+        warnings.append(
+          "Workflow is awaiting clarification until discovery is "
+          "complete."
+        )
+    elif (
+      discovery_record is not None
+      and discovery_record.status == ArtifactStatus.GENERATED.value
+    ):
+      warnings.append(
+        "Discovery is registered but not complete; the specification "
+        "must not be approved."
+      )
+
+    if state.status != WorkflowStatus.DRAFT.value:
+      blockers = artifact_blockers(state, state.status)
+      if blockers:
+        warnings.append(
+          f"Workflow is blocked in '{state.status}': "
+          + ", ".join(blockers)
+          + "."
+        )
+    return tuple(warnings), tuple(orphans)
+
+  def _load_state(
+    self,
+    location: ChangeLocation,
+    *,
+    persist: bool,
+  ) -> WorkflowState:
+    if not location.directory.is_dir():
+      msg = f"Change directory does not exist: {location.directory}"
+      raise ChangeNotFoundError(msg)
+
+    events = read_events(location.events_path)
+    state = replay_events(events)
+
+    if not events:
+      if location.workflow_path.is_file():
+        msg = (
+          "State projection exists without an event log: "
+          f"{location.workflow_path}"
+        )
+        raise InvalidStateError(msg)
+      msg = (
+        f"No workflow state found for {location.change}. "
+        "Run 'devflow spec' first."
+      )
+      raise ChangeNotFoundError(msg)
+
+    projection = (
+      self._read_projection(location)
+      if location.workflow_path.is_file()
+      else None
+    )
+    if (
+      projection is not None
+      and projection.last_event_seq > state.last_event_seq
+    ):
+      msg = (
+        "State projection references events that are missing from "
+        f"the event log: {location.workflow_path}"
+      )
+      raise InvalidStateError(msg)
+
+    if persist and (
+      projection is None
+      or _canonical_state(projection) != _canonical_state(state)
+    ):
+      self._write_projection(location, state)
+    return state
+
+  def _append_and_save(
+    self,
+    location: ChangeLocation,
+    state: WorkflowState,
+    event_type: str,
+    payload: dict[str, Any],
+    *,
+    actor: str,
+    run_id: str | None,
+  ) -> WorkflowState:
+    event = WorkflowEvent(
+      seq=state.last_event_seq + 1,
+      event_id=self.ids.new_id("evt"),
+      type=event_type,
+      timestamp=format_timestamp(self.clock.now()),
+      actor=actor,
+      run_id=run_id,
+      payload=payload,
+    )
+    append_event(location.events_path, event)
+    apply_event(state, event)
+    self._write_projection(location, state)
+    return state
+
+  def _read_projection(self, location: ChangeLocation) -> WorkflowState:
+    try:
+      with location.workflow_path.open(encoding="utf-8") as handle:
+        data = yaml.safe_load(handle)
+    except OSError as error:
+      msg = f"Could not read workflow state: {location.workflow_path}"
+      raise InvalidStateError(msg) from error
+    except yaml.YAMLError as error:
+      msg = f"Invalid YAML in workflow state: {location.workflow_path}"
+      raise InvalidStateError(msg) from error
+    if not isinstance(data, dict):
+      msg = "workflow.yaml must contain a mapping."
+      raise InvalidStateError(msg)
+    try:
+      state = WorkflowState.from_dict(data)
+    except (KeyError, TypeError, ValueError) as error:
+      msg = f"Invalid workflow state: {location.workflow_path}"
+      raise InvalidStateError(msg) from error
+    if state.status not in WORKFLOW_STATUSES:
+      msg = (
+        f"Unknown workflow status '{state.status}' in "
+        f"{location.workflow_path}"
+      )
+      raise InvalidStateError(msg)
+    return state
+
+  def _write_projection(
+    self,
+    location: ChangeLocation,
+    state: WorkflowState,
+  ) -> None:
+    content = _PROJECTION_HEADER + yaml.safe_dump(
+      state.to_dict(),
+      sort_keys=False,
+      allow_unicode=True,
+    )
+    self.store.write(location.workflow_path, content)
+
+  def _lock(self, location: ChangeLocation) -> ChangeLock:
+    return ChangeLock(location.lock_path, change=location.change)
+
+  def _artifact_path(self, relative: str) -> Path:
+    path = (self.root / relative).resolve()
+    try:
+      path.relative_to(self.root)
+    except ValueError as error:
+      msg = f"Artifact path escapes the project root: {relative}"
+      raise StateError(msg) from error
+    return path
+
+  def _relative_artifact_path(self, path: Path) -> str:
+    resolved = path.resolve()
+    try:
+      return resolved.relative_to(self.root).as_posix()
+    except ValueError as error:
+      msg = f"Artifact path escapes the project root: {path}"
+      raise StateError(msg) from error
+
+
+_KIND_BY_FILENAME = {
+  "discovery.yaml": "discovery",
+  "spec.md": "spec",
+  "plan.md": "plan",
+  "tasks.yaml": "tasks",
+  "review.md": "review",
+}