platformforge 0.1.0__py3-none-any.whl

platformforge/ops/runbook.py

@@ -0,0 +1,269 @@
+"""Cycle 4 — structured runbook engine (phase O).
+
+Runbooks are data, not scripts: trigger, scope, diagnostics,
+preconditions, steps (typed actions only), risk, approval, verification,
+rollback, knowledge, sources. `bind()` compiles a runbook to a ChangePlan
++ diagnostics checklist; `audit()` refuses malformed runbooks.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from platformforge.live.models import canonical_hash
+from platformforge.ops.actions import spec_for
+from platformforge.ops.models import PlanStep
+
+RUNBOOK_SCHEMA = "platformforge/runbook/v1"
+
+# Cycle 4.1 §125–127 — safe parameter references. A runbook rollback
+# param may be declared as {"from": "pre_state.replicas"} — bound at
+# rollback-compile time against captured material, never eval()'d and
+# only under allowlisted roots.
+SAFE_REF_ROOTS = ("pre_state", "params", "result")
+
+
+def resolve_ref(ref: dict[str, Any], context: dict[str, Any]
+                ) -> dict[str, Any]:
+    """Resolve {"from": "root.a.b"} against context dicts. Data-only
+    path walking — no eval, no attribute access, allowlisted roots."""
+    path = str(ref.get("from", ""))
+    parts = path.split(".")
+    if len(parts) < 2 or parts[0] not in SAFE_REF_ROOTS:
+        return {"refusal": "PF-OPS-RUNBOOK-BAD-REF",
+                "unlock": f"'{path}' — refs must be "
+                          f"{SAFE_REF_ROOTS}.<field>[.<subfield>]"}
+    cur: Any = context.get(parts[0])
+    for p in parts[1:]:
+        if not isinstance(cur, dict) or p not in cur:
+            return {"refusal": "PF-OPS-RUNBOOK-REF-MISSING",
+                    "unlock": f"'{path}' not present in captured "
+                              f"state — bind cannot proceed"}
+        cur = cur[p]
+    return {"ok": True, "value": cur}
+
+
+def bind_params(declared: dict[str, Any], context: dict[str, Any]
+                ) -> dict[str, Any]:
+    """Bind a params dict — literal values pass through, {"from": …}
+    values resolve via resolve_ref."""
+    out: dict[str, Any] = {}
+    for k, v in declared.items():
+        if isinstance(v, dict) and "from" in v:
+            r = resolve_ref(v, context)
+            if "refusal" in r:
+                return r
+            out[k] = r["value"]
+        else:
+            out[k] = v
+    return {"ok": True, "params": out}
+
+
+@dataclass
+class RunbookStep:
+    step_id: str
+    action: str
+    params: dict[str, Any] = field(default_factory=dict)
+    depends_on: list[str] = field(default_factory=list)
+    kind: str = "execute"          # diagnose|execute|verify|rollback
+    on_failure: str = "abort"      # abort|continue|compensate
+
+
+@dataclass
+class Runbook:
+    runbook_id: str = ""
+    title: str = ""
+    trigger: dict[str, Any] = field(default_factory=dict)
+    scope: list[str] = field(default_factory=list)
+    diagnostics: list[dict[str, Any]] = field(default_factory=list)
+    preconditions: list[str] = field(default_factory=list)
+    steps: list[RunbookStep] = field(default_factory=list)
+    risk: dict[str, Any] = field(default_factory=dict)
+    approval_required: bool = True
+    verification: dict[str, Any] = field(default_factory=dict)
+    rollback: dict[str, Any] = field(default_factory=dict)
+    knowledge: list[dict[str, Any]] = field(default_factory=list)
+    sources: list[str] = field(default_factory=list)
+
+    def hash(self) -> str:
+        return "sha256:" + canonical_hash(self._payload())
+
+    def _payload(self) -> dict[str, Any]:
+        return {"schema": RUNBOOK_SCHEMA, "runbook_id": self.runbook_id,
+                "title": self.title, "trigger": self.trigger,
+                "scope": self.scope, "diagnostics": self.diagnostics,
+                "preconditions": self.preconditions,
+                "steps": [{"step_id": s.step_id, "action": s.action,
+                           "params": s.params, "kind": s.kind,
+                           "depends_on": s.depends_on,
+                           "on_failure": s.on_failure}
+                          for s in self.steps],
+                "risk": self.risk,
+                "approval_required": self.approval_required,
+                "verification": self.verification,
+                "rollback": self.rollback, "knowledge": self.knowledge,
+                "sources": self.sources}
+
+    def audit(self) -> list[dict[str, Any]]:
+        """Refusals for malformed runbooks — every step must be a
+        typed vocabulary action; diagnostics must name an evidence
+        source; rollback must not be fabricated."""
+        v = []
+        if not self.trigger:
+            v.append({"refusal": "PF-OPS-RUNBOOK-NO-TRIGGER",
+                      "unlock": "declare when this runbook applies"})
+        if not self.sources:
+            v.append({"refusal": "PF-OPS-RUNBOOK-NO-SOURCE",
+                      "unlock": "cite knowledge sources for each claim"})
+        seen: set[str] = set()
+        for s in self.steps:
+            if s.step_id in seen:
+                v.append({"refusal": "PF-OPS-RUNBOOK-DUP-STEP",
+                          "unlock": f"duplicate step_id {s.step_id}"})
+            seen.add(s.step_id)
+            if s.kind == "execute" and spec_for(s.action) is None:
+                v.append({"refusal": "PF-OPS-UNKNOWN-ACTION",
+                          "unlock": f"{s.action} not in action vocabulary"})
+            for d in s.depends_on:
+                if d not in seen and d not in {
+                        x.step_id for x in self.steps}:
+                    v.append({"refusal": "PF-OPS-RUNBOOK-BAD-DEP",
+                              "unlock": f"{s.step_id} depends on "
+                                        f"unknown {d}"})
+        for dg in self.diagnostics:
+            if not dg.get("source"):
+                v.append({"refusal": "PF-OPS-RUNBOOK-DIAG-NO-SOURCE",
+                          "unlock": "diagnostics must name an "
+                                    "evidence source"})
+        # §124–127 — declared rollback actions must be typed actions and
+        # `from:` refs must point at allowlisted roots; a hardcoded
+        # inverse that just mirrors forward params is a violation.
+        for rb in (self.rollback.get("actions") or []):
+            if spec_for(rb.get("action", "")) is None:
+                v.append({"refusal": "PF-OPS-UNKNOWN-ACTION",
+                          "unlock": f"rollback action "
+                                    f"{rb.get('action')} not in "
+                                    "vocabulary"})
+            for pk, pv in (rb.get("params") or {}).items():
+                if isinstance(pv, dict) and "from" in pv:
+                    root = str(pv["from"]).split(".")[0]
+                    if root not in SAFE_REF_ROOTS:
+                        v.append({"refusal": "PF-OPS-RUNBOOK-BAD-REF",
+                                  "unlock": f"rollback param {pk} "
+                                            f"refs disallowed root "
+                                            f"'{root}'"})
+        return v
+
+    def bind_rollback(self, materials: dict[str, Any],
+                      forward_params: dict[str, Any] | None = None
+                      ) -> dict[str, Any]:
+        """§123–127 — compile the declared `rollback.actions` into
+        typed actions whose params resolve against captured material.
+
+        `materials`: {step_id: RollbackMaterial|dict} — `pre_state`
+        values come from the first material (or the step the rollback
+        action names via `for_step`). Params referencing
+        `pre_state.*` never read forward params — captured state only.
+        """
+        out = []
+        mats = {sid: (m.to_dict() if hasattr(m, "to_dict") else dict(m))
+                for sid, m in (materials or {}).items()}
+        for rb in (self.rollback.get("actions") or []):
+            sid = rb.get("for_step") or next(iter(mats), "")
+            ctx = {"pre_state": (mats.get(sid) or {}).get(
+                       "pre_state", {}),
+                   "result": (mats.get(sid) or {}).get(
+                       "execution_result", {}),
+                   "params": forward_params or {}}
+            bound = bind_params(dict(rb.get("params") or {}), ctx)
+            if "refusal" in bound:
+                return {"ok": False,
+                        "refusal": bound,
+                        "action": rb.get("action")}
+            out.append({"action": rb["action"],
+                        "params": bound["params"],
+                        "for_step": sid or None})
+        return {"ok": True, "actions": out}
+
+    def bind(self, params: dict[str, Any] | None = None
+             ) -> dict[str, Any]:
+        """Compile to plan steps with bound params."""
+        violations = self.audit()
+        if violations:
+            return {"ok": False, "refusals": violations}
+        bound = []
+        for s in self.steps:
+            p = dict(params or {})
+            p.update(s.params)
+            if s.depends_on:
+                p["__depends_on__"] = s.depends_on
+            bound.append(PlanStep(step_id=s.step_id, action=s.action,
+                                  params=p))
+        return {"ok": True, "steps": bound,
+                "runbook_hash": self.hash()}
+
+    def to_dict(self) -> dict[str, Any]:
+        d = self._payload()
+        d["hash"] = self.hash()
+        return d
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> Runbook:
+        rb = Runbook()
+        for k in ("runbook_id", "title", "trigger", "scope",
+                  "diagnostics", "preconditions", "risk",
+                  "approval_required", "verification", "rollback",
+                  "knowledge", "sources"):
+            if k in d:
+                setattr(rb, k, d[k])
+        rb.steps = [RunbookStep(**s) for s in d.get("steps", [])]
+        return rb
+
+
+BUILTIN_RUNBOOKS: dict[str, Runbook] = {
+    "replica-drift-restore": Runbook(
+        runbook_id="replica-drift-restore",
+        title="Restore GitOps-managed replica drift via git",
+        trigger={"finding": "live-drift", "drift_kind": "config-drift",
+                 "attr_contains": "replicas"},
+        scope=["k8s:*:*:Deployment:*"],
+        diagnostics=[{"check": "argocd app diff for drift details",
+                      "source": "argocd-diff"},
+                     {"check": "git log for desired replica count",
+                      "source": "git-log"}],
+        preconditions=["fresh-observation", "gitops-managed",
+                       "no-active-freeze"],
+        steps=[RunbookStep("fix-git", "git.open_pr",
+                           params={"title": "fix: restore desired "
+                                            "replica count"}),
+               RunbookStep("argocd-sync", "argocd.sync",
+                           params={},
+                           depends_on=["fix-git"],
+                           kind="execute")],
+        risk={"class": "R3"},
+        approval_required=True,
+        verification={"windows": ["immediate", "stabilization"],
+                      "check": "observed replicas == desired"},
+        rollback={"strategy": "argo-rollback"},
+        sources=["gitops-first-remediation"]),
+    "scale-out-under-pressure": Runbook(
+        runbook_id="scale-out-under-pressure",
+        title="Scale deployment for load (non-prod auto-eligible)",
+        trigger={"slo": "burn_rate_elevated", "environment": "non-prod"},
+        scope=["k8s:*:*:Deployment:*"],
+        diagnostics=[{"check": "error/burn metrics",
+                      "source": "metrics"}],
+        preconditions=["fresh-observation"],
+        steps=[RunbookStep("scale", "kubernetes.scale", params={})],
+        risk={"class": "R2"},
+        approval_required=True,
+        verification={"windows": ["immediate", "stabilization"],
+                      "check": "burn_rate declines"},
+        rollback={"strategy": "direct-inverse",
+                  "actions": [{"action": "kubernetes.scale",
+                               "for_step": "scale",
+                               "params": {"replicas": {
+                                   "from": "pre_state.replicas"}}}]},
+        sources=["sre-scale-out"]),
+}

platformforge/ops/simulate.py

@@ -0,0 +1,125 @@
+"""Cycle 4 — simulation engine (§24–30).
+
+Simulation is first-class and *level-honest*: S0 static → S5 authorized
+cloud sandbox. A simulation receipt records level, inputs, environment,
+expected delta, unknowns and unsupported behaviors. "Simulation passed"
+never means "production safe" — limitations are part of the output.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from platformforge.live.models import now_iso
+from platformforge.ops.models import ChangePlan
+
+SIMULATION_LEVELS = ("S0", "S1", "S2", "S3", "S4", "S5")
+LEVEL_NAMES = {
+    "S0": "static",
+    "S1": "local-deterministic",
+    "S2": "sandbox/process",
+    "S3": "local-infra/kind/container",
+    "S4": "provider-dry-run/plan",
+    "S5": "authorized-cloud-sandbox"}
+
+# What each level can honestly claim.
+LEVEL_LIMITS = {
+    "S0": ["no runtime behavior", "no controller semantics",
+           "schema/shape only"],
+    "S1": ["deterministic projection — no provider calls"],
+    "S2": ["process isolation — no real provider"],
+    "S3": ["local cluster only — not production topology"],
+    "S4": [("dry-run/plan covers API validation, not controller "
+            "behavior or drift convergence")],
+    "S5": ["sandbox account — production data/scale not covered"]}
+
+
+@dataclass
+class SimulationReceipt:
+    level: str = "S0"
+    environment: str = "local"
+    inputs: dict[str, Any] = field(default_factory=dict)
+    expected_delta: dict[str, Any] = field(default_factory=dict)
+    outcome: str = "unknown"         # pass|fail|partial|unknown
+    findings: list[str] = field(default_factory=list)
+    unknowns: list[str] = field(default_factory=list)
+    unsupported: list[str] = field(default_factory=list)
+    limitations: list[str] = field(default_factory=list)
+    ran_at: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": "platformforge/simulation-receipt/v1",
+                "level": self.level,
+                "level_name": LEVEL_NAMES.get(self.level, "?"),
+                "environment": self.environment,
+                "outcome": self.outcome,
+                "expected_delta": self.expected_delta,
+                "findings": self.findings, "unknowns": self.unknowns,
+                "unsupported": self.unsupported,
+                "limitations": self.limitations, "ran_at": self.ran_at}
+
+
+def simulate(plan: ChangePlan, *, level: str = "S1",
+             observed_graph: dict[str, Any] | None = None,
+             planned_graph: dict[str, Any] | None = None,
+             executor_results: list[dict[str, Any]] | None = None
+             ) -> SimulationReceipt:
+    """Deterministic local simulation:
+    - validates the plan DAG (cycles/deps),
+    - computes graph delta when both graphs are given (S1),
+    - folds in executor dry-run results when provided (S4 class),
+    - always emits the level's limitations.
+    """
+    if level not in SIMULATION_LEVELS:
+        level = "S0"
+    r = SimulationReceipt(level=level, ran_at=now_iso(),
+                          expected_delta=plan.expected_delta.to_dict(),
+                          limitations=list(LEVEL_LIMITS.get(level, [])),
+                          inputs={"plan_hash": plan.hash(),
+                                  "steps": len(plan.steps)})
+
+    v = plan.validate()
+    for item in v:
+        r.findings.append(f"plan:{item['refusal']}")
+    if v:
+        r.outcome = "fail"
+        return r
+
+    # S1: graph delta from observed → planned projection
+    if observed_graph is not None and planned_graph is not None:
+        on = set((observed_graph.get("nodes") or {}).keys())
+        pn = set((planned_graph.get("nodes") or {}).keys())
+        oe = set((observed_graph.get("edges") or {}).keys())
+        pe = set((planned_graph.get("edges") or {}).keys())
+        r.expected_delta["adds"] = {
+            "resources": sorted(pn - on), "dependencies": sorted(pe - oe)}
+        r.expected_delta["removes"] = {
+            "resources": sorted(on - pn), "dependencies": sorted(oe - pe)}
+        r.unknowns.extend([d for d in ("security", "slo", "cost")
+                           if d not in
+                           (plan.expected_delta.to_dict() or {})])
+    else:
+        r.unknowns.append("graph-delta:not-computed "
+                          "(graphs not supplied)")
+
+    for er in executor_results or []:
+        if not er.get("ok", er.get("rc") == 0):
+            r.findings.append(
+                f"executor:{er.get('action', '?')} failed/dry-run rc≠0")
+        if er.get("unsupported"):
+            r.unsupported.extend(er["unsupported"])
+
+    if r.findings:
+        r.outcome = "fail"
+    elif r.unknowns or r.unsupported:
+        r.outcome = "partial"
+    else:
+        r.outcome = "pass"
+    return r
+
+
+def assertion() -> str:
+    """§30 — the sentence every simulation output implies."""
+    return ("simulation passed != production safe — receipt declares "
+            "level, limits and unknowns")

platformforge/ops/source_of_truth.py

@@ -0,0 +1,198 @@
+"""Cycle 4 — SourceOfTruthResolver (§12–17, ADR-0022).
+
+Before any remediation: *where should this resource actually be
+changed?* Resolution is evidence-driven, precedence by provenance —
+never blind. Unprovable ownership → `PF-OPS-SOURCE-UNKNOWN` + human
+review. Never guess.
+
+Signals come from facts/observations/graph nodes: an ArgoCD tracking
+annotation on a k8s object, a `terraform_resource` fact, a Crossplane
+managed resource, a Helm release secret. Each resolved answer carries
+the evidence that produced it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from platformforge.ops.models import SourceOfTruth
+
+# Signals we understand. Each maps evidence → SoT resolution.
+ARGOCD_TRACKING = "argocd.argoproj.io/tracking-id"
+ARGOCD_INSTANCE = "argocd.argoproj.io/instance"
+FLUXCD_LABELS = ("kustomize.toolkit.fluxcd.io/name",
+                 "helm.toolkit.fluxcd.io/name")
+HELM_LABELS = ("app.kubernetes.io/managed-by",)
+CROSSPLANE_CLAIM = "crossplane.io/claim-name"
+TF_ADDRESS_ATTRS = ("tf_address", "terraform_address", "module_address")
+
+
+@dataclass
+class Resolution:
+    resource_id: str = ""
+    source: SourceOfTruth = field(default_factory=SourceOfTruth)
+    preferred_path: str = ""        # git|terraform|gitops|direct — policy hint
+    unresolved: dict[str, Any] | None = None
+    conflicts: list[str] = field(default_factory=list)
+
+    @property
+    def resolved(self) -> bool:
+        return self.unresolved is None and self.source.resolved
+
+    @property
+    def status(self) -> str:
+        """Cycle 4.1 — resolved | conflicted | unresolved. A resource
+        claimed by two systems is NOT 'resolved with precedence' — it
+        is conflicted and defaults to human review (§F)."""
+        if self.unresolved is not None:
+            return "unresolved"
+        if self.conflicts:
+            return "conflicted"
+        if not self.source.resolved:
+            return "unresolved"
+        return "resolved"
+
+    @property
+    def requires_human_review(self) -> bool:
+        """Conflicts and provider-direct/manual ownership never gate
+        automated mutation by themselves (§F)."""
+        return self.status == "conflicted" or \
+            self.preferred_path == "direct-with-review" or \
+            self.source.type == "provider-api"
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"resource_id": self.resource_id,
+                             "resolved": self.resolved,
+                             "status": self.status,
+                             "requires_human_review":
+                                 self.requires_human_review,
+                             "source_of_truth": self.source.to_dict()}
+        if self.preferred_path:
+            d["preferred_path"] = self.preferred_path
+        if self.unresolved:
+            d["unresolved"] = self.unresolved
+        if self.conflicts:
+            d["conflicts"] = self.conflicts
+        return d
+
+
+def _sot(type_: str, *, repo="", path="", ref="", confidence="medium",
+         evidence=()) -> SourceOfTruth:
+    return SourceOfTruth(type=type_, repository=repo, path=path, ref=ref,
+                         confidence=confidence, evidence=list(evidence))
+
+
+def resolve_one(resource: dict[str, Any],
+                context: dict[str, Any] | None = None) -> Resolution:
+    """Resolve the canonical edit location for one resource.
+
+    `resource` fields used (any may be absent):
+      resource_id, kind, annotations/labels (k8s), managed_by,
+      argocd_app, argocd_repo/gitops_repo/gitops_path,
+      tf_address + tf_repo/tf_path, crossplane xr/claim/composition,
+      helm_release + chart_repo, provider, account, region.
+    `context` may carry registries: gitops_apps{}, tf_modules{},
+    helm_releases{}, crossplane_xrs{} keyed by name — each mapping to
+    {repository, path, ref}.
+    """
+    ctx = context or {}
+    rid = resource.get("resource_id") or resource.get("id") or ""
+    ann = dict(resource.get("annotations") or {})
+    labels = dict(resource.get("labels") or {})
+    found: list[SourceOfTruth] = []
+    conflicts: list[str] = []
+
+    # --- GitOps: ArgoCD app owns the object → edit the Git repo -------
+    app = resource.get("argocd_app") or ann.get(ARGOCD_INSTANCE, "").split("_")[0] \
+        or (ann.get(ARGOCD_TRACKING, "") and resource.get("app_name"))
+    if app:
+        reg = (ctx.get("gitops_apps") or {}).get(app, {})
+        repo = reg.get("repository") or resource.get("gitops_repo", "")
+        path = reg.get("path") or resource.get("gitops_path", "")
+        ref = reg.get("ref") or resource.get("gitops_ref", "HEAD")
+        found.append(_sot("gitops", repo=repo, path=path, ref=ref,
+                          confidence="high" if repo else "medium",
+                          evidence=[f"argocd-app:{app}"]))
+    elif any(k in labels for k in FLUXCD_LABELS):
+        name = next(labels[k] for k in FLUXCD_LABELS if k in labels)
+        reg = (ctx.get("flux_kustomizations") or {}).get(name, {})
+        found.append(_sot("gitops", repo=reg.get("repository", ""),
+                          path=reg.get("path", ""),
+                          ref=reg.get("ref", "HEAD"),
+                          confidence="high" if reg else "medium",
+                          evidence=[f"flux-kustomization:{name}"]))
+
+    # --- Terraform: resource tracked by state → edit the tf source ----
+    tf_addr = next((resource.get(k) for k in TF_ADDRESS_ATTRS
+                    if resource.get(k)), None)
+    if tf_addr:
+        mod = (ctx.get("tf_modules") or {}).get(tf_addr.split(".")[0], {})
+        found.append(_sot("terraform",
+                          repo=resource.get("tf_repo") or mod.get("repository", ""),
+                          path=resource.get("tf_path") or mod.get("path", ""),
+                          ref=resource.get("tf_ref") or mod.get("ref", "HEAD"),
+                          confidence="high",
+                          evidence=[f"tf-address:{tf_addr}"]))
+
+    # --- Crossplane MR → XR/Composition ------------------------------
+    if resource.get("crossplane_managed") or CROSSPLANE_CLAIM in ann:
+        claim = resource.get("claim") or ann.get(CROSSPLANE_CLAIM, "")
+        comp = resource.get("composition", "")
+        ev = [f"crossplane-claim:{claim}"] if claim else ["crossplane-managed"]
+        found.append(_sot("crossplane", path=comp or claim,
+                          confidence="medium", evidence=ev))
+
+    # --- Helm release → chart/values source ---------------------------
+    if labels.get("app.kubernetes.io/managed-by") == "Helm" or \
+            resource.get("helm_release"):
+        rel = resource.get("helm_release") or labels.get(
+            "app.kubernetes.io/instance", "")
+        reg = (ctx.get("helm_releases") or {}).get(rel, {})
+        found.append(_sot("helm", repo=reg.get("repository", ""),
+                          path=reg.get("path", "") or f"charts/{rel}",
+                          ref=reg.get("ref", "HEAD"), confidence="medium",
+                          evidence=[f"helm-release:{rel}"] if rel else
+                          ["helm-managed"]))
+
+    if not found:
+        # unmanaged → provider API is *possible* but never assumed safe
+        if resource.get("managed_by") in ("manual", "console", "provider"):
+            return Resolution(
+                resource_id=rid,
+                source=_sot("provider-api", confidence="low",
+                            evidence=[f"managed_by:{resource['managed_by']}"]),
+                preferred_path="direct-with-review")
+        return Resolution(
+            resource_id=rid,
+            unresolved={"refusal": "PF-OPS-SOURCE-UNKNOWN",
+                        "unlock": "provide ownership evidence (gitops app, "
+                                  "tf address, helm release, crossplane claim) "
+                                  "or mark managed_by explicitly"})
+
+    if len(found) > 1:
+        # §13 — precedence by evidence, not blind: gitops > terraform >
+        # crossplane > helm, but *conflicts are recorded*, never silent.
+        order = {"gitops": 0, "terraform": 1, "crossplane": 2, "helm": 3}
+        found.sort(key=lambda s: order.get(s.type, 9))
+        conflicts = [f"also-managed-by:{s.type}" for s in found[1:]]
+
+    best = found[0]
+    path = {"gitops": "gitops", "terraform": "terraform",
+            "crossplane": "crossplane-config", "helm": "helm-values"}.get(
+                best.type, "direct-with-review")
+    return Resolution(resource_id=rid, source=best, preferred_path=path,
+                      conflicts=conflicts)
+
+
+def resolve(resources: list[dict[str, Any]],
+            context: dict[str, Any] | None = None) -> list[Resolution]:
+    return [resolve_one(r, context) for r in resources]
+
+
+def unresolved_report(resolutions: list[Resolution]) -> dict[str, Any]:
+    """§17 — unknown ownership is a human-review outcome, not a guess."""
+    bad = [r for r in resolutions if r.unresolved]
+    return {"total": len(resolutions), "resolved": len(resolutions) - len(bad),
+            "unresolved": [r.to_dict() for r in bad],
+            "action": "human-review-required" if bad else "none"}