platformforge 0.1.0__py3-none-any.whl

platformforge/ops/gates.py

@@ -0,0 +1,135 @@
+"""Cycle 4 phase Q — FinOps cost delta + security gates.
+
+CostDelta is an estimate, not a guess: current/planned/delta/basis/
+confidence/source. Security gates are deterministic checks over
+declared change context (IAM, exposure, provenance, vulnerabilities);
+each returns pass|fail|unknown — unknown blocks production paths.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from platformforge.live.models import now_iso
+
+GATE_STATUS = ("pass", "fail", "unknown", "skipped")
+
+
+@dataclass
+class CostDelta:
+    current_monthly: float | None = None
+    planned_monthly: float | None = None
+    currency: str = "USD"
+    basis: str = ""               # estimate|observed-billing|unit-price
+    confidence: str = "unknown"   # high|medium|low|unknown
+    source: str = ""              # finops-db|aws-pricing|manual|…
+    notes: list[str] = field(default_factory=list)
+
+    @property
+    def delta(self) -> float | None:
+        if self.current_monthly is None or self.planned_monthly is None:
+            return None
+        return round(self.planned_monthly - self.current_monthly, 2)
+
+    def gate(self, *, budget_increase_max: float | None = None,
+             increase_pct_max: float | None = None) -> dict[str, Any]:
+        """Budget guard: exceeds → fail; no estimate → unknown
+        (never silently pass)."""
+        if self.delta is None:
+            return {"gate": "cost", "status": "unknown",
+                    "detail": "no cost estimate — unknown ≠ zero"}
+        if budget_increase_max is not None \
+                and self.delta > budget_increase_max:
+            return {"gate": "cost", "status": "fail",
+                    "detail": f"+{self.delta} > budget "
+                              f"{budget_increase_max}"}
+        if increase_pct_max is not None and self.current_monthly:
+            pct = self.delta / self.current_monthly * 100
+            if pct > increase_pct_max:
+                return {"gate": "cost", "status": "fail",
+                        "detail": f"+{pct:.1f}% > {increase_pct_max}%"}
+        return {"gate": "cost", "status": "pass",
+                "delta": self.delta, "confidence": self.confidence}
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": "platformforge/cost-delta/v1",
+                "current_monthly": self.current_monthly,
+                "planned_monthly": self.planned_monthly,
+                "delta": self.delta, "currency": self.currency,
+                "basis": self.basis, "confidence": self.confidence,
+                "source": self.source, "notes": self.notes,
+                "at": now_iso()}
+
+
+# --- security gates ------------------------------------------------------
+
+def gate_iam_change(diff: dict[str, Any]) -> dict[str, Any]:
+    """IAM gate — wildcard actions/resources or admin policy adds fail;
+    no IAM diff → skipped."""
+    adds = ((diff.get("adds") or {}).get("iam") or [])
+    if not adds and not ((diff.get("changes") or {}).get("iam")):
+        return {"gate": "iam", "status": "skipped"}
+    bad = [p for p in adds if isinstance(p, dict)
+           and ("*" in str(p.get("actions", ""))
+                or "*" in str(p.get("resources", ""))
+                or p.get("admin"))]
+    return {"gate": "iam",
+            "status": "fail" if bad else "pass",
+            "violations": bad}
+
+
+def gate_network_exposure(diff: dict[str, Any]) -> dict[str, Any]:
+    """Exposure gate — new 0.0.0.0/0 ingress or public LB fails."""
+    adds = ((diff.get("adds") or {}).get("network") or [])
+    if not adds:
+        return {"gate": "exposure", "status": "skipped"}
+    bad = [n for n in adds if isinstance(n, dict)
+           and (n.get("cidr") in ("0.0.0.0/0", "::/0")
+                or n.get("public") is True)]
+    return {"gate": "exposure",
+            "status": "fail" if bad else "pass",
+            "violations": bad}
+
+
+def gate_provenance(ctx: dict[str, Any]) -> dict[str, Any]:
+    """Artifact provenance — image/artifact must declare signature +
+    SBOM + source ref when artifacts are touched."""
+    artifacts = ctx.get("artifacts") or []
+    if not artifacts:
+        return {"gate": "provenance", "status": "skipped"}
+    bad = [a.get("ref", "?") for a in artifacts
+           if not (a.get("signed") and a.get("sbom"))]
+    if not artifacts:
+        return {"gate": "provenance", "status": "unknown"}
+    return {"gate": "provenance",
+            "status": "fail" if bad else "pass",
+            "violations": bad}
+
+
+def gate_vulnerabilities(vuln_scan: dict[str, Any] | None
+                         ) -> dict[str, Any]:
+    """Vuln gate — critical/high new findings fail; no scan → unknown."""
+    if vuln_scan is None:
+        return {"gate": "vulnerabilities", "status": "unknown",
+                "detail": "no scan supplied — unknown ≠ clean"}
+    new = vuln_scan.get("new_findings") or []
+    sev = [v for v in new if v.get("severity") in ("critical", "high")]
+    return {"gate": "vulnerabilities",
+            "status": "fail" if sev else "pass",
+            "violations": [v.get("id") for v in sev]}
+
+
+def security_gates(diff: dict[str, Any] | None = None,
+                   ctx: dict[str, Any] | None = None,
+                   vuln_scan: dict[str, Any] | None = None
+                   ) -> dict[str, Any]:
+    """Run all applicable gates; verdict = worst status
+    (fail > unknown > skipped > pass)."""
+    diff = diff or {}
+    ctx = ctx or {}
+    gates = [gate_iam_change(diff), gate_network_exposure(diff),
+             gate_provenance(ctx), gate_vulnerabilities(vuln_scan)]
+    rank = {"fail": 3, "unknown": 2, "skipped": 1, "pass": 0}
+    verdict = max(gates, key=lambda g: rank.get(g["status"], 2))["status"]
+    return {"verdict": verdict, "gates": gates, "at": now_iso()}

platformforge/ops/goldenpath.py

@@ -0,0 +1,180 @@
+"""Cycle 4 phase P — Golden Path lifecycle + PlatformRequest.
+
+A PlatformRequest is a governed service request. Its lifecycle is an
+explicit state machine:
+
+    request → validate → plan → policy → approve → provision →
+    observe → score → upgrade → decommission
+
+Every transition beyond `plan` requires receipts from earlier stages —
+policy decision, cost estimate, security review, approval — nothing is
+implicitly skipped. Production readiness is deterministic and preserves
+unknown ≠ zero (reuses scorecards' axis semantics).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from platformforge.live.models import canonical_hash, now_iso
+
+REQUEST_STATES = ("requested", "validated", "planned",
+                  "policy-reviewed", "approved", "provisioned",
+                  "observed", "scored", "upgrade-planned",
+                  "decommissioned", "rejected")
+
+_TRANSITIONS: dict[str, tuple[str, ...]] = {
+    "requested": ("validated", "rejected"),
+    "validated": ("planned", "rejected"),
+    "planned": ("policy-reviewed", "rejected"),
+    "policy-reviewed": ("approved", "rejected"),
+    "approved": ("provisioned", "rejected"),
+    "provisioned": ("observed",),
+    "observed": ("scored",),
+    "scored": ("upgrade-planned", "decommissioned"),
+    "upgrade-planned": ("policy-reviewed", "decommissioned"),
+    "decommissioned": (),
+    "rejected": (),
+}
+
+
+@dataclass
+class PlatformRequest:
+    request_id: str = ""
+    requester: str = ""
+    team: str = ""
+    kind: str = ""                # service|database|cache|pipeline|…
+    template: str = ""            # golden-path id
+    params: dict[str, Any] = field(default_factory=dict)
+    environment: str = ""
+    state: str = "requested"
+    receipts: list[dict[str, Any]] = field(default_factory=list)
+    history: list[dict[str, Any]] = field(default_factory=list)
+
+    def hash(self) -> str:
+        return "sha256:" + canonical_hash({
+            "request_id": self.request_id, "kind": self.kind,
+            "template": self.template, "params": self.params,
+            "environment": self.environment, "requester": self.requester})
+
+    def transition(self, to: str, *, receipt: dict[str, Any] | None = None,
+                   actor: str = "system") -> dict[str, Any]:
+        allowed = _TRANSITIONS.get(self.state, ())
+        if to not in allowed:
+            return {"refusal": "PF-OPS-REQ-BAD-TRANSITION",
+                    "unlock": f"from {self.state} allowed: "
+                              f"{allowed or 'none'}",
+                    "from": self.state, "to": to}
+        # gate checks — receipts required before advancing; the receipt
+        # carried by this transition counts (the stage produces it).
+        need = _RECEIPT_REQUIREMENTS.get(to, ())
+        have = {r.get("kind") for r in self.receipts}
+        if receipt:
+            have.add(receipt.get("kind"))
+        missing = [k for k in need if k not in have]
+        if missing:
+            return {"refusal": "PF-OPS-REQ-MISSING-RECEIPT",
+                    "unlock": f"attach receipts: {missing}",
+                    "from": self.state, "to": to}
+        self.state = to
+        self.history.append({"to": to, "at": now_iso(), "actor": actor,
+                             "receipt": (receipt or {}).get("kind", "")})
+        if receipt:
+            self.receipts.append(receipt)
+        return {"ok": True, "state": to}
+
+    def to_change_intent(self, steps: list | None = None):
+        """§128–129 — a Golden Path provisions through the *same*
+        governed contracts as everything else: emit a ChangeIntent
+        that feeds intent → plan → policy → approval → execute.
+        There is no parallel provisioning workflow."""
+        from platformforge.ops.models import ChangeIntent
+        return ChangeIntent(
+            intent_id=f"req-{self.request_id}",
+            requested_by=self.requester,
+            owner=self.team,
+            target_resources=list(self.params.get("resources", [])),
+            desired_change={"template": self.template,
+                            "kind": self.kind,
+                            "params": self.params},
+            risk_context={"environment": self.environment},
+            expected_outcome=f"golden path {self.template} provisioned "
+                             f"for {self.team}")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": "platformforge/platform-request/v1",
+                "request_id": self.request_id, "requester": self.requester,
+                "team": self.team, "kind": self.kind,
+                "template": self.template, "params": self.params,
+                "environment": self.environment, "state": self.state,
+                "hash": self.hash(), "receipts": self.receipts,
+                "history": self.history}
+
+
+# stage → receipt kinds that must exist (prior receipts + the one
+# carried by the transition itself)
+_RECEIPT_REQUIREMENTS: dict[str, tuple[str, ...]] = {
+    "validated": ("validation",),
+    "planned": ("plan",),
+    "policy-reviewed": ("policy-decision",),
+    "approved": ("policy-decision", "cost-estimate", "security-review",
+                 "approval"),
+    "provisioned": ("execution",),
+    "observed": ("observation",),
+    "scored": ("scorecard",),
+}
+
+
+def validate_request(req: PlatformRequest,
+                     templates: dict[str, Any] | None = None
+                     ) -> dict[str, Any]:
+    """Deterministic request validation — template exists, required
+    inputs present + type-checked, environment declared."""
+    findings = []
+    ok = True
+    if not req.requester or not req.team:
+        findings.append({"refusal": "PF-OPS-REQ-NO-OWNER",
+                         "unlock": "declare requester + team"})
+        ok = False
+    if req.environment not in ("dev", "staging", "prod", "lab"):
+        findings.append({"refusal": "PF-OPS-REQ-BAD-ENV",
+                         "unlock": "environment ∈ dev|staging|prod|lab"})
+        ok = False
+    tpl = (templates or {}).get(req.template)
+    if req.template and tpl is None:
+        findings.append({"refusal": "PF-OPS-REQ-UNKNOWN-TEMPLATE",
+                         "unlock": f"template {req.template} not in "
+                                   "golden-path library"})
+        ok = False
+    elif tpl is not None:
+        for inp in tpl.get("inputs", []):
+            name = inp.get("name")
+            if inp.get("required", True) and name not in req.params:
+                findings.append({"refusal": "PF-OPS-REQ-MISSING-INPUT",
+                                 "unlock": f"param '{name}' required "
+                                           f"by {req.template}"})
+                ok = False
+    return {"ok": ok, "findings": findings,
+            "receipt": {"kind": "validation", "ok": ok,
+                        "at": now_iso()}}
+
+
+def readiness_score(card: dict[str, Any]) -> dict[str, Any]:
+    """Production readiness from a scorecard dict: unknown axes are
+    listed, never counted as zero. Returns grade + per-axis rollup."""
+    axes = card.get("axes", {})
+    grades = {a: v.get("grade", "unknown") for a, v in axes.items()}
+    unknown = [a for a, g in grades.items() if g == "unknown"]
+    failing = [a for a, g in grades.items() if g in ("F", "D")]
+    if unknown:
+        verdict = "not-ready"     # unknown ≠ ready
+    elif failing:
+        verdict = "not-ready"
+    elif all(g == "A" for g in grades.values()):
+        verdict = "ready"
+    else:
+        verdict = "conditional"
+    return {"verdict": verdict, "axes": grades,
+            "unknown_axes": unknown, "failing_axes": failing,
+            "note": "unknown axes never count as passed"}

platformforge/ops/material.py

@@ -0,0 +1,181 @@
+"""Cycle 4.1 — RollbackMaterial (§5–8, §31, ADR-cycle4.1).
+
+A `rollback_action` name alone is not a rollback — the inverse usually
+needs parameters that only exist *before* or *during* the forward step.
+`RollbackMaterial` is the explicit, **immutable, hash-bound,
+content-addressed** record of everything captured to enable a correct
+reversal:
+
+    forward intent + pre-change state + execution result + strategy
+        = executable compensation
+
+Materials are written once into `.platformforge/materials/<hash>.json`;
+a rewrite attempt with different content is tamper evidence, not an
+update.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from platformforge.live.models import canonical_hash, now_iso
+
+MATERIAL_SCHEMA = "platformforge/rollback-material/v1"
+
+# provenance of a captured field — declared by the caller vs observed
+# by a transport/collector. Observed outranks declared on conflict.
+PROVENANCE = ("declared", "observed")
+
+
+@dataclass
+class RollbackMaterial:
+    material_id: str = ""
+    operation_id: str = ""
+    step_id: str = ""
+    action: str = ""
+    captured_at: str = ""
+    pre_state: dict[str, Any] = field(default_factory=dict)
+    execution_result: dict[str, Any] = field(default_factory=dict)
+    source_of_truth: dict[str, Any] = field(default_factory=dict)
+    artifacts: list[str] = field(default_factory=list)
+    references: list[str] = field(default_factory=list)
+    evidence: dict[str, Any] = field(default_factory=dict)
+    limitations: list[str] = field(default_factory=list)
+    provenance: str = "declared"
+
+    def payload(self) -> dict[str, Any]:
+        """Canonical content — everything the hash binds. Deep-copied:
+        a serialized material never aliases the live object's mutable
+        fields (mutating the dict must not corrupt the material)."""
+        import copy
+        return {"schema": MATERIAL_SCHEMA,
+                "material_id": self.material_id,
+                "operation_id": self.operation_id,
+                "step_id": self.step_id,
+                "action": self.action,
+                "captured_at": self.captured_at,
+                "pre_state": copy.deepcopy(self.pre_state),
+                "execution_result": copy.deepcopy(
+                    self.execution_result),
+                "source_of_truth": copy.deepcopy(self.source_of_truth),
+                "artifacts": list(self.artifacts),
+                "references": list(self.references),
+                "evidence": copy.deepcopy(self.evidence),
+                "limitations": list(self.limitations),
+                "provenance": self.provenance}
+
+    def hash(self) -> str:
+        return "sha256:" + canonical_hash(self.payload())
+
+    def to_dict(self) -> dict[str, Any]:
+        return {**self.payload(), "hash": self.hash()}
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> RollbackMaterial:
+        m = RollbackMaterial(
+            material_id=d.get("material_id", ""),
+            operation_id=d.get("operation_id", ""),
+            step_id=d.get("step_id", ""),
+            action=d.get("action", ""),
+            captured_at=d.get("captured_at", ""),
+            pre_state=dict(d.get("pre_state", {})),
+            execution_result=dict(d.get("execution_result", {})),
+            source_of_truth=dict(d.get("source_of_truth", {})),
+            artifacts=list(d.get("artifacts", [])),
+            references=list(d.get("references", [])),
+            evidence=dict(d.get("evidence", {})),
+            limitations=list(d.get("limitations", [])),
+            provenance=d.get("provenance", "declared"))
+        return m
+
+    def verify(self) -> dict[str, Any]:
+        """Tamper check — recompute the content hash."""
+        return {"material_id": self.material_id, "hash": self.hash(),
+                "ok": True}
+
+    def complete(self, required: tuple[str, ...]) -> list[str]:
+        """Which required pre-state keys are missing."""
+        return [k for k in required if k not in self.pre_state]
+
+
+class MaterialStore:
+    """Content-addressed, write-once store under
+    `.platformforge/materials/`. Same hash → same object; different
+    content at an existing path → tamper refusal."""
+
+    def __init__(self, root: str | Path = ".platformforge/materials"):
+        self.root = Path(root)
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def put(self, m: RollbackMaterial) -> dict[str, Any]:
+        h = m.hash()
+        p = self.root / f"{h.split(':', 1)[1]}.json"
+        if p.exists():
+            existing = json.loads(p.read_text())
+            if existing.get("hash") != h:
+                return {"ok": False,
+                        "refusal": "PF-OPS-MATERIAL-TAMPER",
+                        "unlock": "material content differs at existing "
+                                  "hash path — investigate tampering"}
+            return {"ok": True, "hash": h, "deduplicated": True}
+        p.write_text(json.dumps(m.to_dict(), indent=2, sort_keys=True))
+        return {"ok": True, "hash": h, "deduplicated": False}
+
+    def get(self, hash_or_id: str) -> RollbackMaterial | None:
+        h = hash_or_id.split(":", 1)[-1]
+        p = self.root / f"{h}.json"
+        if not p.exists():
+            for f in self.root.glob("*.json"):
+                d = json.loads(f.read_text())
+                if d.get("material_id") == hash_or_id:
+                    return RollbackMaterial.from_dict(d)
+            return None
+        return RollbackMaterial.from_dict(json.loads(p.read_text()))
+
+    def verify(self, hash_or_id: str) -> dict[str, Any]:
+        m = self.get(hash_or_id)
+        if m is None:
+            return {"ok": False, "refusal": "PF-OPS-MATERIAL-MISSING",
+                    "unlock": f"no material {hash_or_id}"}
+        p = self.root / f"{m.hash().split(':', 1)[1]}.json"
+        stored = json.loads(p.read_text()) if p.exists() else {}
+        return {"ok": stored.get("hash") == m.hash(),
+                "material_id": m.material_id, "hash": m.hash()}
+
+    def for_operation(self, operation_id: str) -> list[dict[str, Any]]:
+        out = []
+        for f in sorted(self.root.glob("*.json")):
+            d = json.loads(f.read_text())
+            if d.get("operation_id") == operation_id:
+                out.append({"hash": d.get("hash"),
+                            "step_id": d.get("step_id"),
+                            "action": d.get("action")})
+        return out
+
+
+def capture_material(action: str, step_id: str, operation_id: str,
+                     params: dict[str, Any],
+                     required: tuple[str, ...],
+                     pre_state: dict[str, Any] | None = None,
+                     execution_result: dict[str, Any] | None = None,
+                     source_of_truth: dict[str, Any] | None = None,
+                     provenance: str = "declared") -> RollbackMaterial:
+    """Build a material for one step — merges declared params with
+    transport/observation-captured pre-state (observed wins)."""
+    ps = dict(pre_state or {})
+    m = RollbackMaterial(
+        material_id=f"mat-{operation_id}-{step_id}",
+        operation_id=operation_id, step_id=step_id, action=action,
+        captured_at=now_iso(), pre_state=ps,
+        execution_result=dict(execution_result or {}),
+        source_of_truth=dict(source_of_truth or {}),
+        provenance=provenance)
+    missing = m.complete(required)
+    if missing:
+        m.limitations.append(
+            f"required pre-state not captured: {missing} — "
+            "rollback cannot be considered executable")
+    return m