fdai-deployment-cli 0.1.2__py3-none-any.whl

fdai_deployment_cli/lifecycle_promotion.py

@@ -0,0 +1,185 @@
+"""Release channel promotion pipeline evaluator and boundary registry digest mirroring."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+
+from fdai_deployment_cli.lifecycle_plan import required_artifact_digests
+from fdai_deployment_cli.lifecycle_release import LifecycleRelease
+from fdai_deployment_cli.runtime_release import (
+    RecallRecord,
+    ReleaseDecision,
+    evaluate_recall_candidate,
+    is_release_id,
+)
+
+_IMAGE_DIGEST = re.compile(r"sha256:[0-9a-f]{64}\Z", re.ASCII)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PromotionStageCriteria:
+    """Criteria required to advance a Release from ``source_channel`` to ``target_channel``."""
+
+    source_channel: str
+    target_channel: str
+    required_labels: frozenset[str] = field(default_factory=frozenset)
+    min_soak_seconds: int = 0
+    min_healthy_canaries: int = 0
+    max_stage_timeout_seconds: int = 3600
+
+    def __post_init__(self) -> None:
+        if not self.source_channel.strip() or not self.target_channel.strip():
+            raise ValueError("source_channel and target_channel MUST NOT be empty")
+        if self.source_channel == self.target_channel:
+            raise ValueError("source_channel and target_channel MUST differ")
+        if any(not label.strip() for label in self.required_labels):
+            raise ValueError("required_labels MUST NOT contain blank labels")
+        if (
+            isinstance(self.min_soak_seconds, bool)
+            or not isinstance(self.min_soak_seconds, int)
+            or self.min_soak_seconds < 0
+        ):
+            raise ValueError("min_soak_seconds MUST be a non-negative integer")
+        if (
+            isinstance(self.min_healthy_canaries, bool)
+            or not isinstance(self.min_healthy_canaries, int)
+            or self.min_healthy_canaries < 0
+        ):
+            raise ValueError("min_healthy_canaries MUST be a non-negative integer")
+        if (
+            isinstance(self.max_stage_timeout_seconds, bool)
+            or not isinstance(self.max_stage_timeout_seconds, int)
+            or self.max_stage_timeout_seconds < 1
+        ):
+            raise ValueError("max_stage_timeout_seconds MUST be a positive integer")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CanaryObservation:
+    """Health and soak observation from one canary installation running a candidate Release."""
+
+    installation_id: str
+    release_id: str
+    healthy: bool
+    soak_seconds: int
+
+    def __post_init__(self) -> None:
+        if not self.installation_id.strip():
+            raise ValueError("installation_id MUST NOT be empty")
+        if not is_release_id(self.release_id):
+            raise ValueError("release_id MUST be canonical SemVer")
+        if not isinstance(self.healthy, bool):
+            raise TypeError("healthy MUST be a boolean")
+        if (
+            isinstance(self.soak_seconds, bool)
+            or not isinstance(self.soak_seconds, int)
+            or self.soak_seconds < 0
+        ):
+            raise ValueError("soak_seconds MUST be a non-negative integer")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PromotionStageInput:
+    """Observed evidence for one promotion-pipeline stage evaluation."""
+
+    release_id: str
+    present_in_source_channel: bool
+    labels: frozenset[str] = field(default_factory=frozenset)
+    canary_observations: tuple[CanaryObservation, ...] = ()
+    elapsed_stage_seconds: int = 0
+    capability_ids: tuple[str, ...] = ()
+    recall_records: tuple[RecallRecord, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not is_release_id(self.release_id):
+            raise ValueError("release_id MUST be canonical SemVer")
+        if not isinstance(self.present_in_source_channel, bool):
+            raise TypeError("present_in_source_channel MUST be a boolean")
+        if (
+            isinstance(self.elapsed_stage_seconds, bool)
+            or not isinstance(self.elapsed_stage_seconds, int)
+            or self.elapsed_stage_seconds < 0
+        ):
+            raise ValueError("elapsed_stage_seconds MUST be a non-negative integer")
+
+
+def evaluate_promotion_stage(
+    criteria: PromotionStageCriteria,
+    stage_input: PromotionStageInput,
+) -> ReleaseDecision:
+    """Evaluate label requirements, soak time, canary health, timeouts, and recalls."""
+
+    recall_decision = evaluate_recall_candidate(
+        release_id=stage_input.release_id,
+        capability_ids=stage_input.capability_ids,
+        recall_records=stage_input.recall_records,
+    )
+    if not recall_decision.allowed:
+        return recall_decision
+    if not stage_input.present_in_source_channel:
+        return ReleaseDecision(
+            False, "promotion_source_channel_missing", (criteria.source_channel,)
+        )
+    if stage_input.elapsed_stage_seconds > criteria.max_stage_timeout_seconds:
+        return ReleaseDecision(
+            False,
+            "promotion_stage_timed_out",
+            (str(stage_input.elapsed_stage_seconds), str(criteria.max_stage_timeout_seconds)),
+        )
+    missing_labels = tuple(sorted(criteria.required_labels - stage_input.labels))
+    if missing_labels:
+        return ReleaseDecision(False, "promotion_labels_missing", missing_labels)
+    relevant = [
+        obs for obs in stage_input.canary_observations if obs.release_id == stage_input.release_id
+    ]
+    unhealthy = tuple(sorted(obs.installation_id for obs in relevant if not obs.healthy))
+    if unhealthy:
+        return ReleaseDecision(False, "promotion_canary_unhealthy", unhealthy)
+    healthy = [obs for obs in relevant if obs.healthy]
+    if len(healthy) < criteria.min_healthy_canaries:
+        return ReleaseDecision(
+            False,
+            "promotion_canary_quorum_unmet",
+            (str(len(healthy)), str(criteria.min_healthy_canaries)),
+        )
+    soaked = [obs for obs in healthy if obs.soak_seconds >= criteria.min_soak_seconds]
+    if len(soaked) < criteria.min_healthy_canaries:
+        return ReleaseDecision(
+            False,
+            "promotion_soak_incomplete",
+            (str(len(soaked)), str(criteria.min_healthy_canaries)),
+        )
+    return ReleaseDecision(True, "allowed", ())
+
+
+@dataclass(frozen=True, slots=True)
+class BoundaryRegistryMirror:
+    """Connected-installation boundary registry mirror state for Release image digests."""
+
+    mirrored_digests: frozenset[str] = field(default_factory=frozenset)
+
+    def __post_init__(self) -> None:
+        if any(_IMAGE_DIGEST.fullmatch(digest) is None for digest in self.mirrored_digests):
+            raise ValueError("mirrored_digests MUST contain only sha256:<64 hex> digests")
+
+    def missing_for(self, release: LifecycleRelease) -> frozenset[str]:
+        """Return required Release image digests not yet mirrored inside the boundary."""
+
+        return required_artifact_digests(release) - self.mirrored_digests
+
+    def mirror_release(
+        self,
+        release: LifecycleRelease,
+        *,
+        available_upstream_digests: Iterable[str],
+    ) -> BoundaryRegistryMirror:
+        """Mirror available required digests for ``release`` into the boundary registry."""
+
+        upstream = frozenset(available_upstream_digests)
+        if any(_IMAGE_DIGEST.fullmatch(digest) is None for digest in upstream):
+            raise ValueError("available_upstream_digests MUST contain only sha256:<64 hex> digests")
+        required = required_artifact_digests(release)
+        transferred = required & upstream
+        return BoundaryRegistryMirror(mirrored_digests=self.mirrored_digests | transferred)

fdai_deployment_cli/lifecycle_release.py

@@ -0,0 +1,308 @@
+"""Application-neutral lifecycle packages and the legacy runtime compatibility adapter."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Protocol
+
+from fdai_deployment_cli.contracts import canonical_bytes, canonical_digest, load_json_object
+from fdai_deployment_cli.runtime_release import (
+    ConfigurationSchema,
+    RuntimeReleaseError,
+    SchemaMetadata,
+    SchemaRange,
+    is_release_id,
+    parse_release_configuration_schema,
+    parse_runtime_release_manifest,
+)
+
+APPLICATION_RELEASE_SCHEMA = "fdai.application-release.v1"
+APPLICATION_COMPONENT_RELEASE_SCHEMA = "fdai.application-release.v2"
+SCHEMA_EXPAND_JOB_SCHEMA = "fdai.schema-expand-job.v1"
+MIGRATION_CLASSIFICATION_SCHEMA = "fdai.migration-classification.v1"
+APPLICATION_RELEASE_SCHEMAS = frozenset(
+    {APPLICATION_RELEASE_SCHEMA, APPLICATION_COMPONENT_RELEASE_SCHEMA}
+)
+LIFECYCLE_RELEASE_SCHEMAS = frozenset({"fdai.runtime-release.v3", *APPLICATION_RELEASE_SCHEMAS})
+LIFECYCLE_IMAGE_SECTIONS = (
+    "services",
+    "sidecars",
+    "installation_agents",
+    "workloads",
+    "components",
+)
+_IDENTIFIER = re.compile(r"[a-z][a-z0-9-]{0,62}\Z", re.ASCII)
+_COMPONENT = re.compile(r"[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?\Z", re.ASCII)
+_DIGEST = re.compile(r"sha256:[0-9a-f]{64}\Z", re.ASCII)
+_REVISION_ID = re.compile(r"[A-Za-z0-9_]{1,128}\Z", re.ASCII)
+_FIELDS = frozenset(
+    {"schema_version", "product", "release_version", "source_commit", "platform_tag", "workloads"}
+)
+
+
+def is_product_id(value: object) -> bool:
+    return isinstance(value, str) and _IDENTIFIER.fullmatch(value) is not None
+
+
+class LifecycleRelease(SchemaMetadata, Protocol):
+    @property
+    def product(self) -> str | None: ...
+
+    @property
+    def schema_version(self) -> str: ...
+
+    @property
+    def source_commit(self) -> str: ...
+
+    @property
+    def platform_tag(self) -> str: ...
+
+    @property
+    def digest(self) -> str: ...
+
+    @property
+    def capability_maximums(self) -> Mapping[str, str]: ...
+
+    @property
+    def downtime_entities(self) -> tuple[str, ...]: ...
+
+    @property
+    def configuration_schema(self) -> ConfigurationSchema | None: ...
+
+    def to_mapping(self) -> dict[str, object]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class HttpWorkload:
+    image_digest: str
+    port: int = 8080
+    health_path: str = "/"
+    replicas: int = 1
+
+
+@dataclass(frozen=True, slots=True)
+class SchemaExpandMigration:
+    classification: Mapping[str, str]
+    active_deadline_seconds: int
+
+
+@dataclass(frozen=True, slots=True)
+class ApplicationRelease:
+    product: str
+    release_version: str
+    source_commit: str
+    platform_tag: str
+    digest: str
+    workloads: Mapping[str, HttpWorkload]
+    _catalog: bytes = field(repr=False)
+    schema_target: int = 0
+    schema_range: SchemaRange = SchemaRange(0, 0)
+    configuration_schema: ConfigurationSchema | None = None
+    schema_expand: SchemaExpandMigration | None = None
+    schema_version: str = APPLICATION_RELEASE_SCHEMA
+    components: Mapping[str, str] = field(default_factory=dict)
+    downtime_entities: tuple[str, ...] = field(default=(), init=False)
+
+    @property
+    def capability_maximums(self) -> Mapping[str, str]:
+        return {}
+
+    def to_mapping(self) -> dict[str, object]:
+        return load_json_object(self._catalog, label="application release", strict=True)
+
+
+def parse_lifecycle_release_manifest(raw: bytes) -> LifecycleRelease:
+    """Validate bounded strict JSON before either format reaches publication or execution."""
+    try:
+        document = load_json_object(raw, label="lifecycle release", strict=True)
+        schema_version = document.get("schema_version")
+        if schema_version not in APPLICATION_RELEASE_SCHEMAS:
+            return parse_runtime_release_manifest(raw)
+        section = (
+            "components" if schema_version == APPLICATION_COMPONENT_RELEASE_SCHEMA else "workloads"
+        )
+        required = (_FIELDS - {"workloads"}) | {section}
+        if (
+            not required
+            <= document.keys()
+            <= required
+            | {
+                "configuration_schema",
+                "schema",
+                "schema_expand",
+            }
+        ):
+            raise ValueError("application fields are invalid")
+        product = document["product"]
+        version = document["release_version"]
+        commit = document["source_commit"]
+        platform = document["platform_tag"]
+        if not isinstance(product, str) or not is_product_id(product):
+            raise ValueError("application product is invalid")
+        if not isinstance(version, str) or not is_release_id(version) or len(version) > 64:
+            raise ValueError("application version is invalid")
+        if not isinstance(commit, str) or re.fullmatch(r"[0-9a-f]{40}", commit) is None:
+            raise ValueError("application source is invalid")
+        if not isinstance(platform, str) or platform not in {"linux-x86_64", "linux-aarch64"}:
+            raise ValueError("application platform is invalid")
+        workloads = document[section]
+        if not isinstance(workloads, dict) or not 1 <= len(workloads) <= 64:
+            raise ValueError("application requires bounded workloads")
+        component_only = schema_version == APPLICATION_COMPONENT_RELEASE_SCHEMA
+        parsed_workloads = (
+            {}
+            if component_only
+            else {name: _workload(name, value) for name, value in workloads.items()}
+        )
+        parsed_components = (
+            {
+                name: _image_record(name, value, allowed={"image_digest", "image_ref"})
+                for name, value in workloads.items()
+            }
+            if component_only
+            else {}
+        )
+        configuration = (
+            parse_release_configuration_schema(document["configuration_schema"])
+            if "configuration_schema" in document
+            else None
+        )
+        if configuration is not None and configuration.release_version != version:
+            raise ValueError("application configuration version differs")
+        target, schema_range = (
+            _schema(document["schema"]) if "schema" in document else (0, SchemaRange(0, 0))
+        )
+        schema_expand = (
+            _schema_expand(document["schema_expand"]) if "schema_expand" in document else None
+        )
+        if schema_expand is not None and (
+            not component_only or target == 0 or not schema_expand.classification
+        ):
+            raise ValueError("schema expand Job requires a component Release schema transition")
+        catalog = canonical_bytes(document)
+        load_json_object(catalog, label="canonical application release", strict=True)
+        return ApplicationRelease(
+            product=product,
+            release_version=version,
+            source_commit=commit,
+            platform_tag=platform,
+            digest=canonical_digest(document),
+            workloads=MappingProxyType(parsed_workloads),
+            _catalog=catalog,
+            schema_target=target,
+            schema_range=schema_range,
+            configuration_schema=configuration,
+            schema_expand=schema_expand,
+            schema_version=str(schema_version),
+            components=MappingProxyType(parsed_components),
+        )
+    except RuntimeReleaseError:
+        raise
+    except (ValueError, TypeError, KeyError, RecursionError) as error:
+        raise RuntimeReleaseError("Lifecycle release metadata is invalid.") from error
+
+
+def _image_record(name: object, value: object, *, allowed: set[str]) -> str:
+    if not isinstance(name, str) or _COMPONENT.fullmatch(name) is None:
+        raise ValueError("application component is invalid")
+    if not isinstance(value, dict) or not {"image_digest"} <= value.keys() <= allowed:
+        raise ValueError("application workload fields are invalid")
+    digest = value["image_digest"]
+    if not isinstance(digest, str) or _DIGEST.fullmatch(digest) is None:
+        raise ValueError("application image must be digest-pinned")
+    if "image_ref" in value:
+        reference = value["image_ref"]
+        if (
+            not isinstance(reference, str)
+            or len(reference) > 512
+            or re.fullmatch(
+                r"[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?"
+                r"(?::[1-9][0-9]{0,4})?/"
+                r"[a-z0-9]+(?:[._-][a-z0-9]+)*(?:/[a-z0-9]+(?:[._-][a-z0-9]+)*)*"
+                r"@sha256:[0-9a-f]{64}",
+                reference,
+                re.ASCII,
+            )
+            is None
+            or reference.rsplit("@", 1)[1] != digest
+        ):
+            raise ValueError("application image source must match its signed digest")
+    return digest
+
+
+def _workload(name: object, value: object) -> HttpWorkload:
+    digest = _image_record(name, value, allowed={"image_digest", "port", "health_path", "replicas"})
+    if not isinstance(value, dict):
+        raise ValueError("application workload fields are invalid")
+    port = value.get("port", 8080)
+    path = value.get("health_path", "/")
+    replicas = value.get("replicas", 1)
+    if type(port) is not int or not 1 <= port <= 65535:
+        raise ValueError("application port is invalid")
+    if (
+        not isinstance(path, str)
+        or path.startswith("//")
+        or not re.fullmatch(r"/[A-Za-z0-9/._~-]{0,255}", path, re.ASCII)
+    ):
+        raise ValueError("application health path is invalid")
+    if type(replicas) is not int or not 1 <= replicas <= 3:
+        raise ValueError("application replicas are invalid")
+    return HttpWorkload(digest, port, path, replicas)
+
+
+def _schema_expand(value: object) -> SchemaExpandMigration:
+    if (
+        not isinstance(value, Mapping)
+        or set(value) != {"schema_version", "classification", "active_deadline_seconds"}
+        or value["schema_version"] != SCHEMA_EXPAND_JOB_SCHEMA
+        or not isinstance(value["classification"], Mapping)
+    ):
+        raise ValueError("schema expand Job is invalid")
+    classification = value["classification"]
+    if (
+        set(classification) != {"schema", "revisions"}
+        or classification["schema"] != MIGRATION_CLASSIFICATION_SCHEMA
+        or not isinstance(classification["revisions"], Mapping)
+        or not classification["revisions"]
+        or not all(
+            isinstance(revision, str)
+            and _REVISION_ID.fullmatch(revision)
+            and migration_class in {"expand", "contract"}
+            for revision, migration_class in classification["revisions"].items()
+        )
+    ):
+        raise ValueError("migration classification is invalid")
+    if any(
+        migration_class == "contract" for migration_class in classification["revisions"].values()
+    ):
+        raise ValueError("schema expand Job cannot contain contract revisions")
+    deadline = value["active_deadline_seconds"]
+    if type(deadline) is not int or not 60 <= deadline <= 3600:
+        raise ValueError("schema expand Job deadline is invalid")
+    return SchemaExpandMigration(
+        MappingProxyType(
+            {
+                str(revision): str(migration_class)
+                for revision, migration_class in classification["revisions"].items()
+            }
+        ),
+        deadline,
+    )
+
+
+def _schema(value: object) -> tuple[int, SchemaRange]:
+    if not isinstance(value, dict) or set(value) != {"target", "tolerates"}:
+        raise ValueError("application schema is invalid")
+    target = value["target"]
+    limits = value["tolerates"]
+    if not isinstance(limits, dict) or set(limits) != {"minimum", "maximum"}:
+        raise ValueError("application schema range is invalid")
+    minimum, maximum = limits["minimum"], limits["maximum"]
+    if any(type(item) is not int for item in (target, minimum, maximum)) or not (
+        0 <= minimum <= target <= maximum <= 2**31 - 1
+    ):
+        raise ValueError("application schema revisions are invalid")
+    return target, SchemaRange(minimum, maximum)

fdai_deployment_cli/lifecycle_self_upgrade.py

@@ -0,0 +1,202 @@
+"""Dual-slot self-upgrade controller for installation agents and Target Hubs."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass, replace
+from typing import Literal
+
+from fdai_deployment_cli.runtime_release import is_release_id
+
+SelfUpgradeComponent = Literal["lifecycle-agent", "infrastructure-agent", "target-hub"]
+SlotId = Literal["slot-a", "slot-b"]
+SelfUpgradeOutcome = Literal["upgraded", "rolled-back"]
+
+_SUPPORTED_COMPONENTS = frozenset({"lifecycle-agent", "infrastructure-agent", "target-hub"})
+_IMAGE_DIGEST = re.compile(r"sha256:[0-9a-f]{64}\Z", re.ASCII)
+
+
+def _other_slot(slot: SlotId) -> SlotId:
+    return "slot-b" if slot == "slot-a" else "slot-a"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SlotRuntime:
+    """State of one component slot copy."""
+
+    slot_id: SlotId
+    release_id: str | None
+    image_digest: str | None
+    running: bool
+    healthy: bool
+    write_authority: bool
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DualSlotState:
+    """Two-slot state for a lifecycle agent, infrastructure agent, or Target Hub."""
+
+    component: SelfUpgradeComponent
+    active_slot: SlotId
+    fencing_generation: int
+    slots: dict[SlotId, SlotRuntime]
+
+    def __post_init__(self) -> None:
+        if self.component not in _SUPPORTED_COMPONENTS:
+            raise ValueError("component is unsupported")
+        if self.active_slot not in ("slot-a", "slot-b"):
+            raise ValueError("active_slot is invalid")
+        if (
+            isinstance(self.fencing_generation, bool)
+            or not isinstance(self.fencing_generation, int)
+            or self.fencing_generation < 1
+        ):
+            raise ValueError("fencing_generation MUST be a positive integer")
+        if set(self.slots) != {"slot-a", "slot-b"}:
+            raise ValueError("slots MUST contain slot-a and slot-b")
+        writers = [slot_id for slot_id, s in self.slots.items() if s.write_authority]
+        if writers != [self.active_slot]:
+            raise ValueError("exactly the active slot MUST hold write_authority")
+
+    @classmethod
+    def initial(
+        cls,
+        *,
+        component: SelfUpgradeComponent,
+        release_id: str,
+        image_digest: str,
+        active_slot: SlotId = "slot-a",
+        fencing_generation: int = 1,
+    ) -> DualSlotState:
+        if not is_release_id(release_id):
+            raise ValueError("release_id MUST be canonical SemVer")
+        if _IMAGE_DIGEST.fullmatch(image_digest) is None:
+            raise ValueError("image_digest MUST be sha256:<64 hex>")
+        standby = _other_slot(active_slot)
+        return cls(
+            component=component,
+            active_slot=active_slot,
+            fencing_generation=fencing_generation,
+            slots={
+                active_slot: SlotRuntime(
+                    slot_id=active_slot,
+                    release_id=release_id,
+                    image_digest=image_digest,
+                    running=True,
+                    healthy=True,
+                    write_authority=True,
+                ),
+                standby: SlotRuntime(
+                    slot_id=standby,
+                    release_id=None,
+                    image_digest=None,
+                    running=False,
+                    healthy=False,
+                    write_authority=False,
+                ),
+            },
+        )
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SelfUpgradeResult:
+    """Result of one dual-slot self-upgrade attempt."""
+
+    outcome: SelfUpgradeOutcome
+    reason_code: str
+    state: DualSlotState
+
+
+class DualSlotUpgradeController:
+    """Start candidate without write authority, verify health, and cut over or roll back."""
+
+    def upgrade(
+        self,
+        state: DualSlotState,
+        *,
+        target_release_id: str,
+        target_image_digest: str,
+        check_candidate_health: Callable[[SelfUpgradeComponent, SlotId, str, str], bool],
+        verify_post_handoff_readback: Callable[[SelfUpgradeComponent, SlotId, int], bool]
+        | None = None,
+    ) -> SelfUpgradeResult:
+        if not is_release_id(target_release_id):
+            raise ValueError("target_release_id MUST be canonical SemVer")
+        if _IMAGE_DIGEST.fullmatch(target_image_digest) is None:
+            raise ValueError("target_image_digest MUST be sha256:<64 hex>")
+
+        old_slot_id = state.active_slot
+        candidate_slot_id = _other_slot(old_slot_id)
+        old_slot = state.slots[old_slot_id]
+
+        # 1. Candidate starts beside the old slot with write_authority=False.
+        candidate_healthy = bool(
+            check_candidate_health(
+                state.component,
+                candidate_slot_id,
+                target_release_id,
+                target_image_digest,
+            )
+        )
+        if not candidate_healthy:
+            rolled_back_slots = {
+                old_slot_id: old_slot,
+                candidate_slot_id: SlotRuntime(
+                    slot_id=candidate_slot_id,
+                    release_id=target_release_id,
+                    image_digest=target_image_digest,
+                    running=False,
+                    healthy=False,
+                    write_authority=False,
+                ),
+            }
+            return SelfUpgradeResult(
+                outcome="rolled-back",
+                reason_code="candidate_health_check_failed",
+                state=replace(state, slots=rolled_back_slots),
+            )
+
+        next_generation = state.fencing_generation + 1
+        if verify_post_handoff_readback is not None and not bool(
+            verify_post_handoff_readback(state.component, candidate_slot_id, next_generation)
+        ):
+            rolled_back_slots = {
+                old_slot_id: old_slot,
+                candidate_slot_id: SlotRuntime(
+                    slot_id=candidate_slot_id,
+                    release_id=target_release_id,
+                    image_digest=target_image_digest,
+                    running=False,
+                    healthy=False,
+                    write_authority=False,
+                ),
+            }
+            return SelfUpgradeResult(
+                outcome="rolled-back",
+                reason_code="post_handoff_readback_failed",
+                state=replace(state, slots=rolled_back_slots),
+            )
+
+        # 2. Transfer fenced write authority to the healthy candidate; keep old slot as rollback target.
+        upgraded_slots = {
+            old_slot_id: replace(old_slot, write_authority=False),
+            candidate_slot_id: SlotRuntime(
+                slot_id=candidate_slot_id,
+                release_id=target_release_id,
+                image_digest=target_image_digest,
+                running=True,
+                healthy=True,
+                write_authority=True,
+            ),
+        }
+        return SelfUpgradeResult(
+            outcome="upgraded",
+            reason_code="upgraded",
+            state=DualSlotState(
+                component=state.component,
+                active_slot=candidate_slot_id,
+                fencing_generation=next_generation,
+                slots=upgraded_slots,
+            ),
+        )