forge-autonomy 2.3.1__py3-none-any.whl

forge/__init__.py

@@ -0,0 +1,35 @@
+"""Forge's local-only Foundation Model, knowledge, and planning contracts."""
+
+from .models import (
+    ArchitectureMission,
+    Capability,
+    EngineeringMode,
+    GovernanceProfile,
+    KnowledgeSource,
+    MissionCandidate,
+    Repository,
+    RepositoryCatalog,
+    Workspace,
+)
+from .foundation import FoundationDocument, FoundationDocumentLoader, ValidationIssue, ValidationReport
+from .planning import EngineeringPlanningDocument, PlanningDocumentLoader, PlanningRegistry, PlanningValidationReport
+
+__all__ = [
+    "ArchitectureMission",
+    "Capability",
+    "EngineeringMode",
+    "GovernanceProfile",
+    "KnowledgeSource",
+    "MissionCandidate",
+    "Repository",
+    "RepositoryCatalog",
+    "Workspace",
+    "FoundationDocument",
+    "FoundationDocumentLoader",
+    "ValidationIssue",
+    "ValidationReport",
+    "EngineeringPlanningDocument",
+    "PlanningDocumentLoader",
+    "PlanningRegistry",
+    "PlanningValidationReport",
+]

forge/__main__.py

@@ -0,0 +1,20 @@
+"""Read-only command entrypoint for the packaged Forge runtime."""
+from __future__ import annotations
+
+import argparse
+
+from ._version import canonical_version
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="forge",
+        description="Forge mission planning and evidence interpretation runtime.",
+    )
+    parser.add_argument("--version", action="version", version=canonical_version())
+    parser.parse_args(argv)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

forge/_version.py

@@ -0,0 +1,38 @@
+"""Resolve Forge's canonical version without creating a second allocator."""
+from __future__ import annotations
+
+import json
+from importlib.metadata import PackageNotFoundError, version as installed_version
+from pathlib import Path
+import re
+
+
+_VERSION = re.compile(r"^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$")
+
+
+def _source_version() -> str | None:
+    """Read the sole source of authority when this is a source distribution."""
+    manifest = Path(__file__).resolve().parents[1] / "product-version.json"
+    try:
+        value = json.loads(manifest.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    candidate = value.get("version") if isinstance(value, dict) else None
+    return candidate if isinstance(candidate, str) and _VERSION.fullmatch(candidate) else None
+
+
+def canonical_version() -> str:
+    """Return the source manifest version or installed distribution metadata."""
+    source = _source_version()
+    if source is not None:
+        return source
+    try:
+        value = installed_version("forge-autonomy")
+    except PackageNotFoundError as error:
+        raise RuntimeError("Forge version metadata is unavailable") from error
+    if _VERSION.fullmatch(value) is None:
+        raise RuntimeError("Forge version metadata is not a stable X.Y.Z version")
+    return value
+
+
+__version__ = canonical_version()

forge/action_derivation_canary_closure.py

@@ -0,0 +1,129 @@
+"""Canonical immutable closure for a bounded Action-Derivation qualification canary."""
+from __future__ import annotations
+
+from hashlib import sha256
+import json
+
+from forge.governance_authority import CanonicalGovernanceRepository, GovernanceCapability
+from forge.operator_identity import OperatorContext
+from forge.runtime.database import _timestamp
+
+
+_NOT_QUALIFIED = (
+    "ACTION_MATERIALIZATION", "AUTONOMOUS_NEXT_MISSION_LOOP", "EP_DISPATCH",
+    "EP_RESULT_OBSERVATION", "EXECUTION_ADMISSION",
+)
+
+
+def _digest(value: object) -> str:
+    return "sha256:" + sha256(json.dumps(value, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+
+class CanonicalActionDerivationCanaryClosureService:
+    """Close a qualified planning-only canary without changing Mission lifecycle."""
+
+    def __init__(self, repository: CanonicalGovernanceRepository) -> None:
+        self.repository, self.database = repository, repository.database
+
+    @staticmethod
+    def _operator_id(context: OperatorContext) -> str:
+        return sha256(context.generated_uid.encode()).hexdigest()[:16]
+
+    def close(self, *, mission_id: str, successor_attempt_id: str,
+              qualification_decision_id: str, operator_context: OperatorContext) -> dict[str, object]:
+        if not self.repository.operators.authorize(operator_context):
+            raise PermissionError("trusted operator context is required")
+        state = self.database.get_document("mission_state", mission_id)
+        successor = self.database.get_document("action_derivations", successor_attempt_id)
+        required = (
+            "predecessor_attempt_id", "authorization_id", "preflight_receipt_id", "main_head",
+            "snapshot_digest", "evidence_digest", "effective_contract_digest",
+            "provider_configuration", "generation_request_digest", "validation_digest",
+        )
+        if (state.get("status") != "APPROVED_PLANNABLE" or successor.get("mission_id") != mission_id
+                or successor.get("lifecycle") != "VALIDATED" or successor.get("validation_result") != "PASS"
+                or successor.get("provider_output_untrusted") is not True
+                or successor.get("runtime_action_executed") is not False
+                or successor.get("action_materialized") is not False
+                or successor.get("engineering_side_effects", 0) != 0
+                or any(not isinstance(successor.get(key), str) or not successor[key] for key in required)):
+            raise PermissionError("canonical validated non-executing Action-Derivation evidence is incomplete")
+        predecessor = self.database.get_document("action_derivations", successor["predecessor_attempt_id"])
+        authorization = self.database.get_document(
+            "action_derivation_reattempt_authorizations", successor["authorization_id"]
+        )
+        if (predecessor.get("mission_id") != mission_id or predecessor.get("lifecycle") != "FAILED"
+                or authorization.get("successor_attempt_id") != successor_attempt_id
+                or authorization.get("predecessor_attempt_id") != successor["predecessor_attempt_id"]
+                or any(authorization.get(left) != successor.get(right) for left, right in (
+                    ("planning_snapshot_digest", "snapshot_digest"), ("effective_contract_digest", "effective_contract_digest"),
+                    ("evidence_digest", "evidence_digest"), ("g011_policy_digest", "provider_configuration"),
+                    ("provider_request_digest", "generation_request_digest"), ("main_head", "main_head")))):
+            raise PermissionError("canonical successor lineage is stale or conflicting")
+        if self.database._connection.execute(
+            "SELECT 1 FROM action_derivation_reattempt_consumptions WHERE authorization_id=?",
+            (successor["authorization_id"],),
+        ).fetchone() is None:
+            raise PermissionError("validated successor lacks a consumed canonical reattempt authorization")
+        receipt = self.database.consumed_token_preflight_receipt(successor["preflight_receipt_id"])
+        if any(receipt.get(left) != successor.get(right) for left, right in (
+            ("mission_id", "mission_id"), ("main_head", "main_head"), ("policy_digest", "provider_configuration"),
+            ("request_digest", "generation_request_digest"), ("evidence_digest", "evidence_digest"),
+            ("effective_contract_digest", "effective_contract_digest"),
+        )):
+            raise PermissionError("canonical token-preflight receipt is stale or conflicting")
+        try:
+            decision = self.repository.decision(qualification_decision_id)
+        except ValueError as error:
+            raise PermissionError("post-canary Security qualification is absent") from error
+        summary = {
+            "mission_id": mission_id, "successor_attempt_id": successor_attempt_id,
+            "predecessor_attempt_id": successor["predecessor_attempt_id"],
+            "authorization_id": successor["authorization_id"], "main_head": successor["main_head"],
+            "snapshot_digest": successor["snapshot_digest"], "evidence_digest": successor["evidence_digest"],
+            "effective_contract_digest": successor["effective_contract_digest"],
+            "g011_policy_digest": successor["provider_configuration"],
+            "request_digest": successor["generation_request_digest"],
+            "preflight_receipt_id": successor["preflight_receipt_id"],
+            "validation_digest": successor["validation_digest"],
+        }
+        if (decision.get("subject_id") != successor_attempt_id
+                or decision.get("subject_revision") != successor["validation_digest"]
+                or decision.get("capability") != GovernanceCapability.SECURITY_APPROVAL.value
+                or decision.get("decision") != "approved"
+                or decision.get("scope") != ["ACTION_DERIVATION_QUALIFICATION"]
+                or decision.get("gates") != ["POST_CANARY_SECURITY_REVIEW"]
+                or decision.get("predecessor_digest") != _digest(summary)):
+            raise PermissionError("post-canary Security qualification is absent, stale, or conflicting")
+        closure_id = f"action-derivation-canary-closure:{mission_id}:{successor_attempt_id}"
+        document = {
+            "closure_id": closure_id, "mission_id": mission_id,
+            "successor_attempt_id": successor_attempt_id,
+            "predecessor_attempt_id": successor["predecessor_attempt_id"],
+            "qualification_decision_id": qualification_decision_id,
+            "qualification_decision_digest": _digest(decision),
+            "effective_contract_digest": successor["effective_contract_digest"],
+            "evidence_digest": successor["evidence_digest"],
+            "g011_policy_digest": successor["provider_configuration"],
+            "provider_request_digest": successor["generation_request_digest"],
+            "preflight_receipt_id": successor["preflight_receipt_id"],
+            "reattempt_authorization_id": successor["authorization_id"],
+            "main_head": successor["main_head"], "qualified_capability": "ACTION_DERIVATION",
+            "not_qualified_capabilities": list(_NOT_QUALIFIED),
+            "installation_id": operator_context.installation_id,
+            "operator_id": self._operator_id(operator_context),
+            "runtime_id": self.database.metadata["runtime_id"], "closed_at": _timestamp(),
+        }
+        existing = self.database._connection.execute(
+            "SELECT document FROM action_derivation_canary_closures WHERE successor_attempt_id=?",
+            (successor_attempt_id,),
+        ).fetchone()
+        if existing is not None:
+            persisted = json.loads(existing["document"])
+            expected = {key: value for key, value in document.items() if key != "closed_at"}
+            actual = {key: value for key, value in persisted.items() if key not in ("closed_at", "digest")}
+            if actual != expected:
+                raise PermissionError("existing Action-Derivation canary closure is stale or conflicting")
+            return persisted
+        document["digest"] = _digest(document)
+        return self.database.create_action_derivation_canary_closure(document)

forge/action_derivation_evidence.py

@@ -0,0 +1,101 @@
+"""Canonical, pre-planning evidence producer for Action Derivation.
+
+It deliberately derives only from a Mission's immutable admission contract;
+it neither observes repositories, creates approvals, nor grants execution.
+"""
+from __future__ import annotations
+
+from hashlib import sha256
+import json
+
+from forge.governance_authority import CanonicalGovernanceRepository
+from forge.models.architecture_mission import ArchitectureMission
+from forge.models.intent import IntentReference
+from forge.models.mission_planner import (ApprovedScope, MissionPlannerInput, MissionPlanningState,
+    PlanningEvidence, PlanningInputKind)
+from forge.runtime.database import RuntimeDatabase, RuntimeIntegrityError
+from forge.mission_amendment import MissionAmendmentService
+
+
+def _digest(value: object) -> str:
+    return "sha256:" + sha256(json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode()).hexdigest()
+
+
+class ActionDerivationEvidenceError(ValueError):
+    """The immutable admission contract cannot produce a complete evidence set."""
+
+
+class CanonicalActionDerivationEvidenceProducer:
+    """The sole runtime-owned producer for generic pre-planning evidence."""
+
+    _NO_REPOSITORY_TARGET = "NO_REPOSITORY_TARGET=TRUE"
+    _CAPABILITIES = ("action-derivation-planning", "deterministic-action-materialization")
+
+    def __init__(self, database: RuntimeDatabase, repository: CanonicalGovernanceRepository) -> None:
+        if repository.database is not database:
+            raise ValueError("evidence producer requires the canonical governance Runtime Database")
+        self.database, self.repository = database, repository
+
+    def produce(self, mission_id: str) -> dict[str, object]:
+        state = self.database.get_document("mission_state", mission_id)
+        contract, _ = MissionAmendmentService(self.repository).effective_contract(mission_id)
+        if not isinstance(contract, dict) or state.get("status") != "APPROVED_PLANNABLE":
+            raise ActionDerivationEvidenceError("Mission is not canonically approved/plannable")
+        required = ("installation_id", "candidate_id", "subject_revision", "business_decision_id",
+                    "architecture_decision_id", "planning", "envelope_digest", "write_scope", "mission")
+        if any(item not in contract for item in required) or contract["write_scope"] != "NONE":
+            raise ActionDerivationEvidenceError("Mission admission contract is incomplete or has non-NONE write scope")
+        mission = ArchitectureMission.from_dict(contract["mission"])
+        if mission.id != mission_id or mission.candidate_id != contract["candidate_id"]:
+            raise RuntimeIntegrityError("Mission admission contract identity mismatch")
+        if contract["installation_id"] != self.repository.operators.installation_id():
+            raise ActionDerivationEvidenceError("Mission admission contract is cross-installation")
+        planning = contract["planning"]
+        if not isinstance(planning, dict) or planning.get("provenance_revision") != contract["subject_revision"]:
+            raise ActionDerivationEvidenceError("Mission planning evidence revision is stale")
+        for decision_id in (contract["business_decision_id"], contract["architecture_decision_id"]):
+            decision = self.repository.decision(decision_id)
+            if decision["subject_id"] != contract["candidate_id"] or decision["subject_revision"] != contract["subject_revision"]:
+                raise ActionDerivationEvidenceError("Mission approval lineage is inconsistent")
+        if self._NO_REPOSITORY_TARGET not in mission.engineering_constraints:
+            raise ActionDerivationEvidenceError("Mission lacks explicit approved NO_REPOSITORY_TARGET evidence")
+        context = {"kind": "NO_REPOSITORY_TARGET", "mission_id": mission_id,
+                   "installation_id": contract["installation_id"], "candidate_id": contract["candidate_id"],
+                   "subject_revision": contract["subject_revision"], "write_scope": contract["write_scope"],
+                   "classification": "planning_only_no_repository_target",
+                   "provenance": {"envelope_digest": contract["envelope_digest"], "mission_constraint": self._NO_REPOSITORY_TARGET}}
+        context["digest"] = _digest(context)
+        projection = {"kind": "PRE_PLANNING_CANONICAL_PROJECTION", "mission_id": mission_id,
+                      "installation_id": contract["installation_id"], "candidate_id": contract["candidate_id"],
+                      "subject_revision": contract["subject_revision"], "architecture_decision_id": contract["architecture_decision_id"],
+                      "envelope_digest": contract["envelope_digest"], "planning": planning}
+        projection["digest"] = _digest(projection)
+        catalogue = {"kind": "RUNTIME_CAPABILITY_CATALOGUE", "mission_id": mission_id,
+                     "installation_id": contract["installation_id"], "candidate_id": contract["candidate_id"],
+                     "subject_revision": contract["subject_revision"], "envelope_digest": contract["envelope_digest"],
+                     "capabilities": list(self._CAPABILITIES), "effective_write_scope": "NONE", "grants_authority": False}
+        catalogue["digest"] = _digest(catalogue)
+        mission_evidence = {"kind": "MISSION_STATE", "mission_id": mission_id, "digest": _digest(state)}
+        value = {"evidence_set_id": "action-derivation-evidence-" + contract["envelope_digest"][7:23],
+                 "mission_id": mission_id, "installation_id": contract["installation_id"],
+                 "candidate_id": contract["candidate_id"], "subject_revision": contract["subject_revision"],
+                 "envelope_digest": contract["envelope_digest"], "mission_state": mission_evidence,
+                 "repository_context": context, "architecture_review": projection, "capability_catalogue": catalogue}
+        value["digest"] = _digest(value)
+        return self.database.create_action_derivation_evidence_set(value)
+
+    def planner_input(self, mission_id: str) -> MissionPlannerInput:
+        evidence_set = self.produce(mission_id)
+        mission = ArchitectureMission.from_dict(self.database.get_document("mission_state", mission_id)["admission_contract"]["mission"])
+        reference = IntentReference("architecture-decision", str(evidence_set["subject_revision"]),
+                                    "runtime://governance/" + str(evidence_set["architecture_review"]["architecture_decision_id"]))
+        documents = ((PlanningInputKind.MISSION_STATE, evidence_set["mission_state"]),
+                     (PlanningInputKind.REPOSITORY_CONTEXT, evidence_set["repository_context"]),
+                     (PlanningInputKind.ARCHITECTURE_REVIEW, evidence_set["architecture_review"]),
+                     (PlanningInputKind.CAPABILITY_CATALOGUE, evidence_set["capability_catalogue"]))
+        evidence = tuple(PlanningEvidence(kind, str(document["kind"]).lower(), str(evidence_set["subject_revision"]),
+                                          "runtime://action-derivation-evidence/" + str(evidence_set["evidence_set_id"]), str(document["digest"]))
+                         for kind, document in documents)
+        capability = mission.required_capabilities[0]
+        scopes = tuple(ApprovedScope(scope, capability, (reference,), (), allow_provider_derivation=True) for scope in mission.scope)
+        return MissionPlannerInput(mission, MissionPlanningState(mission.id, int(self.database.get_document("mission_state", mission_id)["revision"])), evidence, scopes)

forge/action_derivation_qualification.py

@@ -0,0 +1,71 @@
+"""Canonical post-canary qualification decision for validated derivations."""
+from __future__ import annotations
+
+from hashlib import sha256
+import json
+
+from forge.governance_authority import CanonicalGovernanceRepository, GovernanceCapability, GovernanceDecision
+from forge.operator_identity import OperatorContext
+
+
+def _digest(value: object) -> str:
+    return "sha256:" + sha256(json.dumps(value, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+
+class CanonicalActionDerivationQualificationService:
+    """Records no new authority: a typed projection of SECURITY_APPROVAL only."""
+    def __init__(self, repository: CanonicalGovernanceRepository) -> None:
+        self.repository, self.database = repository, repository.database
+
+    def qualify(self, *, mission_id: str, successor_attempt_id: str,
+                operator_context: OperatorContext, decision_id: str) -> str:
+        if not self.repository.operators.authorize(operator_context):
+            raise PermissionError("trusted operator context is required")
+        state = self.database.get_document("mission_state", mission_id)
+        successor = self.database.get_document("action_derivations", successor_attempt_id)
+        required = ("predecessor_attempt_id", "authorization_id", "preflight_receipt_id", "main_head", "evidence_digest",
+                    "effective_contract_digest", "provider_configuration", "generation_request_digest",
+                    "validation_digest")
+        if (state.get("status") != "APPROVED_PLANNABLE" or successor.get("mission_id") != mission_id
+                or successor.get("lifecycle") != "VALIDATED" or successor.get("validation_result") != "PASS"
+                or successor.get("provider_output_untrusted") is not True
+                or successor.get("runtime_action_executed") is not False
+                or successor.get("action_materialized") is not False
+                or any(not isinstance(successor.get(key), str) or not successor[key] for key in required)):
+            raise PermissionError("canonical validated non-executing Action-Derivation evidence is incomplete")
+        predecessor = self.database.get_document("action_derivations", successor["predecessor_attempt_id"])
+        authorization = self.database.get_document("action_derivation_reattempt_authorizations", successor["authorization_id"])
+        if (predecessor.get("lifecycle") != "FAILED"
+                or authorization.get("successor_attempt_id") != successor_attempt_id
+                or authorization.get("predecessor_attempt_id") != successor["predecessor_attempt_id"]
+                or any(authorization.get(left) != successor.get(right) for left, right in (
+                    ("planning_snapshot_digest", "snapshot_digest"), ("g011_policy_digest", "provider_configuration"),
+                    ("evidence_digest", "evidence_digest"), ("effective_contract_digest", "effective_contract_digest"),
+                    ("provider_request_digest", "generation_request_digest"), ("main_head", "main_head")))):
+            raise PermissionError("canonical successor lineage is stale or conflicting")
+        consumed_authorization = self.database._connection.execute(
+            "SELECT 1 FROM action_derivation_reattempt_consumptions WHERE authorization_id = ?",
+            (successor["authorization_id"],),
+        ).fetchone()
+        if consumed_authorization is None:
+            raise PermissionError("validated successor lacks a consumed canonical reattempt authorization")
+        receipt = self.database.consumed_token_preflight_receipt(successor["preflight_receipt_id"])
+        if any(receipt.get(left) != successor.get(right) for left, right in (
+            ("mission_id", "mission_id"), ("main_head", "main_head"), ("policy_digest", "provider_configuration"),
+            ("request_digest", "generation_request_digest"), ("evidence_digest", "evidence_digest"),
+            ("effective_contract_digest", "effective_contract_digest"),
+        )):
+            raise PermissionError("canonical token-preflight receipt is stale or conflicting")
+        summary = {"mission_id": mission_id, "successor_attempt_id": successor_attempt_id,
+                   "predecessor_attempt_id": successor["predecessor_attempt_id"],
+                   "authorization_id": successor["authorization_id"],
+                   "main_head": successor["main_head"], "snapshot_digest": successor["snapshot_digest"],
+                   "evidence_digest": successor["evidence_digest"],
+                   "effective_contract_digest": successor["effective_contract_digest"],
+                   "g011_policy_digest": successor["provider_configuration"],
+                   "request_digest": successor["generation_request_digest"],
+                   "preflight_receipt_id": successor["preflight_receipt_id"],
+                   "validation_digest": successor["validation_digest"]}
+        return self.repository.record(GovernanceDecision(
+            decision_id, successor_attempt_id, successor["validation_digest"], GovernanceCapability.SECURITY_APPROVAL,
+            "approved", ("ACTION_DERIVATION_QUALIFICATION",), ("POST_CANARY_SECURITY_REVIEW",), _digest(summary)), operator_context)

forge/action_derivation_reattempt.py

@@ -0,0 +1,113 @@
+"""Canonical, explicitly authorized successor lineage for Action Derivation.
+
+This module allocates no provider work.  It records the one durable authority
+needed before a later, separately authorized token preflight may be attempted.
+"""
+from __future__ import annotations
+
+from hashlib import sha256
+import json
+import re
+import uuid
+
+from forge.action_derivation_evidence import CanonicalActionDerivationEvidenceProducer
+from forge.governance_authority import CanonicalGovernanceRepository
+from forge.models.action_derivation import PlanningSnapshot
+from forge.operator_identity import OperatorContext
+from forge.planner.openai_responses import _G011PolicySnapshot, _digest
+from forge.planner.provider_adapter import ProviderDerivationRequest
+from forge.runtime.database import RuntimeIntegrityError, _timestamp
+
+
+REQUEST_SEMANTICS_CHANGED = "REQUEST_SEMANTICS_CHANGED"
+
+
+class NewPlanningRequired(RuntimeIntegrityError):
+    """The candidate drifted beyond the narrow reattempt authority."""
+
+
+class CanonicalActionDerivationReattemptService:
+    """The sole application path for a governed Action-Derivation successor.
+
+    It accepts a canonical adapter/configuration rather than caller-provided
+    policy, evidence, database, or request digests.  Persisting authorization
+    never calls a provider and never consumes a preflight receipt.
+    """
+    def __init__(self, adapter, governance_repository: CanonicalGovernanceRepository) -> None:
+        database = adapter.configuration.policy_service.db
+        if governance_repository.database is not database:
+            raise PermissionError("reattempt lineage requires the canonical governance RuntimeDatabase")
+        self.adapter, self.repository, self.database = adapter, governance_repository, database
+
+    @staticmethod
+    def _record_digest(value: dict[str, object]) -> str:
+        return "sha256:" + sha256(json.dumps(value, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+    def authorize_successor(self, *, predecessor_attempt_id: str, operator_context: OperatorContext,
+                            rationale: str, reason: str = REQUEST_SEMANTICS_CHANGED) -> dict[str, object]:
+        if reason != REQUEST_SEMANTICS_CHANGED:
+            raise PermissionError("unsupported Action-Derivation reattempt reason")
+        if not isinstance(rationale, str) or not rationale.strip() or len(rationale) > 512:
+            raise ValueError("a bounded explicit reattempt rationale is required")
+        if not self.repository.operators.authorize(operator_context):
+            raise PermissionError("trusted operator context is required for a reattempt")
+        predecessor = self.database.get_document("action_derivations", predecessor_attempt_id)
+        if predecessor.get("lifecycle") != "FAILED":
+            raise PermissionError("only a terminal failed Action-Derivation attempt may have a successor")
+        required = ("mission_id", "snapshot_digest", "effective_contract_digest", "evidence_digest",
+                    "provider_configuration", "generation_request_digest", "main_head")
+        if any(not isinstance(predecessor.get(field), str) or not predecessor[field] for field in required):
+            raise RuntimeIntegrityError("predecessor lacks complete canonical reattempt provenance")
+
+        mission_id = predecessor["mission_id"]
+        producer = CanonicalActionDerivationEvidenceProducer(self.database, self.repository)
+        planning_input = producer.planner_input(mission_id)
+        snapshot = PlanningSnapshot.from_planner_input(planning_input)
+        policy = self.adapter.configuration.current_policy()
+        policy_digest = _G011PolicySnapshot.from_policy(policy).digest
+        boundary = self.adapter.configuration.preflight_authority.boundary_for(mission_id)
+        state = self.database.get_document("mission_state", mission_id)
+        if state.get("status") != "APPROVED_PLANNABLE":
+            raise NewPlanningRequired("Mission is no longer approved/plannable")
+        if any((snapshot.digest != predecessor["snapshot_digest"],
+                boundary.effective_contract_digest != predecessor["effective_contract_digest"],
+                boundary.evidence_digest != predecessor["evidence_digest"],
+                policy_digest != predecessor["provider_configuration"])):
+            raise NewPlanningRequired("Mission, planning, effective contract, evidence, or G011 policy drift requires new planning")
+
+        successor_attempt_id = f"reattempt-{uuid.uuid4()}"
+        request = ProviderDerivationRequest(successor_attempt_id, snapshot, policy.provider_id, policy.model)
+        request_digest = _digest(self.adapter._body(request, policy))
+        if request_digest == predecessor["generation_request_digest"]:
+            raise PermissionError("an unchanged request digest is an exact replay, not a successor attempt")
+        sequence_row = self.database._connection.execute(
+            "SELECT MAX(attempt_sequence) AS sequence FROM action_derivation_reattempt_authorizations WHERE predecessor_attempt_id=?",
+            (predecessor_attempt_id,),
+        ).fetchone()
+        if sequence_row is not None and sequence_row["sequence"] is not None:
+            # A second child of this predecessor is never silently given a new
+            # sequence; its different reason needs separate governance semantics.
+            raise PermissionError("a predecessor already has a governed successor attempt")
+        operator_id = self.repository._operator_id(operator_context)
+        document: dict[str, object] = {
+            "authorization_id": f"action-derivation-reattempt-{uuid.uuid4()}",
+            "successor_attempt_id": successor_attempt_id,
+            "mission_id": mission_id,
+            "predecessor_attempt_id": predecessor_attempt_id,
+            "predecessor_terminal_state": predecessor["lifecycle"],
+            "attempt_sequence": 2,
+            "planning_snapshot_digest": snapshot.digest,
+            "effective_contract_digest": boundary.effective_contract_digest,
+            "evidence_digest": boundary.evidence_digest,
+            "g011_policy_digest": policy_digest,
+            "provider_request_digest": request_digest,
+            "main_head": boundary.main_head,
+            "reattempt_reason": reason,
+            "rationale": rationale.strip(),
+            "authorization_identity": operator_id,
+            "installation_id": operator_context.installation_id,
+            "created_at": _timestamp(),
+        }
+        document["digest"] = self._record_digest(document)
+        return self.database.create_action_derivation_reattempt_authorization(document)
+

forge/ai_architect/__init__.py

@@ -0,0 +1,5 @@
+"""Provider-neutral AI Architect registry and future provider namespace."""
+
+from .provider_registry import AIProviderRegistry
+
+__all__ = ["AIProviderRegistry"]

forge/ai_architect/provider_registry.py

@@ -0,0 +1,82 @@
+"""Local deterministic registry for AI Architect Provider declarations only."""
+
+from __future__ import annotations
+
+from forge.models import (
+    AIProviderMetadata,
+    ProviderQualification,
+    ProviderQualificationState,
+    ProviderSelection,
+    ProviderSelectionRequest,
+    ProviderStatus,
+    WorkspaceProviderConfiguration,
+)
+
+
+class AIProviderRegistry:
+    """Register and select declared providers without loading or invoking one."""
+
+    def __init__(self) -> None:
+        self._providers: dict[str, AIProviderMetadata] = {}
+        self._qualifications: dict[str, ProviderQualification] = {}
+
+    def register(self, provider: AIProviderMetadata, qualification: ProviderQualification) -> AIProviderMetadata:
+        """Register one repository-qualified declaration, rejecting duplicate ids."""
+        if provider.id in self._providers:
+            raise ValueError("provider id is already registered")
+        if qualification.provider_id != provider.id or qualification.provider_version != provider.version:
+            raise ValueError("provider qualification must match provider identity and version")
+        if qualification.state is not provider.qualification_state:
+            raise ValueError("provider qualification must match provider qualification state")
+        self._providers[provider.id] = provider
+        self._qualifications[provider.id] = qualification
+        return provider
+
+    def list(self) -> tuple[AIProviderMetadata, ...]:
+        """Return all declarations in stable provider-id and version order."""
+        return tuple(sorted(self._providers.values(), key=lambda item: (item.id, item.version)))
+
+    def qualification(self, provider_id: str) -> ProviderQualification | None:
+        """Return the repository-owned qualification record, if registered."""
+        return self._qualifications.get(provider_id)
+
+    def select(
+        self,
+        request: ProviderSelectionRequest,
+        configuration: WorkspaceProviderConfiguration,
+    ) -> ProviderSelection:
+        """Select an active qualified declaration by policy, never invoke it."""
+        if configuration.workspace_id != request.workspace_id:
+            raise ValueError("workspace provider configuration must match selection request")
+        qualified = tuple(
+            provider
+            for provider in self.list()
+            if provider.qualification_state is ProviderQualificationState.QUALIFIED
+            and provider.status is ProviderStatus.ACTIVE
+            and request.capability in provider.capabilities
+            and request.reasoning_mode in provider.reasoning_modes
+        )
+        if not qualified:
+            raise LookupError("no qualified provider supports the requested capability and reasoning mode")
+        by_id = {provider.id: provider for provider in qualified}
+        configured = self._ordered_configured_ids(configuration)
+        for provider_id, reason in configured:
+            provider = by_id.get(provider_id)
+            if provider is not None:
+                return ProviderSelection(request, provider, reason)
+        return ProviderSelection(request, qualified[0], "stable_provider_id_version_tiebreaker")
+
+    @staticmethod
+    def _ordered_configured_ids(configuration: WorkspaceProviderConfiguration) -> tuple[tuple[str, str], ...]:
+        candidates = [(provider_id, "workspace_provider_preference") for provider_id in configuration.provider_preferences]
+        if configuration.default_provider_id:
+            candidates.append((configuration.default_provider_id, "workspace_default_provider"))
+        if configuration.fallback_provider_id:
+            candidates.append((configuration.fallback_provider_id, "workspace_fallback_provider"))
+        seen: set[str] = set()
+        ordered: list[tuple[str, str]] = []
+        for provider_id, reason in candidates:
+            if provider_id not in seen:
+                seen.add(provider_id)
+                ordered.append((provider_id, reason))
+        return tuple(ordered)

forge/architecture/__init__.py

@@ -0,0 +1,8 @@
+"""Architecture Workspace public contracts."""
+
+from .advisor import ArchitectureAdvisor, ArchitectureAdvisorAdvice
+from .presentation import render_architecture_decision_evidence, render_architecture_mission
+from .workspace import ArchitectureMissionHistoryEntry, ArchitectureWorkspace, ArchitectureWorkspaceError
+from forge.governance_authority import ArchitecturePlanningEvidence, CanonicalArchitectureWorkspace, MissionPlanningEvidenceEnvelope
+
+__all__ = ["ArchitectureAdvisor", "ArchitectureAdvisorAdvice", "ArchitectureMissionHistoryEntry", "ArchitectureWorkspace", "ArchitectureWorkspaceError", "ArchitecturePlanningEvidence", "CanonicalArchitectureWorkspace", "MissionPlanningEvidenceEnvelope", "render_architecture_decision_evidence", "render_architecture_mission"]