platformforge 0.1.0__py3-none-any.whl

platformforge/ops/risk.py

@@ -0,0 +1,216 @@
+"""Cycle 4 — mutation risk taxonomy (§31–35, ADR-0024).
+
+Risk classes R0–R5 plus decomposed dimensions — blast radius,
+environment, criticality, reversibility, security/identity/network/
+data/availability/cost impact, uncertainty, freshness, coverage,
+rollback confidence. The load-bearing rule: **unknown ≠ low**. Any
+unassessed dimension raises uncertainty, and unknown reversibility or
+rollback bumps the class — never downgrades it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+RISK_CLASSES = ("R0", "R1", "R2", "R3", "R4", "R5")
+RISK_RANK = {r: i for i, r in enumerate(RISK_CLASSES)}
+
+RISK_DIMENSIONS = ("blast_radius", "environment", "criticality",
+                   "reversibility", "security_impact", "identity_impact",
+                   "network_exposure", "data_impact", "availability_impact",
+                   "cost_impact", "uncertainty", "observation_freshness",
+                   "coverage_completeness", "rollback_confidence")
+
+REVERSIBILITY = ("fully-reversible", "conditionally-reversible",
+                 "hard-to-reverse", "irreversible", "unknown")
+
+# Per-dimension levels → numeric weight (higher = riskier)
+_LEVELS = {"none": 0, "low": 1, "medium": 2, "high": 3,
+           "critical": 4, "unknown": 3}
+
+# Action-type → default class ceiling/floor hints (typed actions only —
+# see ops/actions.py for the vocabulary).
+ACTION_BASE_RISK: dict[str, str] = {
+    "git.create_branch": "R0",
+    "git.apply_patch": "R1",
+    "git.commit": "R1",
+    "git.open_pr": "R2",
+    "ci.validate": "R0",
+    "policy.check": "R0",
+    "terraform.validate": "R0",
+    "terraform.plan": "R0",
+    "terraform.apply_saved_plan": "R3",
+    "tofu.plan": "R0",
+    "tofu.apply_saved_plan": "R3",
+    "argocd.sync": "R3",
+    "argocd.rollback": "R3",
+    "kubernetes.scale": "R2",
+    "kubernetes.rollout_restart": "R2",
+    "kubernetes.rollout_undo": "R3",
+    "kubernetes.annotate": "R1",
+    "k8s.observe": "R0",
+    "aws.observe": "R0",
+}
+
+# Escalators: contexts that raise class regardless of base.
+_DESTRUCTIVE_SIGNALS = ("delete", "destroy", "remove", "drop", "purge")
+_IDENTITY_SIGNALS = ("iam", "policy", "role", "permission", "trust")
+_DATA_SIGNALS = ("database", "rds", "bucket", "volume", "stateful",
+                 "persistent")
+
+
+@dataclass
+class RiskAssessment:
+    risk_class: str = "R0"
+    dimensions: dict[str, str] = field(default_factory=dict)
+    reversibility: str = "unknown"
+    escalation_reasons: list[str] = field(default_factory=list)
+    unknowns: list[str] = field(default_factory=list)
+
+    @property
+    def blocks_autonomy(self) -> bool:
+        """A5 experiments never run above R2 or with unknowns."""
+        return RISK_RANK[self.risk_class] > RISK_RANK["R2"] or \
+            bool(self.unknowns)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"risk_class": self.risk_class,
+                "reversibility": self.reversibility,
+                "dimensions": self.dimensions,
+                "escalation_reasons": self.escalation_reasons,
+                "unknowns": self.unknowns,
+                "blocks_autonomy": self.blocks_autonomy}
+
+
+def assess(action: str, params: dict[str, Any] | None = None,
+           context: dict[str, Any] | None = None) -> RiskAssessment:
+    """Deterministic risk classification for a typed action.
+
+    `params`   — action params (e.g. {"replicas": 5, "resource": ...})
+    `context`  — {environment, criticality, blast_radius, coverage,
+                  freshness, reversibility, data_impact, identity_impact,
+                  security_impact, network_exposure, cost_impact,
+                  rollback_confidence}
+    """
+    params = params or {}
+    ctx = context or {}
+    dims: dict[str, str] = {}
+    unknowns: list[str] = []
+    escalations: list[str] = []
+
+    base = ACTION_BASE_RISK.get(action)
+    if base is None:
+        base = "R5"
+        unknowns.append(f"unlisted-action:{action}")
+        escalations.append("unknown action type → R5 ceiling")
+
+    env = ctx.get("environment", "unknown")
+    dims["environment"] = env
+    if env == "prod" and RISK_RANK[base] < RISK_RANK["R3"]:
+        escalations.append("prod environment → ≥R3")
+        base = "R3"
+    elif env == "unknown":
+        unknowns.append("environment")
+        dims["environment"] = "unknown"
+
+    rev = ctx.get("reversibility", "unknown")
+    if rev not in REVERSIBILITY:
+        rev = "unknown"
+    if rev == "unknown":
+        unknowns.append("reversibility")
+    elif rev == "irreversible":
+        escalations.append("irreversible → ≥R4")
+        if RISK_RANK[base] < RISK_RANK["R4"]:
+            base = "R4"
+    elif rev == "hard-to-reverse":
+        escalations.append("hard-to-reverse → ≥R3")
+        if RISK_RANK[base] < RISK_RANK["R3"]:
+            base = "R3"
+    dims["reversibility"] = rev
+
+    for dim in ("criticality", "blast_radius", "security_impact",
+                "identity_impact", "network_exposure", "data_impact",
+                "availability_impact", "cost_impact",
+                "rollback_confidence", "observation_freshness",
+                "coverage_completeness"):
+        v = ctx.get(dim, "unknown")
+        dims[dim] = v
+        if v == "unknown":
+            unknowns.append(dim)
+        elif v in ("high", "critical") and dim != "rollback_confidence":
+            # high *confidence* is good — never an escalation
+            escalations.append(f"{dim}={v}")
+
+    # Content signals — params describing destructive/identity/data ops
+    blob = repr(params).lower()
+    if any(s in blob for s in _DESTRUCTIVE_SIGNALS):
+        escalations.append("destructive signal in params → ≥R4")
+        base = "R4" if RISK_RANK[base] < RISK_RANK["R4"] else base
+    if any(s in blob for s in _IDENTITY_SIGNALS):
+        escalations.append("identity/security surface")
+        if ctx.get("identity_impact", "unknown") in ("high", "critical",
+                                                   "unknown"):
+            base = "R4" if RISK_RANK[base] < RISK_RANK["R4"] else base
+    if any(s in blob for s in _DATA_SIGNALS) and \
+            ctx.get("data_impact", "unknown") in ("high", "critical"):
+        escalations.append("data-critical target")
+        base = "R4" if RISK_RANK[base] < RISK_RANK["R4"] else base
+
+    if dims.get("blast_radius") in ("high", "critical"):
+        base = "R4" if RISK_RANK[base] < RISK_RANK["R4"] else base
+    if dims.get("rollback_confidence") == "unknown":
+        escalations.append("rollback confidence unknown")
+
+    return RiskAssessment(risk_class=base, dimensions=dims,
+                          reversibility=rev,
+                          escalation_reasons=escalations,
+                          unknowns=sorted(set(unknowns)))
+
+
+def classify_reversibility(action: str, params: dict[str, Any] | None = None,
+                           context: dict[str, Any] | None = None) -> str:
+    """§34–35 — reversibility is assessed, never invented."""
+    params = params or {}
+    ctx = context or {}
+    blob = repr(params).lower()
+    if any(s in blob for s in _DESTRUCTIVE_SIGNALS):
+        if ctx.get("data_present") or "data" in blob:
+            return "irreversible"
+        return "hard-to-reverse"
+    if action in ("kubernetes.scale", "kubernetes.annotate",
+                  "kubernetes.rollout_restart", "git.create_branch"):
+        return "fully-reversible"
+    if action in ("git.open_pr", "git.apply_patch", "git.commit"):
+        return "conditionally-reversible"
+    if action in ("terraform.apply_saved_plan", "tofu.apply_saved_plan",
+                  "argocd.sync"):
+        return ctx.get("reversibility_hint", "conditionally-reversible")
+    if action in ("kubernetes.rollout_undo", "argocd.rollback"):
+        return "conditionally-reversible"
+    return "unknown"
+
+
+def rollback_confidence(status: str | None) -> str:
+    """Cycle 4.1 §F — fold the material-built rollback status into the
+    risk model. executable → high confidence; requires-replan /
+    manual-only → conditional; impossible → low; unresolved/unknown →
+    unknown (which *escalates* the class, never downgrades)."""
+    return {"executable": "high",
+            "requires-replan": "conditional",
+            "manual-only": "low",
+            "impossible": "low",
+            "unresolved": "unknown"}.get(status or "", "unknown")
+
+
+def reversibility_for_status(status: str | None, current: str
+                             ) -> str:
+    """A plan whose rollback is impossible/manual-only must not keep a
+    fully-reversible rating — worst-of wins."""
+    worse = {"impossible": "irreversible",
+             "manual-only": "hard-to-reverse",
+             "unresolved": "unknown"}.get(status or "")
+    order = {r: i for i, r in enumerate(REVERSIBILITY)}
+    if worse and order.get(worse, 0) > order.get(current, 0):
+        return worse
+    return current

platformforge/ops/rollback.py

@@ -0,0 +1,287 @@
+"""Cycle 4.1 — rollback planning v2 (§21–43).
+
+A `rollback_action` name alone is not a rollback. Correct reversal =
+forward intent + captured pre-state + execution result + strategy.
+`RollbackPlan` now carries a per-step strategy, the material hashes it
+depends on, and an honest `status`:
+
+    executable        — typed actions validated, material complete
+    requires-replan   — reversal needs a NEW governed plan (terraform)
+    manual-only       — human procedure required
+    impossible        — factually cannot be undone
+    unresolved        — insufficient evidence to claim any of the above
+
+"rollback ready" is only ever said when status == executable (§37).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from platformforge.live.models import now_iso
+from platformforge.ops.actions import spec_for, validate_action
+from platformforge.ops.rollback_builders import BUILDERS
+
+ROLLBACK_SCHEMA = "platformforge/rollback-plan/v2"
+
+STRATEGIES = ("direct-inverse", "source-revert", "previous-revision",
+              "compensating-operation", "replan-required",
+              "manual-only", "impossible", "unknown")
+
+# legacy v1 strategy names → v2 (envelopes persisted before 4.1)
+LEGACY_STRATEGY = {
+    "git-revert": "direct-inverse",
+    "terraform-revert": "replan-required",
+    "previous-artifact": "previous-revision",
+    "argo-rollback": "previous-revision",
+    "rollout-undo": "previous-revision",
+    "compensating": "compensating-operation",
+    "manual-only": "manual-only",
+    "impossible": "impossible",
+    "unknown": "unknown",
+}
+
+STATUSES = ("executable", "requires-replan", "manual-only",
+            "impossible", "unresolved")
+
+TRIGGERS = ("verification-failed", "slo-regression", "manual",
+            "policy-revocation", "incident")
+
+# worst-first rollup across steps
+_SEVERITY = {"impossible": 5, "unknown": 4, "manual-only": 3,
+             "replan-required": 2}
+
+
+@dataclass
+class RollbackPlan:
+    rollback_id: str = ""
+    trigger: str = "verification-failed"
+    strategy: str = "unknown"            # worst-of step strategies
+    status: str = "unresolved"           # §36
+    steps: list[dict[str, Any]] = field(default_factory=list)
+    actions: list[dict[str, Any]] = field(default_factory=list)  # executable
+    material_hashes: list[str] = field(default_factory=list)
+    replans: list[dict[str, Any]] = field(default_factory=list)
+    preconditions: list[str] = field(default_factory=list)
+    limitations: list[str] = field(default_factory=list)
+    data_impact: str = "unknown"
+    expected_delta: dict[str, Any] = field(default_factory=dict)
+    automatic: bool = False              # §38–39 — lab/non-prod only
+
+    def validate(self) -> list[dict[str, Any]]:
+        v = []
+        if self.strategy not in STRATEGIES:
+            v.append({"refusal": "PF-OPS-BAD-ROLLBACK-TYPE",
+                      "unlock": f"strategy in {STRATEGIES}"})
+        if self.status not in STATUSES:
+            v.append({"refusal": "PF-OPS-BAD-ROLLBACK-STATUS",
+                      "unlock": f"status in {STATUSES}"})
+        if self.status in ("manual-only", "impossible", "unresolved",
+                           "requires-replan") and self.automatic:
+            v.append({"refusal": "PF-OPS-ROLLBACK-CONTRADICTION",
+                      "unlock": "only status=executable may be "
+                                "automatic (§38)"})
+        # §35 — every executable action must pass typed validation
+        for a in self.actions:
+            bad = validate_action(a.get("action", ""),
+                                  a.get("params", {}))
+            if bad:
+                v.append(bad)
+        return v
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": ROLLBACK_SCHEMA, "rollback_id": self.rollback_id,
+                "trigger": self.trigger, "strategy": self.strategy,
+                "status": self.status, "steps": self.steps,
+                "actions": self.actions,
+                "material_hashes": self.material_hashes,
+                "replans": self.replans,
+                "preconditions": self.preconditions,
+                "limitations": self.limitations,
+                "data_impact": self.data_impact,
+                "expected_delta": self.expected_delta,
+                "automatic": self.automatic,
+                "created_at": now_iso()}
+
+
+def _status_rollup(step_statuses: list[str]) -> str:
+    if not step_statuses:
+        return "unresolved"
+    if "impossible" in step_statuses:
+        return "impossible"
+    if "unresolved" in step_statuses:
+        return "unresolved"
+    if "manual-only" in step_statuses:
+        return "manual-only"
+    if "requires-replan" in step_statuses:
+        return "requires-replan"
+    return "executable"
+
+
+def _strategy_rollup(strategies: set[str]) -> str:
+    if not strategies:
+        return "unknown"
+    worst = max(strategies,
+                key=lambda s: _SEVERITY.get(s, 1))
+    if len(strategies) > 1 and _SEVERITY.get(worst, 0) == 0:
+        return "compensating-operation"   # mixed executable → saga
+    return worst
+
+
+def build_rollback_plan(steps: list[dict[str, Any]],
+                        materials: dict[str, Any] | None = None,
+                        context: dict[str, Any] | None = None
+                        ) -> RollbackPlan:
+    """§30 pipeline — ActionSpec contract + captured materials → plan.
+
+    `steps`: forward steps [{step_id, action, params}].
+    `materials`: {step_id: RollbackMaterial|dict} captured pre/during
+    forward execution (empty at plan-time → honest degraded status).
+    """
+    ctx = context or {}
+    materials = materials or {}
+    plan = RollbackPlan()
+    strategies: set[str] = set()
+    statuses: list[str] = []
+    for s in steps:
+        act = s.get("action", "")
+        spec = spec_for(act)
+        mat = materials.get(s.get("step_id"))
+        mat_d = (mat.to_dict() if hasattr(mat, "to_dict")
+                 else dict(mat or {}))
+        if spec is None:
+            strategies.add("unknown")
+            statuses.append("unresolved")
+            plan.limitations.append(f"{act}: not a typed action")
+            continue
+        st_strategy = spec.rollback_strategy
+        strategies.add(st_strategy)
+        step_rec = {"step_id": s.get("step_id"), "action": act,
+                    "strategy": st_strategy,
+                    "material_hash": mat_d.get("hash")}
+        if mat_d.get("hash"):
+            plan.material_hashes.append(mat_d["hash"])
+        missing = [k for k in spec.pre_state_requirements
+                   if k not in mat_d.get("pre_state", {})]
+        if st_strategy in ("manual-only", "impossible", "unknown"):
+            statuses.append(
+                "manual-only" if st_strategy == "manual-only"
+                else "impossible" if st_strategy == "impossible"
+                else "unresolved")
+            step_rec["status"] = statuses[-1]
+        elif st_strategy == "replan-required":
+            statuses.append("requires-replan")
+            step_rec["status"] = "requires-replan"
+            builder = BUILDERS.get(spec.rollback_builder)
+            if builder:
+                out = builder(s.get("params", {}), mat_d, ctx) or {}
+                if out.get("replan"):
+                    plan.replans.append({**out["replan"],
+                                         "step_id": s.get("step_id"),
+                                         "action": act})
+        elif missing:
+            statuses.append("unresolved")
+            step_rec["status"] = "unresolved"
+            step_rec["missing_pre_state"] = missing
+            plan.limitations.append(
+                f"{act}: missing pre-state {missing} — strategy "
+                f"{st_strategy} not executable (§31)")
+        else:
+            builder = BUILDERS.get(spec.rollback_builder)
+            out = builder(s.get("params", {}), mat_d, ctx) \
+                if builder else None
+            if out and out.get("action"):
+                bad = validate_action(out["action"],
+                                      out.get("params", {}))
+                if bad:
+                    statuses.append("unresolved")
+                    step_rec["status"] = "unresolved"
+                    plan.limitations.append(
+                        f"{act}: built rollback failed validation — "
+                        f"{bad['refusal']}")
+                else:
+                    statuses.append("executable")
+                    step_rec["status"] = "executable"
+                    step_rec["rollback_action"] = out["action"]
+                    step_rec["rationale"] = out.get("rationale", "")
+                    plan.actions.append(
+                        {"action": out["action"],
+                         "params": out["params"],
+                         "compensates": s.get("step_id"),
+                         "material_hash": mat_d.get("hash")})
+            else:
+                statuses.append("unresolved")
+                step_rec["status"] = "unresolved"
+                plan.limitations.append(
+                    f"{act}: builder returned no action — material "
+                    "insufficient")
+        plan.steps.append(step_rec)
+
+    plan.strategy = _strategy_rollup(strategies)
+    plan.status = _status_rollup(statuses)
+    # §38–39 — auto-rollback: executable + non-prod + explicitly allowed
+    plan.automatic = bool(ctx.get("automatic_allowed")) and \
+        plan.status == "executable"
+    if ctx.get("environment") in ("prod", "production") and \
+            plan.automatic:
+        plan.automatic = False
+        plan.limitations.append("auto-rollback disabled for prod (§39)")
+    elif plan.automatic:
+        plan.limitations.append("auto-rollback allowed only in lab/"
+                                "non-prod (§38–39)")
+    return plan
+
+
+def terraform_plan_reuse_check(forward_plan_hash: str,
+                               rollback_plan_hash: str
+                               ) -> dict[str, Any] | None:
+    """§18 invariant — a saved forward plan is never a rollback plan."""
+    if forward_plan_hash and forward_plan_hash == rollback_plan_hash:
+        return {"refusal": "PF-OPS-PLAN-REUSE",
+                "unlock": "rollback via terraform must plan against "
+                          "reverted source — never reuse the forward "
+                          "saved plan"}
+    return None
+
+
+# --- backward-compat -----------------------------------------------------
+
+def derive_rollback(actions: list[dict[str, Any]],
+                    context: dict[str, Any] | None = None) -> RollbackPlan:
+    """Plan-time derivation (no materials yet): declares per-step
+    strategies + capture requirements. Status stays `unresolved`
+    until materials exist — never claims executable early."""
+    steps = [{"step_id": a.get("step_id", f"s{i}"),
+              "action": a.get("action", ""),
+              "params": a.get("params", {})}
+             for i, a in enumerate(actions)]
+    return build_rollback_plan(steps, materials=None, context=context)
+
+
+def compensate_for(steps: list[dict[str, Any]],
+                   materials: dict[str, Any] | None = None,
+                   ) -> dict[str, Any]:
+    """§105–106 — saga compensation for *completed* forward steps,
+    reverse order, built from materials (not forward params)."""
+    comp: list[dict[str, Any]] = []
+    manual: list[str] = []
+    mats = materials or {}
+    for s in reversed(steps):
+        if s.get("status") != "completed":
+            continue
+        spec = spec_for(s.get("action", ""))
+        mat = mats.get(s.get("step_id"))
+        mat_d = (mat.to_dict() if hasattr(mat, "to_dict")
+                 else dict(mat or {}))
+        out = None
+        if spec and spec.rollback_builder in BUILDERS:
+            out = BUILDERS[spec.rollback_builder](
+                s.get("params", {}), mat_d, {})
+        if out and out.get("action"):
+            comp.append({"action": out["action"],
+                         "params": out["params"],
+                         "compensates": s.get("step_id")})
+        else:
+            manual.append(s.get("step_id", "?"))
+    return {"compensating_actions": comp, "manual_steps": manual}

platformforge/ops/rollback_builders.py

@@ -0,0 +1,163 @@
+"""Cycle 4.1 — per-action rollback builders (§33–35).
+
+One registry, one builder per mutating action — no giant if-chain.
+A builder receives (params, material, ctx) and returns a typed rollback
+action dict {action, params, rationale} or None when the captured
+material is insufficient (which degrades the plan honestly — never
+invents parameters). Every produced action is re-checked with
+`validate_action` before the plan may be marked `executable` (§35).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+Builder = Callable[[dict[str, Any], dict[str, Any], dict[str, Any]],
+                   dict[str, Any] | None]
+
+
+def _k8s_common(params: dict[str, Any]) -> dict[str, Any]:
+    return {k: params[k] for k in
+            ("kind", "name", "namespace", "context") if k in params}
+
+
+def build_k8s_scale(params, material, ctx):
+    """§9 — scale back to the *captured* replica count, never the
+    forward param."""
+    pre = material.get("pre_state", {})
+    if "replicas" not in pre:
+        return None
+    p = {**_k8s_common(params), "replicas": pre["replicas"]}
+    if pre.get("resource_version"):
+        p["resource_version"] = pre["resource_version"]
+    return {"action": "kubernetes.scale", "params": p,
+            "rationale": "direct-inverse from captured replicas="
+                         f"{pre['replicas']}"}
+
+
+def build_k8s_annotate(params, material, ctx):
+    """§10 — restore the captured annotation map; keys the forward
+    step *added* (absent in pre-state) go to remove_annotations."""
+    pre = material.get("pre_state", {})
+    if "annotations" not in pre:
+        return None
+    prev = dict(pre["annotations"])
+    forward = set(params.get("annotations") or {})
+    added = sorted(k for k in forward if k not in prev)
+    p = {**_k8s_common(params),
+         "annotations": {k: v for k, v in prev.items() if k in forward}}
+    if added:
+        p["remove_annotations"] = added
+    if pre.get("resource_version"):
+        p["resource_version"] = pre["resource_version"]
+    return {"action": "kubernetes.annotate", "params": p,
+            "rationale": f"restore {len(p['annotations'])} keys, "
+                         f"remove {added or 'none'}"}
+
+
+def build_k8s_rollout_restart(params, material, ctx):
+    pre = material.get("pre_state", {})
+    if "revision" not in pre:
+        return None
+    return {"action": "kubernetes.rollout_undo",
+            "params": {**_k8s_common(params),
+                       "to_revision": pre["revision"]},
+            "rationale": f"previous-revision → {pre['revision']}"}
+
+
+def build_git_apply_patch(params, material, ctx):
+    """§11 — revert the commit the forward step *produced*."""
+    res = material.get("execution_result", {})
+    sha = res.get("resulting_commit") or res.get("commit_sha")
+    if not sha:
+        return None
+    return {"action": "git.revert_commit",
+            "params": {"repo": params.get("repo", ""), "commit_sha": sha},
+            "rationale": f"revert resulting_commit {sha[:12]}"}
+
+
+build_git_commit = build_git_apply_patch
+
+
+def build_git_open_pr(params, material, ctx):
+    res = material.get("execution_result", {})
+    pr = res.get("pr") or res.get("pr_number")
+    if not pr:
+        return None
+    return {"action": "git.close_pr",
+            "params": {"repo": params.get("repo", ""), "pr": pr},
+            "rationale": f"close pr {pr}"}
+
+
+def build_git_create_branch(params, material, ctx):
+    if not params.get("branch"):
+        return None
+    return {"action": "git.delete_branch",
+            "params": {"repo": params.get("repo", ""),
+                       "branch": params["branch"]},
+            "rationale": "direct-inverse delete created branch"}
+
+
+def build_git_delete_branch(params, material, ctx):
+    """Previous-revision: recreate the branch at its captured sha."""
+    pre = material.get("pre_state", {})
+    if not pre.get("branch_sha"):
+        return None
+    return {"action": "git.create_branch",
+            "params": {"repo": params.get("repo", ""),
+                       "branch": params.get("branch", ""),
+                       "base": pre["branch_sha"]},
+            "rationale": f"recreate branch at {pre['branch_sha'][:12]}"}
+
+
+def build_argocd_sync(params, material, ctx):
+    """§13–14 — prefer argo history rollback; when source-of-truth is
+    Git and a revert commit is supplied, git-revert is the preferred
+    path (declared, not silently chosen)."""
+    pre = material.get("pre_state", {})
+    sot = (material.get("source_of_truth") or {}).get("resolved", "")
+    if sot in ("git", "gitops") and pre.get("git_revert_commit"):
+        return {"action": "git.revert_commit",
+                "params": {"repo": pre.get("repo", params.get("repo", "")),
+                           "commit_sha": pre["git_revert_commit"]},
+                "rationale": "source-revert via git (SoT=git)"}
+    hid = pre.get("history_id")
+    if hid is None:
+        return None
+    return {"action": "argocd.rollback",
+            "params": {"app": params.get("app", ""), "history_id": hid},
+            "rationale": f"previous-revision history_id={hid}"}
+
+
+def build_terraform_apply(params, material, ctx):
+    """§15–19 — NEVER reuse the forward saved plan. Returns a
+    replan descriptor, not an action: the rollback is a *new governed
+    operation* (source-revert → plan BA → approval → apply BA)."""
+    pre = material.get("pre_state", {})
+    out = {"replan": {
+        "source_ref": pre.get("source_ref", ""),
+        "workspace": pre.get("workspace", ""),
+        "state_serial": pre.get("state_serial"),
+        "forward_plan_hash": (params.get("plan_hash") or
+                              pre.get("plan_hash", "")),
+        "resource_addresses": list(pre.get("resource_addresses", [])),
+    }}
+    return out  # deliberate: no executable action
+
+
+# Registry — action → builder. Mutating actions missing here degrade to
+# unknown (the honest answer), never to a guessed inverse.
+BUILDERS: dict[str, Builder] = {
+    "kubernetes.scale": build_k8s_scale,
+    "kubernetes.annotate": build_k8s_annotate,
+    "kubernetes.rollout_restart": build_k8s_rollout_restart,
+    "git.apply_patch": build_git_apply_patch,
+    "git.commit": build_git_commit,
+    "git.open_pr": build_git_open_pr,
+    "git.create_branch": build_git_create_branch,
+    "git.delete_branch": build_git_delete_branch,
+    "argocd.sync": build_argocd_sync,
+    "terraform.apply_saved_plan": build_terraform_apply,
+    "tofu.apply_saved_plan": build_terraform_apply,
+}