platformforge 0.1.0__py3-none-any.whl

platformforge/models/__init__.py

@@ -0,0 +1,21 @@
+"""Canonical models: Fact, Finding, Recommendation, Refusal, evidence tiers."""
+
+from platformforge.models.base import (
+    EvidenceTier,
+    Fact,
+    Finding,
+    FreshnessStatus,
+    Recommendation,
+    Refusal,
+    RefusalCode,
+)
+
+__all__ = [
+    "EvidenceTier",
+    "Fact",
+    "Finding",
+    "FreshnessStatus",
+    "Recommendation",
+    "Refusal",
+    "RefusalCode",
+]

platformforge/models/base.py

@@ -0,0 +1,214 @@
+"""Canonical contracts for the epistemic pipeline.
+
+Fact:      something directly observed (anchored, tiered, provenanced).
+Finding:   a judgment over facts — invalid without non-empty evidence.
+Refusal:   a named "we cannot tell" — never "probably".
+Recommendation: judgment + context, carries its epistemic basis.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import asdict, dataclass, field
+from enum import IntEnum
+from typing import Any
+
+
+class EvidenceTier(IntEnum):
+    """Authority ordering. T6/T7 never silently become facts."""
+
+    MEASURED_RUNTIME = 0
+    PROVIDER_OBSERVED = 1
+    GENERATED_PLAN = 2
+    REPO_CONFIG = 3
+    OFFICIAL_DOC = 4
+    OPERATOR_DECLARED = 5
+    LLM_INFERENCE = 6
+    CONJECTURE = 7
+
+    @property
+    def label(self) -> str:
+        return {
+            0: "measured-runtime",
+            1: "provider-observed",
+            2: "generated-plan",
+            3: "repo-config",
+            4: "official-doc",
+            5: "operator-declared",
+            6: "llm-inference",
+            7: "conjecture",
+        }[int(self)]
+
+
+class FreshnessStatus(str):
+    CURRENT = "current"
+    FRESH = "fresh"
+    STALE = "stale"
+    DEPRECATED = "deprecated"
+    SUPERSEDED = "superseded"
+    CONFLICTED = "conflicted"
+    UNRESOLVED = "unresolved"
+
+
+class RefusalCode:
+    """Named refusals — evidence gaps are data, never hedged prose."""
+
+    COST = "platform.cost.unresolved"
+    NETWORK = "platform.network.unresolved"
+    IDENTITY = "platform.identity.unresolved"
+    RUNTIME = "platform.runtime.unresolved"
+    VERSION = "platform.version.unresolved"
+    TOPOLOGY = "platform.topology.unresolved"
+    SLO = "platform.slo.unresolved"
+    OWNERSHIP = "platform.ownership.unresolved"
+    SECURITY = "platform.security.unresolved"
+    EVIDENCE = "platform.evidence.unresolved"
+
+    ALL = (
+        COST, NETWORK, IDENTITY, RUNTIME, VERSION, TOPOLOGY, SLO, OWNERSHIP, SECURITY, EVIDENCE
+    )
+
+
+FACT_ID_RE = re.compile(r"^PF-[A-Z0-9]+-[0-9]+$")
+FINDING_ID_RE = re.compile(r"^PF-F-[0-9]+$")
+RULE_ID_RE = re.compile(r"^PF-[A-Z0-9]+(-[A-Z0-9]+)*-[0-9]+$")
+
+
+def stable_id(prefix: str, *parts: str) -> str:
+    """Deterministic numeric id derived from content — stable across runs
+    given identical inputs, so findings can cite fact_ids durably."""
+    digest = hashlib.sha256("\x00".join(parts).encode()).hexdigest()
+    return f"{prefix}-{int(digest[:12], 16) % 10**12:012d}"
+
+
+@dataclass
+class Fact:
+    kind: str
+    source: str
+    location: str
+    tier: int = EvidenceTier.REPO_CONFIG
+    observed: bool = True
+    attrs: dict[str, Any] = field(default_factory=dict)
+    measures: dict[str, Any] = field(default_factory=dict)
+    provenance: dict[str, Any] = field(default_factory=dict)
+    freshness: dict[str, Any] = field(default_factory=dict)
+    fact_id: str = ""
+
+    def __post_init__(self) -> None:
+        if int(self.tier) >= EvidenceTier.LLM_INFERENCE:
+            raise ValueError(f"T6/T7 evidence cannot become a Fact (tier={self.tier})")
+        if not self.fact_id:
+            self.fact_id = stable_id(
+                "PF-" + self.domain_prefix,
+                self.kind, self.location,
+                json.dumps(self.attrs, sort_keys=True, default=str),
+            )
+        if not FACT_ID_RE.match(self.fact_id):
+            raise ValueError(f"invalid fact_id: {self.fact_id}")
+
+    @property
+    def domain_prefix(self) -> str:
+        """PF-<KIND AREA>-<n>: area derived from kind (`k8s.workload` -> K8S)."""
+        return self.kind.split(".")[0].upper().replace("_", "-") or "GEN"
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["tier"] = int(self.tier)
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Fact:
+        return cls(**d)
+
+
+@dataclass
+class Finding:
+    """A judgment over facts. Empty evidence is invalid by construction."""
+
+    rule_id: str
+    severity: str
+    status: str  # violated | passed | unresolved | not-applicable
+    evidence: list[str]
+    finding_id: str = ""
+    title: str = ""
+    message: str = ""
+    location: str = ""
+    attrs: dict[str, Any] = field(default_factory=dict)
+
+    SEVERITIES = ("info", "low", "medium", "high", "critical")
+    STATUSES = ("violated", "passed", "unresolved", "not-applicable")
+
+    def __post_init__(self) -> None:
+        if self.status == "violated" and not self.evidence:
+            raise ValueError(f"finding {self.rule_id}: violated requires non-empty evidence")
+        if self.severity not in self.SEVERITIES:
+            raise ValueError(f"invalid severity: {self.severity}")
+        if self.status not in self.STATUSES:
+            raise ValueError(f"invalid status: {self.status}")
+        if not RULE_ID_RE.match(self.rule_id):
+            raise ValueError(f"invalid rule_id: {self.rule_id}")
+        if not self.finding_id:
+            self.finding_id = stable_id(
+                "PF-F", self.rule_id, ",".join(sorted(self.evidence)), self.message
+            )
+        if not FINDING_ID_RE.match(self.finding_id):
+            raise ValueError(f"invalid finding_id: {self.finding_id}")
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class Refusal:
+    code: str
+    field: str
+    unlock: str
+    message: str = ""
+    missing_evidence: list[str] = field(default_factory=list)
+    refusal_id: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.refusal_id:
+            self.refusal_id = stable_id("PF-R", self.code, self.field)
+        if not (self.code.endswith(".unresolved") or RULE_ID_RE.match(self.code)):
+            raise ValueError(f"invalid refusal code: {self.code}")
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class Recommendation:
+    """Judgment + context. Always exposes its epistemic basis."""
+
+    title: str
+    severity: str
+    confidence: str
+    evidence: list[str]
+    proposed_change: list[str]
+    risks: list[str]
+    validation: list[str]
+    rollback: list[str]
+    basis: dict[str, list[str]]  # observed | declared | inferred | unknown
+    root_cause: str | None = None
+    expected_effect: str | None = None
+    benchmark_ref: str | None = None
+    tradeoffs: list[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if not self.evidence:
+            raise ValueError("recommendation requires evidence — never invent it")
+        if self.expected_effect and any(
+            ch.isdigit() for ch in self.expected_effect
+        ) and not self.benchmark_ref:
+            raise ValueError(
+                "quantified expected_effect requires benchmark_ref — "
+                "an unmeasured gain claim is an invention"
+            )
+        for k in ("observed", "declared", "inferred", "unknown"):
+            self.basis.setdefault(k, [])
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)

platformforge/observe/__init__.py

@@ -0,0 +1,26 @@
+"""Observability & SRE: SLO/error budgets, OTel trace correlation,
+incident correlation, capacity. Offline, deterministic, no invented numbers."""
+
+from platformforge.observe.capacity import capacity
+from platformforge.observe.dr import dr_model
+from platformforge.observe.grafana import analyze_grafana
+from platformforge.observe.incident import correlate
+from platformforge.observe.otel import analyze_semconv, correlate_spans
+from platformforge.observe.postmortem import postmortem, timeline
+from platformforge.observe.prometheus import analyze_prometheus
+from platformforge.observe.slo import SloContract, error_budget, multi_window_burn
+
+__all__ = [
+           "SloContract",
+           "analyze_grafana",
+           "analyze_prometheus",
+           "analyze_semconv",
+           "capacity",
+           "correlate",
+           "correlate_spans",
+           "dr_model",
+           "error_budget",
+           "multi_window_burn",
+           "postmortem",
+           "timeline",
+]

platformforge/observe/capacity.py

@@ -0,0 +1,39 @@
+"""Capacity — utilization facts in, saturation classes out. No
+interpolation: a fact reports what was measured, a rule applies the
+threshold."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def classify(utilization: float | None) -> str:
+    if utilization is None:
+        return "unresolved"
+    if utilization >= 0.95:
+        return "saturated"
+    if utilization >= 0.85:
+        return "hot"
+    if utilization >= 0.60:
+        return "warm"
+    return "cool"
+
+
+def capacity(items: list[dict[str, Any]]) -> dict[str, Any]:
+    """items: [{resource, used, limit, unit?}] — limit=None → unresolved."""
+    out = []
+    for it in items:
+        used, limit = it.get("used"), it.get("limit")
+        util = None
+        if isinstance(used, (int, float)) and isinstance(limit, (int, float)) \
+                and limit > 0:
+            util = used / limit
+        out.append({"resource": it.get("resource"), "used": used,
+                    "limit": limit, "unit": it.get("unit"),
+                    "utilization": round(util, 4) if util is not None else None,
+                    "class": classify(util)})
+    hot = [o["resource"] for o in out if o["class"] in ("hot", "saturated")]
+    unresolved = [o["resource"] for o in out if o["class"] == "unresolved"]
+    return {"capacity": out, "hot": hot, "unresolved_resources": unresolved,
+            "counts": {"items": len(out), "hot": len(hot),
+                       "unresolved": len(unresolved)}}

platformforge/observe/dr.py

@@ -0,0 +1,67 @@
+"""§90 DR engine — backup/replication/restore/failover/RTO/RPO as an
+evidence model. The core rule is structural, not statistical:
+
+    backup exists  !=  restore works
+
+A resource with a declared backup but no restore *evidence* (a restore
+test, a replica that has been cut over, a verified snapshot) is
+`protection: unresolved` — never `protected`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+PROTECTED_KINDS = {"database", "bucket", "volume", "cluster", "workload"}
+
+
+def dr_model(facts: list[dict[str, Any]]) -> dict[str, Any]:
+    """Classify each protectable resource's DR posture from facts."""
+    resources: dict[str, dict[str, Any]] = {}
+    for f in facts:
+        a = f.get("attrs") or {}
+        kind = (a.get("resource_type") or
+                (f.get("kind", "").split(".")[-1]))
+        label = a.get("name") or f.get("location", "?")
+        if kind not in PROTECTED_KINDS and not any(
+                k in a for k in ("backup", "replication", "restore_tested",
+                                 "rto", "rpo", "failover")):
+            continue
+        r = resources.setdefault(label, {
+            "kind": kind, "fact_ids": [],
+            "backup_declared": False, "replication_declared": False,
+            "restore_evidence": False, "failover_evidence": False,
+            "rto": None, "rpo": None})
+        r["fact_ids"].append(f.get("fact_id", ""))
+        for k in a:
+            kl = k.lower()
+            if "backup" in kl or "snapshot" in kl:
+                r["backup_declared"] = True
+            if "replicat" in kl or "multi_az" in kl or "multiaz" in kl:
+                r["replication_declared"] = True
+            if kl in ("restore_tested", "last_restore_at",
+                      "restore_verified") and a[k]:
+                r["restore_evidence"] = True
+            if kl in ("failover_tested", "last_failover_at") and a[k]:
+                r["failover_evidence"] = True
+        r["rto"] = a.get("rto") or r["rto"]
+        r["rpo"] = a.get("rpo") or r["rpo"]
+
+    out = []
+    for label, r in sorted(resources.items()):
+        if r["restore_evidence"] or r["failover_evidence"]:
+            protection = "evidenced"
+        elif r["backup_declared"] or r["replication_declared"]:
+            protection = "unresolved"   # declared ≠ proven
+        else:
+            protection = "none"
+        out.append({"resource": label, **r,
+                    "protection": protection,
+                    "note": "backup exists != restore works" if
+                            protection == "unresolved" else None})
+    counts = {}
+    for r in out:
+        counts[r["protection"]] = counts.get(r["protection"], 0) + 1
+    return {"dr": out, "counts": counts,
+            "note": "protection=evidenced requires restore/failover "
+                    "evidence, not just declared backups"}

platformforge/observe/grafana.py

@@ -0,0 +1,76 @@
+"""§86 Grafana — dashboard JSON → facts + `dashboard observes service`.
+
+Dashboards are declared config (T3). Service refs come from panel
+expressions (`service="x"` / `service_name="x"` label matchers) and
+templated variables — never inferred from titles.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from platformforge.models.base import stable_id
+
+_SVC_RE = re.compile(r'\b(?:service|service_name|service\.name)\s*=\s*"([^"]+)"')
+
+
+def _walk_panels(doc: dict[str, Any]) -> list[dict[str, Any]]:
+    panels: list[dict[str, Any]] = []
+    stack = list(doc.get("panels") or [])
+    while stack:
+        p = stack.pop()
+        if not isinstance(p, dict):
+            continue
+        if p.get("type") == "row":
+            stack += p.get("panels") or []
+            continue
+        panels.append(p)
+        stack += p.get("panels") or []
+    return panels
+
+
+def analyze_grafana(path: str | Path) -> dict[str, Any]:
+    root = Path(path)
+    files = sorted(root.rglob("*.json")) if root.is_dir() else [root]
+    facts: list[dict[str, Any]] = []
+    for f in files:
+        try:
+            doc = json.loads(f.read_text())
+        except (OSError, json.JSONDecodeError):
+            continue
+        if not isinstance(doc, dict) or "panels" not in doc \
+                and "dashboard" not in doc:
+            continue
+        dash = doc.get("dashboard", doc)
+        title = dash.get("title", f.stem)
+        panels = _walk_panels(dash)
+        datasources = sorted({(p.get("datasource") or {}).get("uid") or
+                              (p.get("datasource") or {}).get("type") or "?"
+                              for p in panels})
+        services: set[str] = set()
+        alerts = 0
+        for p in panels:
+            for t in p.get("targets") or []:
+                expr = str(t.get("expr") or t.get("rawSql") or "")
+                services |= set(_SVC_RE.findall(expr))
+            if p.get("alert") or p.get("type") == "alert":
+                alerts += 1
+        loc = f"{f}::{title}"
+        facts.append({
+            "fact_id": stable_id("PF-GRAFANA", "dashboard", loc),
+            "kind": "grafana.dashboard", "source": str(f),
+            "location": loc, "tier": 3,
+            "attrs": {"title": title, "uid": dash.get("uid"),
+                      "panels": len(panels), "alerts": alerts,
+                      "datasources": datasources,
+                      "services": sorted(services),
+                      "graph": {
+                          "nodes": [{"kind": "dashboard", "label": title}],
+                          "edges": [{"src_kind": "service", "src": s,
+                                     "dst_kind": "dashboard", "dst": title,
+                                     "kind": "observed_by"}
+                                    for s in sorted(services)]}}})
+    return {"facts": facts, "counts": {"facts": len(facts)}}

platformforge/observe/incident.py

@@ -0,0 +1,58 @@
+"""Incident correlation — alerts × changes × graph proximity → ranked
+hypotheses. Emits hypotheses WITH evidence ids; never asserts causality."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.graph.model import Graph
+from platformforge.graph.query import blast_radius
+
+
+def correlate(alerts: list[dict[str, Any]],
+              changes: list[dict[str, Any]],
+              graph: Graph | None = None,
+              window_s: int = 3600) -> dict[str, Any]:
+    """For each alert, rank candidate changes by (a) temporal proximity to
+    first alert and (b) graph proximity to the alerted node."""
+    hyps: list[dict[str, Any]] = []
+    for al in alerts:
+        svc = al.get("service") or al.get("node") or al.get("target")
+        at = float(al.get("at") or 0)
+        cands = []
+        for ch in changes:
+            tgt = ch.get("target") or ch.get("service")
+            dt = at - float(ch.get("at") or 0)
+            if dt < -window_s or dt > window_s:
+                continue  # change far from alert — out of window
+            proximity = "unknown"
+            if graph is not None and svc and tgt:
+                br = blast_radius(graph, tgt)
+                if svc == tgt:
+                    proximity = "self"
+                elif svc in br["nodes"]:
+                    proximity = f"graph-depth-{br['nodes'][svc]['depth']}"
+            score = (2 if proximity == "self" else
+                     1 if proximity.startswith("graph-depth") else 0) \
+                + (1 if 0 <= dt <= window_s else 0)  # change before alert
+            # §8 — causality vocabulary: proximity is never causality.
+            # confirmed requires external confirmation, never assigned here.
+            if dt < 0:
+                causality = "contradicted"  # change after the alert started
+            elif proximity == "self":
+                causality = "strongly-supported"
+            elif proximity.startswith("graph-depth"):
+                causality = "candidate"
+            elif proximity == "unknown":
+                causality = "correlated" if 0 <= dt <= window_s else "unknown"
+            else:
+                causality = "unknown"
+            cands.append({"change": ch, "dt_seconds": dt,
+                          "proximity": proximity, "score": score,
+                          "causality": causality})
+        cands.sort(key=lambda c: (-c["score"], abs(c["dt_seconds"])))
+        hyps.append({"alert": al, "hypotheses": cands,
+                     "note": "correlation is not causation — hypothesis "
+                             "list, not diagnosis"})
+    return {"incident_hypotheses": hyps,
+            "counts": {"alerts": len(alerts), "changes": len(changes)}}

platformforge/observe/otel.py

@@ -0,0 +1,135 @@
+"""OTel span correlation — JSONL span dumps → per-trace service view.
+
+Input: JSONL of {trace_id, span_id, parent_span_id, service, name,
+start_unix_ms, duration_ms, status}. Output is purely structural: services
+per trace, error propagation, critical path. No sampling assumptions.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+from platformforge.models.base import stable_id
+
+
+def correlate_spans(path: str | Path) -> dict[str, Any]:
+    spans: list[dict[str, Any]] = []
+    skipped = 0
+    for line in Path(path).read_text().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            s = json.loads(line)
+            if "trace_id" in s and "span_id" in s:
+                spans.append(s)
+            else:
+                skipped += 1
+        except json.JSONDecodeError:
+            skipped += 1
+    traces: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    for s in spans:
+        traces[s["trace_id"]].append(s)
+    out_traces = []
+    svc_errors: dict[str, int] = defaultdict(int)
+    svc_calls: dict[str, int] = defaultdict(int)
+    for tid, spans_ in traces.items():
+        by_id = {s["span_id"]: s for s in spans_}
+        services = sorted({s.get("service", "?") for s in spans_})
+        errors = [s for s in spans_
+                  if str(s.get("status", "")).lower() in ("error", "2")]
+        for s in errors:
+            svc_errors[s.get("service", "?")] += 1
+        for s in spans_:
+            svc_calls[s.get("service", "?")] += 1
+        # critical path = chain with max summed duration (tree walk)
+        children: dict[str | None, list[str]] = defaultdict(list)
+        for s in spans_:
+            children[s.get("parent_span_id")].append(s["span_id"])
+        best: dict[str, Any] = {"dur": 0.0, "path": []}
+
+        def walk(sid: str, dur: float, path: list[str],
+                 by_id=by_id, best=best, children=children):
+            node = by_id[sid]
+            dur += float(node.get("duration_ms") or 0)
+            path = path + [f"{node.get('service', '?')}:{node.get('name', '?')}"]
+            if dur > best["dur"]:
+                best["dur"], best["path"] = dur, path
+            for c in children.get(sid, []):
+                walk(c, dur, path, by_id, best, children)
+
+        roots = [s["span_id"] for s in spans_
+                 if s.get("parent_span_id") not in by_id]
+        for r in roots:
+            walk(r, 0.0, [])
+        out_traces.append({
+            "trace_id": tid, "spans": len(spans_), "services": services,
+            "error_spans": len(errors),
+            "error_services": sorted({s.get("service", "?")
+                                      for s in errors}),
+            "critical_path_ms": best["dur"],
+            "critical_path": best["path"],
+        })
+    return {
+        "traces": sorted(out_traces, key=lambda t: t["trace_id"]),
+        "counts": {"spans": len(spans), "traces": len(traces),
+                   "skipped_lines": skipped},
+        "service_summary": {
+            svc: {"spans": svc_calls[svc], "error_spans": svc_errors.get(svc, 0)}
+            for svc in sorted(svc_calls)},
+    }
+
+
+# §83 — OTel semantic conventions used for Graphfy correlation.
+SEMCONV = ("service.name", "service.namespace", "service.instance.id",
+           "cloud.provider", "cloud.account.id", "cloud.region",
+           "k8s.cluster.name", "k8s.namespace.name", "k8s.deployment.name",
+           "k8s.pod.name")
+
+
+def analyze_semconv(path: str | Path) -> dict[str, Any]:
+    """Extract §83 resource attributes from spans → facts + graph edges.
+
+    service.name → service node; k8s.deployment.name → workload node,
+    linked `runs_on`. Every edge carries the span's fact provenance.
+    """
+    spans: list[dict[str, Any]] = []
+    for line in Path(path).read_text().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            spans.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    facts: list[dict[str, Any]] = []
+    seen_edges: set[tuple[str, str]] = set()
+    for s in spans:
+        res = s.get("resource") or s.get("resource_attributes") or {}
+        attrs = {k: res.get(k) or s.get(k) for k in SEMCONV}
+        svc = attrs.get("service.name") or s.get("service")
+        if not svc:
+            continue
+        deploy = attrs.get("k8s.deployment.name")
+        pod = attrs.get("k8s.pod.name")
+        edges, nodes = [], [{"kind": "service", "label": svc}]
+        if deploy:
+            nodes.append({"kind": "workload", "label": deploy})
+            if (svc, deploy) not in seen_edges:
+                seen_edges.add((svc, deploy))
+                edges.append({"src_kind": "workload", "src": deploy,
+                              "dst_kind": "service", "dst": svc,
+                              "kind": "runs_on"})
+        facts.append({
+            "fact_id": stable_id("PF-OTEL", "semconv",
+                                 s.get("span_id", svc)),
+            "kind": "otel.resource", "source": str(path),
+            "location": svc, "tier": 1,
+            "attrs": {"semconv": {k: v for k, v in attrs.items() if v},
+                      "service": svc, "pod": pod,
+                      "graph": {"nodes": nodes, "edges": edges}}})
+    return {"facts": facts, "counts": {"spans": len(spans),
+                                       "resources": len(facts)}}