platformforge 0.1.0__py3-none-any.whl

platformforge/ops/policy.py

@@ -0,0 +1,275 @@
+"""Cycle 4 — operation policy engine V2 (§40–52, ADR-0030).
+
+Governs *actions*, not just resources. The canonical contract is
+`PolicyDecision`; external engines (OPA/Kyverno/CEL) are adapters that
+feed it — never truth themselves.
+
+Precedence rules (explicit, no coin flips):
+- policies carry {owner, authority, priority, scope}; evaluation runs in
+  declared priority order;
+- equal-priority allow vs deny → **deny dominates**;
+- `require-*` decisions dominate plain `allow`;
+- unresolved input → `unresolved` decision which fails closed for
+  mutations (never silently denied, never silently allowed).
+
+Shadow policies evaluate identically but emit `would_*` verdicts — they
+can never enforce (§50–52, 275).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from platformforge.live.models import canonical_hash, now_iso, parse_ts
+
+DECISION_SCHEMA = "platformforge/policy-decision/v1"
+EXCEPTION_SCHEMA = "platformforge/policy-exception/v1"
+
+DECISIONS = ("allow", "deny", "require-approval",
+             "require-additional-evidence", "require-simulation",
+             "require-security-review", "require-owner-review",
+             "defer", "unresolved")
+ENFORCING = {"deny", "require-approval", "require-additional-evidence",
+             "require-simulation", "require-security-review",
+             "require-owner-review", "defer", "unresolved"}
+
+# Rank for combining equal-priority decisions: higher wins.
+_DECISION_RANK = {"deny": 90, "require-security-review": 80,
+                  "require-owner-review": 75, "require-approval": 70,
+                  "require-simulation": 65,
+                  "require-additional-evidence": 60, "defer": 50,
+                  "unresolved": 40, "allow": 10}
+
+
+@dataclass
+class PolicyException:
+    """§47–49 — scoped, owned, expiring bypass. Never permanent."""
+    exception_id: str = ""
+    policy_id: str = ""
+    scope: str = ""
+    resource: str = ""
+    reason: str = ""
+    owner: str = ""
+    approved_by: str = ""
+    created_at: str = ""
+    expires_at: str = ""
+    compensating_controls: list[str] = field(default_factory=list)
+
+    def is_active(self, at: str | None = None) -> bool:
+        exp = parse_ts(self.expires_at)
+        if exp is None:
+            return False   # §48 — exceptions without expiry are inert
+        ref = parse_ts(at) if at else parse_ts(now_iso())
+        return bool(ref and ref <= exp)
+
+    def applies_to(self, policy_id: str, scope: str,
+                   resource: str) -> bool:
+        if self.policy_id and self.policy_id != policy_id:
+            return False
+        if self.scope and self.scope != scope:
+            return False
+        return not (self.resource and self.resource != resource)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": EXCEPTION_SCHEMA,
+                "exception_id": self.exception_id,
+                "policy_id": self.policy_id, "scope": self.scope,
+                "resource": self.resource, "reason": self.reason,
+                "owner": self.owner, "approved_by": self.approved_by,
+                "created_at": self.created_at or now_iso(),
+                "expires_at": self.expires_at,
+                "compensating_controls": self.compensating_controls}
+
+
+@dataclass
+class PolicyDecision:
+    """§42–44 — canonical decision + receipt fields."""
+    decision: str = "unresolved"     # allow|deny|require-*|defer|unresolved
+    policy_id: str = ""
+    policy_version: str = ""
+    combining: str = "deny-overrides"
+    reason: str = ""
+    input_hash: str = ""
+    evidence: list[str] = field(default_factory=list)
+    timestamp: str = ""
+    shadow: bool = False             # §50 — would_* semantics
+    exception_id: str = ""
+    evaluated: list[str] = field(default_factory=list)
+
+    @property
+    def effective(self) -> str:
+        """The decision as enforced — shadow policies only *record*."""
+        if self.shadow:
+            return f"would_{self.decision}"
+        return self.decision
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": DECISION_SCHEMA,
+                "policy_id": self.policy_id,
+                "policy_version": self.policy_version,
+                "combining": self.combining,
+                "input_hash": self.input_hash,
+                "decision": self.decision,
+                "effective": self.effective,
+                "shadow": self.shadow,
+                "reason": self.reason, "evidence": self.evidence,
+                "evaluated": self.evaluated,
+                "exception_id": self.exception_id,
+                "timestamp": self.timestamp or now_iso()}
+
+
+@dataclass
+class Policy:
+    """Native rule form. `when` = predicates over the policy input;
+    `then` = decision + reason."""
+    policy_id: str = ""
+    version: str = "1"
+    owner: str = ""
+    authority: str = ""
+    priority: int = 100
+    scope: str = "*"
+    shadow: bool = False
+    when: dict[str, Any] = field(default_factory=dict)
+    then: dict[str, Any] = field(default_factory=dict)
+    description: str = ""
+
+    def matches(self, inp: dict[str, Any]) -> bool:
+        for k, want in self.when.items():
+            got = inp.get(k)
+            if isinstance(want, list):
+                if got not in want:
+                    return False
+            elif isinstance(want, dict):
+                # comparators: {"$in": [...]}, {"$gte": n}, {"$ne": v}
+                if "$in" in want and got not in want["$in"]:
+                    return False
+                if "$gte" in want and not (got is not None
+                                           and got >= want["$gte"]):
+                    return False
+                if "$lte" in want and not (got is not None
+                                           and got <= want["$lte"]):
+                    return False
+                if "$ne" in want and got == want["$ne"]:
+                    return False
+            elif got != want:
+                return False
+        return True
+
+
+def _scope_match(policy_scope: str, inp_scope: str) -> bool:
+    return policy_scope in ("*", "", inp_scope) or \
+        inp_scope.startswith(policy_scope.rstrip("*"))
+
+
+def evaluate(inp: dict[str, Any], policies: list[Policy],
+             exceptions: list[PolicyException] | None = None,
+             at: str | None = None) -> PolicyDecision:
+    """Deterministic evaluation: scope → priority → deny-overrides."""
+    inp_hash = "sha256:" + canonical_hash(inp)
+    scope = inp.get("scope") or inp.get("environment") or "*"
+    applicable = [p for p in sorted(policies, key=lambda p: p.priority)
+                  if _scope_match(p.scope, scope) and p.matches(inp)]
+
+    hits: list[tuple[Policy, str]] = []
+    for p in applicable:
+        dec = p.then.get("decision", "unresolved")
+        if dec not in DECISIONS:
+            dec = "unresolved"
+        hits.append((p, dec))
+
+    exceptions = exceptions or []
+    active_ex: list[PolicyException] = []
+
+    if not hits:
+        # §33 analog — no applicable policy means "unresolved", not allow
+        return PolicyDecision(decision="unresolved", input_hash=inp_hash,
+                              reason="no applicable policy",
+                              evidence=[], timestamp=at or now_iso())
+
+    for pol, dec in hits:
+        for ex in exceptions:
+            if ex.is_active(at) and ex.applies_to(
+                    pol.policy_id, scope,
+                    inp.get("resource", "") or ""):
+                active_ex.append(ex)
+
+    enforcing = [(p, d) for p, d in hits if d != "allow"]
+    shadow_only = all(p.shadow for p, _ in hits)
+    if enforcing:
+        # deny dominates; among equal-priority, strongest require-* wins
+        top_pri = min(p.priority for p, d in enforcing)
+        top = [(p, d) for p, d in enforcing if p.priority == top_pri]
+        top.sort(key=lambda pd: -_DECISION_RANK.get(pd[1], 0))
+        pol, dec = top[0]
+    else:
+        pol, dec = hits[0][0], "allow"
+
+    if active_ex and dec in ENFORCING:
+        return PolicyDecision(
+            decision="allow", policy_id=pol.policy_id,
+            policy_version=pol.version, reason=(
+                f"exception:{active_ex[0].exception_id} "
+                f"overrides {pol.policy_id} until {active_ex[0].expires_at}"),
+            input_hash=inp_hash,
+            evidence=[f"policy:{p.policy_id}@{p.version}"
+                      for p, _ in hits],
+            timestamp=at or now_iso(), shadow=pol.shadow or shadow_only,
+            exception_id=active_ex[0].exception_id,
+            evaluated=[p.policy_id for p, _ in hits])
+
+    conflict = dec == "allow" and any(d == "deny" for _, d in hits)
+    if conflict:
+        dec, reason_extra = "deny", " [conflict→deny-overrides]"
+    else:
+        reason_extra = ""
+
+    return PolicyDecision(
+        decision=dec, policy_id=pol.policy_id, policy_version=pol.version,
+        reason=(pol.then.get("reason") or pol.description or dec)
+               + reason_extra,
+        input_hash=inp_hash,
+        evidence=[f"policy:{p.policy_id}@{p.version}" for p, _ in hits],
+        timestamp=at or now_iso(), shadow=pol.shadow or shadow_only,
+        evaluated=[p.policy_id for p, _ in hits])
+
+
+def simulate_policy(policy: Policy, history: list[dict[str, Any]],
+                    exceptions: list[PolicyException] | None = None
+                    ) -> dict[str, Any]:
+    """§52 — what would this policy have blocked/require on history."""
+    counts: dict[str, int] = {}
+    records: list[dict[str, Any]] = []
+    for i, inp in enumerate(history):
+        d = evaluate(inp, [policy], exceptions=exceptions)
+        d.shadow = True                    # simulation is never enforcement
+        key = d.effective
+        counts[key] = counts.get(key, 0) + 1
+        records.append({"i": i, "decision": key, "reason": d.reason})
+    return {"policy_id": policy.policy_id, "shadow": True,
+            "evaluated": len(history), "counts": counts,
+            "records": records}
+
+
+def adapter_eval(engine: str, input_: dict[str, Any],
+                 runner: Callable[[dict[str, Any]], dict[str, Any]]
+                 ) -> PolicyDecision:
+    """§45–46 — external engines are adapters emitting canonical shape.
+    `runner` is a host-side callable (opa eval, kyverno apply) returning
+    {decision, reason, policy_id, version, evidence}; undefined/errored
+    engine output must map to `unresolved`, never to allow."""
+    try:
+        out = runner(input_)
+    except Exception as exc:  # noqa: BLE001 — adapter failure → unresolved (fail closed)
+        return PolicyDecision(decision="unresolved",
+                              reason=f"{engine}-adapter-error:{exc}",
+                              input_hash="sha256:" + canonical_hash(input_))
+    dec = out.get("decision", "unresolved")
+    if dec not in DECISIONS:
+        dec = "unresolved"
+    return PolicyDecision(decision=dec, policy_id=out.get("policy_id", engine),
+                          policy_version=out.get("version", ""),
+                          reason=out.get("reason", ""),
+                          input_hash="sha256:" + canonical_hash(input_),
+                          evidence=list(out.get("evidence", [])))

platformforge/ops/preconditions.py

@@ -0,0 +1,109 @@
+"""Cycle 4 — precondition engine (§87–88).
+
+Every check runs *immediately before* execution: fresh observation,
+sufficient coverage, resource still present, hashes unchanged, plan
+still valid, owner unchanged, policy still allows, approval still valid,
+maintenance window open. Any failure → `PF-OPS-PRECONDITION-FAILED`
+with the specific check named — never a blind attempt.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from platformforge.live.models import age_seconds, now_iso, parse_ts
+
+
+@dataclass
+class Precondition:
+    name: str = ""
+    ok: bool = True
+    detail: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"name": self.name, "ok": self.ok, "detail": self.detail}
+
+
+def check_preconditions(*,
+                        observation: dict[str, Any] | None = None,
+                        max_observation_age_s: int = 900,
+                        expected_resource_state: dict[str, Any] | None = None,
+                        current_resource_state: dict[str, Any] | None = None,
+                        plan_hash: str = "", current_plan_hash: str = "",
+                        owner: str = "", current_owner: str = "",
+                        policy_decision: str = "",
+                        approval_valid: bool | None = None,
+                        maintenance_window: dict[str, Any] | None = None,
+                        freeze_active: bool = False,
+                        break_glass: bool = False,
+                        at: str | None = None) -> dict[str, Any]:
+    """Returns {ok, checks[], refusal?}. Each check is named — a failed
+    precondition is an explicit state, never silent."""
+    checks: list[Precondition] = []
+
+    if observation is not None:
+        age = age_seconds(observation.get("captured_at") or
+                          observation.get("collected_at"),
+                          parse_ts(at))
+        fresh = age is not None and age <= max_observation_age_s
+        checks.append(Precondition(
+            "observation-fresh", fresh,
+            f"age={age:.0f}s limit={max_observation_age_s}s"
+            if age is not None else "no timestamp"))
+        cov = (observation.get("coverage") or {})
+        complete = cov.get("complete", cov.get("status") == "complete")
+        checks.append(Precondition("coverage-sufficient", bool(complete),
+                                   cov.get("status", "unknown")))
+    else:
+        checks.append(Precondition("observation-fresh", False,
+                                   "no observation supplied"))
+
+    if expected_resource_state is not None:
+        same = current_resource_state is not None and \
+            expected_resource_state == current_resource_state
+        checks.append(Precondition(
+            "resource-hash-unchanged", same,
+            "resource drifted since plan" if not same else "unchanged"))
+
+    if plan_hash:
+        same = plan_hash == current_plan_hash
+        checks.append(Precondition("plan-still-valid", same,
+                                   "plan hash changed" if not same
+                                   else plan_hash[:24]))
+    if owner:
+        same = owner == current_owner
+        checks.append(Precondition("owner-unchanged", same,
+                                   f"owner {owner}→{current_owner}"))
+
+    if policy_decision:
+        checks.append(Precondition("policy-still-allows",
+                                   policy_decision == "allow",
+                                   policy_decision))
+    if approval_valid is not None:
+        checks.append(Precondition("approval-still-valid",
+                                   bool(approval_valid)))
+
+    if maintenance_window:
+        t = parse_ts(at) if at else parse_ts(now_iso())
+        ws, we = (parse_ts(maintenance_window.get("start") or ""),
+                  parse_ts(maintenance_window.get("end") or ""))
+        open_ = bool(ws and we and t and ws <= t <= we)
+        checks.append(Precondition("maintenance-window-open", open_,
+                                   f"{maintenance_window.get('start','?')}"
+                                   f"→{maintenance_window.get('end','?')}"))
+
+    if freeze_active and not break_glass:
+        checks.append(Precondition("change-freeze", False,
+                                   "freeze period active (break-glass can "
+                                   "override only explicitly)"))
+
+    failed = [c for c in checks if not c.ok]
+    out: dict[str, Any] = {"ok": not failed,
+                           "checks": [c.to_dict() for c in checks]}
+    if failed:
+        out["refusal"] = {"refusal": "PF-OPS-PRECONDITION-FAILED",
+                          "unlock": "fix failed preconditions then re-plan: "
+                                    f"{[c.name for c in failed]}",
+                          "failed": [c.name for c in failed]}
+    return out

platformforge/ops/registry.py

@@ -0,0 +1,101 @@
+"""Cycle 4 phase S — operations capability registry + cross-Forge
+delegation contract.
+
+Sibling forges may *request* operations; Platform Forge never
+auto-approves cross-forge requests — they mint a ChangeIntent and enter
+the normal governed pipeline. Each executor capability declares
+max_autonomy, approval requirement, mutation, risk ceiling and runtime
+availability so the registry can negotiate honestly.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.ops.actions import catalog
+
+# executor → advertised capability block
+EXECUTOR_CAPS: dict[str, dict[str, Any]] = {
+    "git": {"max_autonomy": "A4", "mutates": True,
+            "approval": "required-for-merge",
+            "risk_ceiling": "R3", "runtime_available": False},
+    "terraform": {"max_autonomy": "A4", "mutates": True,
+                  "approval": "required",
+                  "risk_ceiling": "R5", "runtime_available": False},
+    "tofu": {"max_autonomy": "A4", "mutates": True,
+             "approval": "required",
+             "risk_ceiling": "R5", "runtime_available": False},
+    "argocd": {"max_autonomy": "A4", "mutates": True,
+               "approval": "required",
+               "risk_ceiling": "R4", "runtime_available": False},
+    "kubernetes": {"max_autonomy": "A5-lab-only", "mutates": True,
+                   "approval": "required-for-R3+",
+                   "risk_ceiling": "R4", "runtime_available": False},
+    "observe": {"max_autonomy": "A1", "mutates": False,
+                "approval": "none",
+                "risk_ceiling": "R0", "runtime_available": True},
+}
+
+
+def ops_capabilities() -> dict[str, Any]:
+    """Machine-readable ops surface for the v3 manifest."""
+    per_action: dict[str, Any] = {}
+    for name, spec in catalog().items():
+        cap = EXECUTOR_CAPS.get(spec["executor"], {})
+        per_action[name] = {
+            "executor": spec["executor"],
+            "risk_class": spec["risk_base"],
+            "mutates": spec["mutating"],
+            "dry_run": spec["dry_run"],
+            "idempotent": spec["idempotent"],
+            "rollback_action": spec["rollback_action"],
+            "max_autonomy": cap.get("max_autonomy", "A4"),
+            "approval": cap.get("approval", "required"),
+            "runtime_available": cap.get("runtime_available", False)}
+    return {"schema": "platformforge/ops-capabilities/v3",
+            "platform_max_autonomy": "A4",
+            "a5_scope": "lab/non-prod narrow reversible only",
+            "a6": "non-goal",
+            "executors": EXECUTOR_CAPS,
+            "actions": per_action}
+
+
+def delegation_contract() -> dict[str, Any]:
+    """What a sibling forge may ask for — and what is refused."""
+    return {
+        "accepts": ["change-intent", "runbook-request",
+                    "observation-request", "policy-eval-request",
+                    "fleet-summary-request", "analytics-report-request",
+                    "optimization-list-request"],
+        "refuses": ["direct-execution", "approval-minting",
+                    "shell-command", "generic-provider-call",
+                    "full-fleet-dump", "credential-transfer"],
+        "contract": "cross-forge requests mint ChangeIntent + enter "
+                    "the governed pipeline; they never skip stages",
+        "refusal_code": "PF-OPS-CROSSFORGE-REFUSED"}
+
+
+def validate_delegate_request(req: dict[str, Any]
+                              ) -> dict[str, Any]:
+    """Validate an inbound cross-forge request. Returns refusal or a
+    normalized ChangeIntent payload."""
+    kind = req.get("kind")
+    if kind not in delegation_contract()["accepts"]:
+        return {"refusal": "PF-OPS-CROSSFORGE-REFUSED",
+                "unlock": f"kind must be one of "
+                          f"{delegation_contract()['accepts']}"}
+    if kind in ("direct-execution", "approval-minting",
+                "full-fleet-dump", "credential-transfer"):
+        return {"refusal": "PF-OPS-CROSSFORGE-REFUSED",
+                "unlock": "execution, approval, raw dumps and "
+                          "credentials are never delegatable"}
+    if not req.get("requested_by"):
+        return {"refusal": "PF-OPS-NO-ACTOR",
+                "unlock": "cross-forge requests need a principal"}
+    if kind in ("fleet-summary-request", "analytics-report-request",
+                "optimization-list-request"):
+        return {"ok": True, "route": "read-only-intelligence",
+                "requested_by": req["requested_by"],
+                "note": "bounded summary only — never a full dump"}
+    return {"ok": True, "route": "change-intent",
+            "requested_by": req["requested_by"]}