forge-autonomy 2.3.1__py3-none-any.whl

forge/capabilities/delegation.py

@@ -0,0 +1,150 @@
+"""Deterministic capability assessment and delegated-work records.
+
+The registry describes available execution capabilities.  It never invokes a
+provider: Forge retains the Mission and records only the bounded Engineering
+Action it asks another provider to complete.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from enum import Enum
+from typing import Mapping
+
+
+CAPABILITY_REGISTRY_SCHEMA_VERSION = "1.0"
+DELEGATION_SCHEMA_VERSION = "1.0"
+
+
+class CapabilityAvailability(str, Enum):
+    AVAILABLE = "available"
+    UNAVAILABLE = "unavailable"
+
+
+class CapabilityOwner(str, Enum):
+    FORGE = "internal_forge"
+    HUMAN = "human"
+    EXTERNAL_FORGE_RUNNER = "external_forge_runner"
+    EXTERNAL_AI_AGENT = "external_ai_agent"
+    EXTERNAL_APPLICATION = "external_application"
+    PROFESSIONAL_SERVICE = "professional_service"
+
+
+class CapabilityExecutionMode(str, Enum):
+    INTERNAL = "internal"
+    DELEGATED = "delegated"
+
+
+class DelegationApprovalState(str, Enum):
+    NOT_REQUIRED = "not_required"
+    PENDING = "pending"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+
+
+class DelegationResultState(str, Enum):
+    PENDING = "pending"
+    RECEIVED = "received"
+    ACCEPTED = "accepted"
+    REJECTED = "rejected"
+    ADDITIONAL_WORK_REQUIRED = "additional_work_required"
+
+
+@dataclass(frozen=True)
+class CapabilityRegistration:
+    id: str
+    name: str
+    owner: CapabilityOwner
+    availability: CapabilityAvailability
+    execution_mode: CapabilityExecutionMode
+    preferred_provider: CapabilityOwner
+    trust_level: str
+    approval_required: bool = False
+    schema_version: str = CAPABILITY_REGISTRY_SCHEMA_VERSION
+
+    def __post_init__(self) -> None:
+        if self.schema_version != CAPABILITY_REGISTRY_SCHEMA_VERSION or not all((self.id, self.name, self.trust_level)):
+            raise ValueError("capability registration requires supported version, identity, name, and trust level")
+        if self.execution_mode is CapabilityExecutionMode.INTERNAL and self.owner is not CapabilityOwner.FORGE:
+            raise ValueError("internal execution must be owned by Forge")
+
+    def to_dict(self) -> dict[str, object]:
+        document = asdict(self)
+        for name in ("owner", "availability", "execution_mode", "preferred_provider"):
+            document[name] = document[name].value  # type: ignore[union-attr]
+        return document
+
+
+@dataclass(frozen=True)
+class CapabilityAssessment:
+    capability_id: str
+    available: bool
+    execution_mode: CapabilityExecutionMode
+    selected_provider: CapabilityOwner
+    alternatives_considered: tuple[CapabilityOwner, ...]
+    rationale: str
+    confidence: int
+    approval_required: bool
+
+    def to_dict(self) -> dict[str, object]:
+        return {"capability_id": self.capability_id, "available": self.available,
+                "execution_mode": self.execution_mode.value, "selected_provider": self.selected_provider.value,
+                "alternatives_considered": [item.value for item in self.alternatives_considered],
+                "rationale": self.rationale, "confidence": self.confidence,
+                "approval_required": self.approval_required}
+
+
+class CapabilityRegistry:
+    """Immutable, deterministically ordered capability configuration."""
+
+    def __init__(self, registrations: tuple[CapabilityRegistration, ...]) -> None:
+        identifiers = [item.id for item in registrations]
+        if not registrations or len(identifiers) != len(set(identifiers)):
+            raise ValueError("capability registry requires uniquely identified registrations")
+        self._registrations = {item.id: item for item in registrations}
+
+    def assess(self, capability_id: str) -> CapabilityAssessment:
+        registration = self._registrations.get(capability_id)
+        if registration is None:
+            raise ValueError("required capability is not registered")
+        available = registration.availability is CapabilityAvailability.AVAILABLE and registration.execution_mode is CapabilityExecutionMode.INTERNAL
+        alternatives = tuple(sorted((owner for owner in CapabilityOwner if owner is not registration.preferred_provider), key=lambda item: item.value))
+        return CapabilityAssessment(
+            capability_id, available, registration.execution_mode,
+            CapabilityOwner.FORGE if available else registration.preferred_provider,
+            alternatives,
+            "internal capability available" if available else "required capability is unavailable for internal execution",
+            100 if available else 90, registration.approval_required,
+        )
+
+
+@dataclass(frozen=True)
+class DelegationRequest:
+    id: str
+    mission_id: str
+    action_id: str
+    capability_id: str
+    provider: CapabilityOwner
+    reason: str
+    decision_evidence: tuple[str, ...]
+    requested_at: str
+    approval_state: DelegationApprovalState
+    alternatives_considered: tuple[CapabilityOwner, ...]
+    confidence: int
+    result_state: DelegationResultState = DelegationResultState.PENDING
+    verification: Mapping[str, object] | None = None
+    schema_version: str = DELEGATION_SCHEMA_VERSION
+
+    def __post_init__(self) -> None:
+        if self.schema_version != DELEGATION_SCHEMA_VERSION or not all((self.id, self.mission_id, self.action_id, self.capability_id, self.reason, self.requested_at)):
+            raise ValueError("delegation request requires complete identity, rationale, and timestamp")
+        if not 0 <= self.confidence <= 100:
+            raise ValueError("delegation confidence must be between 0 and 100")
+
+    def to_dict(self) -> dict[str, object]:
+        document = asdict(self)
+        document["provider"] = self.provider.value
+        document["approval_state"] = self.approval_state.value
+        document["result_state"] = self.result_state.value
+        document["alternatives_considered"] = [item.value for item in self.alternatives_considered]
+        return document

forge/completion/__init__.py

@@ -0,0 +1,5 @@
+"""Deterministic, local-only phase completion assessment."""
+
+from .assessor import PhaseCompletionAssessor
+
+__all__ = ["PhaseCompletionAssessor"]

forge/completion/assessor.py

@@ -0,0 +1,53 @@
+"""Pure deterministic assessment of declared Phase Completion 1.0 evidence."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from forge.models import (
+    AssessmentFinding,
+    AssessmentStatus,
+    CompletionEvidence,
+    CriterionOutcome,
+    EngineeringPhase,
+    PhaseAssessment,
+)
+
+
+class PhaseCompletionAssessor:
+    """Assess declared evidence only; never fetch, invent, or mutate evidence."""
+
+    def assess(self, phase: EngineeringPhase, evidence: Iterable[CompletionEvidence]) -> PhaseAssessment:
+        declared = tuple(evidence)
+        criterion_ids = {criterion.id for criterion in phase.criteria}
+        evidence_by_criterion: dict[str, list[CompletionEvidence]] = {}
+        findings: list[AssessmentFinding] = []
+        for item in declared:
+            if item.criterion_id not in criterion_ids:
+                findings.append(AssessmentFinding(item.criterion_id, "UNKNOWN_CRITERION", "Evidence references no declared phase criterion."))
+                continue
+            evidence_by_criterion.setdefault(item.criterion_id, []).append(item)
+
+        has_criterion_evidence = bool(evidence_by_criterion)
+        for criterion in phase.criteria:
+            if not criterion.required:
+                continue
+            criterion_evidence = evidence_by_criterion.get(criterion.id, [])
+            if not criterion_evidence:
+                findings.append(AssessmentFinding(criterion.id, "MISSING_EVIDENCE", "Required criterion has no declared evidence."))
+            elif any(item.outcome is CriterionOutcome.FAIL for item in criterion_evidence):
+                findings.append(AssessmentFinding(criterion.id, "FAILED_CRITERION", "Required criterion has declared failing evidence."))
+            elif not any(item.outcome is CriterionOutcome.PASS for item in criterion_evidence):
+                findings.append(AssessmentFinding(criterion.id, "UNRESOLVED_CRITERION", "Required criterion has no passing evidence."))
+
+        ordered_findings = tuple(sorted(findings))
+        required_unresolved = any(finding.code != "UNKNOWN_CRITERION" for finding in ordered_findings)
+        if not has_criterion_evidence:
+            status = AssessmentStatus.NOT_STARTED
+        elif required_unresolved or any(finding.code == "UNKNOWN_CRITERION" for finding in ordered_findings):
+            status = AssessmentStatus.IN_PROGRESS
+        elif phase.completion_declaration is None:
+            status = AssessmentStatus.READY
+        else:
+            status = AssessmentStatus.COMPLETE
+        return PhaseAssessment(phase.id, status, ordered_findings)

forge/constitutional/__init__.py

@@ -0,0 +1,5 @@
+"""Pure Constitutional Validation assessment capability."""
+
+from .assessor import ConstitutionalAssessor
+
+__all__ = ["ConstitutionalAssessor"]

forge/constitutional/assessor.py

@@ -0,0 +1,38 @@
+"""Pure deterministic assessment of declared Constitutional Validation input."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from forge.models import (
+    ConstitutionalAssessment,
+    ConstitutionalAssessmentStatus,
+    ConstitutionalFinding,
+    ConstitutionalFindingSeverity,
+    ConstitutionalRule,
+)
+
+
+class ConstitutionalAssessor:
+    """Assess supplied architectural findings; never retrieve, enforce, or mutate."""
+
+    def assess(
+        self,
+        subject_id: str,
+        applicable_rules: Iterable[ConstitutionalRule],
+        findings: Iterable[ConstitutionalFinding],
+    ) -> ConstitutionalAssessment:
+        """Derive an assessment with fixed severity precedence and stable ordering."""
+        rules = tuple(sorted(applicable_rules))
+        ordered_findings = tuple(sorted(findings))
+        if not rules:
+            if ordered_findings:
+                raise ValueError("constitutional findings require at least one applicable rule")
+            status = ConstitutionalAssessmentStatus.NOT_APPLICABLE
+        elif any(finding.severity is ConstitutionalFindingSeverity.VIOLATION for finding in ordered_findings):
+            status = ConstitutionalAssessmentStatus.VIOLATION
+        elif ordered_findings:
+            status = ConstitutionalAssessmentStatus.WARNING
+        else:
+            status = ConstitutionalAssessmentStatus.PASS
+        return ConstitutionalAssessment(subject_id, rules, status, ordered_findings)

forge/core/__init__.py

@@ -0,0 +1,5 @@
+"""Core local persistence primitives."""
+
+from .json_store import JsonStore
+
+__all__ = ["JsonStore"]

forge/core/json_store.py

@@ -0,0 +1,24 @@
+"""Deterministic, human-readable local JSON persistence for foundation data."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+
+class JsonStore:
+    """Persist a single document locally without database or network dependencies."""
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+
+    def save(self, document: Mapping[str, Any]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(
+            json.dumps(document, indent=2, sort_keys=True, ensure_ascii=False) + "\n",
+            encoding="utf-8",
+        )
+
+    def load(self) -> dict[str, Any]:
+        return json.loads(self.path.read_text(encoding="utf-8"))

forge/decision_evidence/__init__.py

@@ -0,0 +1,5 @@
+"""Decision Evidence public repository contracts."""
+
+from .repository import DecisionEvidenceRepository, DecisionEvidenceRepositoryError
+
+__all__ = ["DecisionEvidenceRepository", "DecisionEvidenceRepositoryError"]

forge/decision_evidence/repository.py

@@ -0,0 +1,68 @@
+"""Append-only local Repository Truth store for immutable Decision Evidence."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+from typing import Callable
+
+from forge.models.decision_evidence import DecisionEvidence, DecisionReference
+
+
+class DecisionEvidenceRepositoryError(ValueError):
+    pass
+
+
+class DecisionEvidenceRepository:
+    """Persists one immutable document per decision and rejects unresolved references."""
+
+    def __init__(self, path: Path, *, reference_resolver: Callable[[DecisionReference], bool]) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self._connection = sqlite3.connect(path)
+        self._connection.row_factory = sqlite3.Row
+        self._reference_resolver = reference_resolver
+        self._connection.executescript("""
+            CREATE TABLE IF NOT EXISTS decision_evidence (
+              decision_id TEXT PRIMARY KEY, content_digest TEXT NOT NULL UNIQUE, document TEXT NOT NULL
+            );
+            CREATE TRIGGER IF NOT EXISTS decision_evidence_no_update BEFORE UPDATE ON decision_evidence
+            BEGIN SELECT RAISE(ABORT, 'decision evidence is immutable'); END;
+            CREATE TRIGGER IF NOT EXISTS decision_evidence_no_delete BEFORE DELETE ON decision_evidence
+            BEGIN SELECT RAISE(ABORT, 'decision evidence is immutable'); END;
+        """)
+        self._connection.commit()
+
+    def close(self) -> None:
+        self._connection.close()
+
+    def __enter__(self) -> "DecisionEvidenceRepository":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def append(self, evidence: DecisionEvidence) -> DecisionEvidence:
+        references = (evidence.repository_context, evidence.mission_context, evidence.repository_maturity_reference,
+                      *evidence.evidence_references, *evidence.execution_evidence_references,
+                      evidence.confidence.repository_truth, evidence.confidence.architecture_review,
+                      evidence.confidence.execution_evidence, evidence.confidence.mission_state)
+        if not all(self._reference_resolver(reference) for reference in references):
+            raise DecisionEvidenceRepositoryError("all Decision Evidence references must resolve to Repository Truth")
+        try:
+            with self._connection:
+                self._connection.execute("INSERT INTO decision_evidence VALUES (?, ?, ?)",
+                                         (evidence.id, evidence.content_digest, json.dumps(evidence.to_dict(), sort_keys=True, separators=(",", ":"), ensure_ascii=False)))
+        except sqlite3.IntegrityError as error:
+            raise DecisionEvidenceRepositoryError("decision evidence id or immutable content already exists") from error
+        return evidence
+
+    def get(self, decision_id: str) -> DecisionEvidence:
+        row = self._connection.execute("SELECT document FROM decision_evidence WHERE decision_id = ?", (decision_id,)).fetchone()
+        if row is None:
+            raise DecisionEvidenceRepositoryError(f"unknown decision evidence: {decision_id}")
+        return DecisionEvidence.from_dict(json.loads(row["document"]))
+
+    def list(self) -> tuple[DecisionEvidence, ...]:
+        rows = self._connection.execute("SELECT document FROM decision_evidence ORDER BY decision_id").fetchall()
+        return tuple(DecisionEvidence.from_dict(json.loads(row["document"])) for row in rows)

forge/dispatcher/__init__.py

@@ -0,0 +1,13 @@
+"""Approved Mission Queue and deterministic Mission Dispatcher."""
+
+from .dispatcher import (
+    BOOTSTRAP_MISSION_SEQUENCE,
+    ApprovedMissionQueue,
+    DispatcherStatus,
+    MissionDispatcher,
+    MissionDispatcherError,
+    MissionDispatcherStore,
+    MissionDispatchRecord,
+)
+
+__all__ = ["BOOTSTRAP_MISSION_SEQUENCE", "ApprovedMissionQueue", "DispatcherStatus", "MissionDispatcher", "MissionDispatcherError", "MissionDispatcherStore", "MissionDispatchRecord"]

forge/dispatcher/dispatcher.py

@@ -0,0 +1,194 @@
+"""Persistent, FIFO dispatch of Architecture-approved Missions only.
+
+This boundary activates Mission work.  It does not create Missions, plan
+Intents or Actions, render prompts, invoke an Execution Host, or execute.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+import sqlite3
+from pathlib import Path
+from typing import Callable, Protocol
+
+from forge.architecture import ArchitectureWorkspace
+from forge.intake import MissionIntake
+from forge.models.architecture_mission import ArchitectureMission
+from forge.state import MissionExecutionStatus, MissionStateStore
+
+# Historical portfolio identifier set retained for the bootstrap regression
+# harness only. It does not affect operational queue ordering.
+BOOTSTRAP_MISSION_SEQUENCE = ("MISSION-0001", "MISSION-0002", "MISSION-0003", "MISSION-0004", "MISSION-0005")
+
+
+class DispatcherStatus(str, Enum):
+    PENDING = "PENDING"
+    ACTIVE = "ACTIVE"
+    COMPLETED = "COMPLETED"
+    BLOCKED = "BLOCKED"
+    FAILED = "FAILED"
+    ARCHIVED = "ARCHIVED"
+
+
+class MissionDispatcherError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class MissionDispatchRecord:
+    mission_id: str
+    status: DispatcherStatus
+    sequence: int
+    occurred_at: str
+
+
+class CompletionHook(Protocol):
+    def __call__(self, mission_id: str) -> None: ...
+
+
+class ApprovedMissionQueue:
+    """A read-only, governance-filtered queue; recommendations never enter it."""
+
+    def __init__(self, workspace: ArchitectureWorkspace) -> None:
+        self._workspace = workspace
+
+    def missions(self) -> tuple[ArchitectureMission, ...]:
+        return self._workspace.approved_for_engineering()
+
+
+class MissionDispatcherStore:
+    """Local durable dispatcher lifecycle with a database-enforced one-active invariant."""
+
+    def __init__(self, path: Path) -> None:
+        self._connection = sqlite3.connect(path)
+        self._connection.row_factory = sqlite3.Row
+        self._connection.executescript("""
+            CREATE TABLE IF NOT EXISTS mission_dispatch (
+              mission_id TEXT PRIMARY KEY, status TEXT NOT NULL, sequence INTEGER NOT NULL, occurred_at TEXT NOT NULL
+            );
+            CREATE UNIQUE INDEX IF NOT EXISTS one_active_mission ON mission_dispatch(status) WHERE status = 'ACTIVE';
+        """)
+        self._connection.commit()
+
+    def close(self) -> None:
+        self._connection.close()
+
+    def active(self) -> MissionDispatchRecord | None:
+        row = self._connection.execute("SELECT * FROM mission_dispatch WHERE status = 'ACTIVE'").fetchone()
+        return None if row is None else self._record(row)
+
+    def get(self, mission_id: str) -> MissionDispatchRecord | None:
+        row = self._connection.execute("SELECT * FROM mission_dispatch WHERE mission_id = ?", (mission_id,)).fetchone()
+        return None if row is None else self._record(row)
+
+    def records(self) -> tuple[MissionDispatchRecord, ...]:
+        return tuple(self._record(row) for row in self._connection.execute("SELECT * FROM mission_dispatch ORDER BY sequence, mission_id"))
+
+    def activate(self, mission_id: str, *, occurred_at: str) -> MissionDispatchRecord:
+        if self.active() is not None:
+            raise MissionDispatcherError("only one Mission may be active")
+        existing = self.get(mission_id)
+        if existing and existing.status not in {DispatcherStatus.PENDING, DispatcherStatus.BLOCKED, DispatcherStatus.FAILED}:
+            raise MissionDispatcherError("Mission dispatch lifecycle cannot be activated")
+        sequence = existing.sequence if existing else len(self.records()) + 1
+        try:
+            with self._connection:
+                if existing:
+                    self._connection.execute("UPDATE mission_dispatch SET status = ?, occurred_at = ? WHERE mission_id = ?", (DispatcherStatus.ACTIVE.value, occurred_at, mission_id))
+                else:
+                    self._connection.execute("INSERT INTO mission_dispatch VALUES (?, ?, ?, ?)", (mission_id, DispatcherStatus.ACTIVE.value, sequence, occurred_at))
+        except sqlite3.IntegrityError as error:
+            raise MissionDispatcherError("only one Mission may be active") from error
+        return self.get(mission_id)  # type: ignore[return-value]
+
+    def pending(self, mission_id: str, *, occurred_at: str) -> MissionDispatchRecord:
+        if self.get(mission_id) is not None:
+            raise MissionDispatcherError("Mission already has a dispatch record")
+        with self._connection:
+            self._connection.execute(
+                "INSERT INTO mission_dispatch VALUES (?, ?, ?, ?)",
+                (mission_id, DispatcherStatus.PENDING.value, len(self.records()) + 1, occurred_at),
+            )
+        return self.get(mission_id)  # type: ignore[return-value]
+
+    def transition(self, mission_id: str, status: DispatcherStatus, *, occurred_at: str) -> MissionDispatchRecord:
+        current = self.get(mission_id)
+        if current is None or current.status is not DispatcherStatus.ACTIVE:
+            raise MissionDispatcherError("only the active Mission may change terminal dispatch state")
+        if status not in {DispatcherStatus.COMPLETED, DispatcherStatus.BLOCKED, DispatcherStatus.FAILED, DispatcherStatus.ARCHIVED}:
+            raise MissionDispatcherError("dispatch transition must be terminal or explicitly blocked")
+        with self._connection:
+            self._connection.execute("UPDATE mission_dispatch SET status = ?, occurred_at = ? WHERE mission_id = ?", (status.value, occurred_at, mission_id))
+        return self.get(mission_id)  # type: ignore[return-value]
+
+    @staticmethod
+    def _record(row: sqlite3.Row) -> MissionDispatchRecord:
+        return MissionDispatchRecord(row["mission_id"], DispatcherStatus(row["status"]), row["sequence"], row["occurred_at"])
+
+
+class MissionDispatcher:
+    """Activate one approved Mission, then wait for its independently verified completion."""
+
+    def __init__(self, queue: ApprovedMissionQueue, intake: MissionIntake, states: MissionStateStore, store: MissionDispatcherStore, *, clock: Callable[[], str], architecture_review: CompletionHook | None = None, recommendations: CompletionHook | None = None) -> None:
+        self._queue, self._intake, self._states, self._store = queue, intake, states, store
+        self._clock, self._architecture_review, self._recommendations = clock, architecture_review, recommendations
+
+    @property
+    def is_idle(self) -> bool:
+        return self._store.active() is None and not any(item.id not in {record.mission_id for record in self._store.records()} for item in self._queue.missions())
+
+    def dispatch(self) -> MissionDispatchRecord | None:
+        active = self.resume()
+        if active:
+            return active
+        if any(item.status in {DispatcherStatus.BLOCKED, DispatcherStatus.FAILED} for item in self._store.records()):
+            return None
+        completed = {item.mission_id for item in self._store.records() if item.status in {DispatcherStatus.COMPLETED, DispatcherStatus.ARCHIVED}}
+        mission = next((item for item in self._queue.missions() if item.id not in completed), None)
+        if mission is None:
+            return None
+        if self._store.get(mission.id) is None:
+            self._store.pending(mission.id, occurred_at=self._clock())
+            self._intake.admit_approved_mission(mission)
+        return self._store.activate(mission.id, occurred_at=self._clock())
+
+    def resume(self) -> MissionDispatchRecord | None:
+        active = self._store.active()
+        if active is None:
+            return None
+        state = self._states.get(active.mission_id)
+        if state.status in {MissionExecutionStatus.COMPLETED, MissionExecutionStatus.ARCHIVED}:
+            raise MissionDispatcherError("active dispatcher record has terminal Mission State")
+        return active
+
+    def complete(self, mission_id: str) -> MissionDispatchRecord | None:
+        state = self._states.get(mission_id)
+        if state.status is not MissionExecutionStatus.COMPLETED:
+            raise MissionDispatcherError("Mission completion requires verified completed Mission State")
+        evidence = getattr(state, "execution_evidence", None)
+        if evidence is not None and (not evidence.get("receipt_id") or evidence.get("outcome") != "complete"):
+            raise MissionDispatcherError("Mission completion requires host-issued complete execution evidence")
+        self._store.transition(mission_id, DispatcherStatus.COMPLETED, occurred_at=self._clock())
+        if self._architecture_review:
+            self._architecture_review(mission_id)
+        if self._recommendations:
+            self._recommendations(mission_id)
+        return self.dispatch()
+
+    def hold(self, mission_id: str, status: MissionExecutionStatus) -> MissionDispatchRecord:
+        """Reflect a loop-owned deterministic pause without advancing the queue."""
+        if status not in {MissionExecutionStatus.BLOCKED, MissionExecutionStatus.FAILED}:
+            raise MissionDispatcherError("dispatcher hold requires blocked or failed Mission State")
+        state = self._states.get(mission_id)
+        if state.status is not status:
+            raise MissionDispatcherError("dispatcher hold requires matching durable Mission State")
+        dispatch_status = DispatcherStatus.BLOCKED if status is MissionExecutionStatus.BLOCKED else DispatcherStatus.FAILED
+        return self._store.transition(mission_id, dispatch_status, occurred_at=self._clock())
+
+    def recover(self, mission_id: str) -> MissionDispatchRecord:
+        """Reactivate an explicitly recovered Mission; it does not plan or execute it."""
+        state = self._states.get(mission_id)
+        if state.status not in {MissionExecutionStatus.READY, MissionExecutionStatus.ACTIVE}:
+            raise MissionDispatcherError("dispatcher recovery requires a recovered Mission State")
+        return self._store.activate(mission_id, occurred_at=self._clock())

forge/execution/__init__.py

@@ -0,0 +1,13 @@
+"""Autonomous, single-Mission execution orchestration."""
+
+from .loop import (
+    ExecutionLoop,
+    ExecutionLoopError,
+    ExecutionLoopObservability,
+    RecoveryAuthorization,
+)
+from .presentation import render_execution_decision_evidence_reference
+from forge.governance import ApprovalRecord, ExecutionPolicy, ExecutionPolicyKind, PauseBoundary
+
+__all__ = ["ApprovalRecord", "ExecutionLoop", "ExecutionLoopError", "ExecutionLoopObservability",
+           "ExecutionPolicy", "ExecutionPolicyKind", "PauseBoundary", "RecoveryAuthorization", "render_execution_decision_evidence_reference"]