platformforge 0.1.0__py3-none-any.whl

platformforge/analytics/opsanalytics.py

@@ -0,0 +1,119 @@
+"""Cycle 5 — fleet operations analytics (§150–160).
+
+Operation history aggregates: hotspots, recurring remediation (never
+blind auto-remediation — §155), recurring incident patterns, unified
+fleet timeline.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.analytics.models import confidence_for_support
+
+
+def operation_metrics(ops: list[dict[str, Any]]) -> dict[str, Any]:
+    """§151 — fleet operation counters."""
+    out = {"operations": len(ops), "converged": 0, "rolled_back": 0,
+           "failed": 0, "blocked": 0, "manual": 0, "auto_eligible": 0,
+           "time_to_converge_s": []}
+    for o in ops:
+        st = str(o.get("state") or o.get("outcome") or "")
+        if st == "converged":
+            out["converged"] += 1
+        if st in ("rolled-back", "rollback-planned"):
+            out["rolled_back"] += 1
+        if st == "failed":
+            out["failed"] += 1
+        if st in ("refused", "blocked"):
+            out["blocked"] += 1
+        if o.get("manual"):
+            out["manual"] += 1
+        if o.get("auto_eligible"):
+            out["auto_eligible"] += 1
+        if o.get("converge_seconds") is not None:
+            out["time_to_converge_s"].append(o["converge_seconds"])
+    t = sorted(out.pop("time_to_converge_s"))
+    out["median_time_to_converge_s"] = t[len(t) // 2] if t else "unknown"
+    out["sample_size"] = len(ops)
+    out["confidence"] = confidence_for_support(len(ops))
+    return out
+
+
+def operation_hotspots(ops: list[dict[str, Any]],
+                       min_count: int = 3) -> list[dict[str, Any]]:
+    """§152 — same action repeatedly on the same service = systemic."""
+    groups: dict[tuple, int] = {}
+    for o in ops:
+        key = (str(o.get("action") or "unknown"),
+               str(o.get("service") or o.get("subject") or "unknown"))
+        groups[key] = groups.get(key, 0) + 1
+    return [{"action": a, "service": s, "count": n,
+             "signal": "repeated-operation-same-target",
+             "confidence": confidence_for_support(n),
+             "note": "possible systemic issue — investigate root cause"}
+            for (a, s), n in sorted(groups.items(), key=lambda kv: -kv[1])
+            if n >= min_count]
+
+
+def remediation_recurrence(remediations: list[dict[str, Any]],
+                           min_count: int = 2) -> list[dict[str, Any]]:
+    """§153–155 — same finding + same remediation repeating. Suggests
+    root-cause paths; NEVER turns into blind auto-remediation."""
+    groups: dict[tuple, list[dict]] = {}
+    for r in remediations:
+        key = (str(r.get("finding") or "unknown"),
+               str(r.get("remediation") or "unknown"))
+        groups.setdefault(key, []).append(r)
+    suggestions = {"config": "fix root configuration",
+                   "golden-path": "improve golden path",
+                   "policy": "add policy",
+                   "capacity": "improve capacity"}
+    out = []
+    for (finding, rem), evs in sorted(groups.items()):
+        if len(evs) < min_count:
+            continue
+        target = str(evs[-1].get("category") or "config")
+        out.append({"finding": finding, "remediation": rem,
+                    "recurrences": len(evs),
+                    "evidence": [str(e.get("ref", "")) for e in evs],
+                    "suggested_path": suggestions.get(
+                        target, "fix root configuration"),
+                    "confidence": confidence_for_support(len(evs)),
+                    "auto_remediate": False,     # §155
+                    "note": "understand recurrence before automating"})
+    return out
+
+
+def incident_patterns(incidents: list[dict[str, Any]],
+                      min_support: int = 2) -> list[dict[str, Any]]:
+    """§156–158 — recurring incident signatures with linked evidence."""
+    groups: dict[str, list[dict]] = {}
+    for i in incidents:
+        sig = str(i.get("signature") or
+                  f"{i.get('service','?')}:{i.get('symptom','?')}")
+        groups.setdefault(sig, []).append(i)
+    return [{"pattern": sig, "occurrences": len(evs),
+             "evidence": [str(e.get("incident_id") or e.get("ref", ""))
+                          for e in evs],
+             "services": sorted({str(e.get("service"))
+                                 for e in evs if e.get("service")}),
+             "confidence": confidence_for_support(len(evs)),
+             "causal_claim": False}
+            for sig, evs in sorted(groups.items())
+            if len(evs) >= min_support]
+
+
+def fleet_timeline(sources: dict[str, list[dict[str, Any]]],
+                   limit: int = 200) -> list[dict[str, Any]]:
+    """§159–160 — unified cross-source timeline."""
+    out = []
+    for src, events in sources.items():
+        for e in events:
+            out.append({"ts": e.get("ts", ""), "source": src,
+                        "subject": e.get("subject") or e.get("service")
+                        or e.get("id") or "",
+                        "type": e.get("type") or e.get("kind") or "",
+                        "ref": e.get("ref") or e.get("hash") or ""})
+    out.sort(key=lambda e: e["ts"])
+    return out[-limit:]

platformforge/analytics/policyintel.py

@@ -0,0 +1,139 @@
+"""Cycle 5 Phase F — policy intelligence (§49–57).
+
+Policies stop being only enforcement. Analytics are honest: a policy
+with many exceptions is *distributed evidence*, not automatically a bad
+policy (§52, §392). Recommendations never edit enforcement (§53–54).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.analytics.models import confidence_for_support
+
+DECISIONS = ("allow", "deny", "require-approval", "require-human",
+             "require-owner", "require-dual", "shadow-allow",
+             "shadow-deny")
+
+
+def policy_metrics(decisions: list[dict[str, Any]],
+                   exceptions: list[dict[str, Any]] | None = None,
+                   overrides: list[dict[str, Any]] | None = None,
+                   ) -> dict[str, dict[str, Any]]:
+    """§51 — per-policy decision distribution."""
+    out: dict[str, dict[str, Any]] = {}
+    for d in decisions:
+        pol = str(d.get("policy") or d.get("policy_id") or "unknown")
+        m = out.setdefault(pol, {"evaluations": 0, "allows": 0,
+                                 "denies": 0, "requires_approval": 0,
+                                 "shadow_decisions": 0})
+        m["evaluations"] += 1
+        dec = str(d.get("decision") or "")
+        if dec == "allow":
+            m["allows"] += 1
+        elif dec == "deny":
+            m["denies"] += 1
+        elif dec.startswith("require"):
+            m["requires_approval"] += 1
+        if dec.startswith("shadow"):
+            m["shadow_decisions"] += 1
+    for e in exceptions or []:
+        pol = str(e.get("policy") or "unknown")
+        m = out.setdefault(pol, {"evaluations": 0, "allows": 0,
+                                 "denies": 0, "requires_approval": 0,
+                                 "shadow_decisions": 0})
+        m.setdefault("exceptions", 0)
+        m["exceptions"] += 1
+        if e.get("expired"):
+            m["expired_exceptions"] = m.get("expired_exceptions", 0) + 1
+    for o in overrides or []:
+        pol = str(o.get("policy") or "unknown")
+        m = out.setdefault(pol, {"evaluations": 0, "allows": 0,
+                                 "denies": 0, "requires_approval": 0,
+                                 "shadow_decisions": 0})
+        m["overrides"] = m.get("overrides", 0) + 1
+    for pol, m in out.items():
+        m["sample_size"] = m["evaluations"]
+        m["confidence"] = confidence_for_support(m["evaluations"])
+    return out
+
+
+def false_positive_candidates(metrics: dict[str, dict[str, Any]],
+                              outcomes: dict[str, int] | None = None,
+                              min_support: int = 3) -> list[dict[str, Any]]:
+    """§52 — `candidate_false_positive` only when frequent exception +
+    successful outcome + repeated pattern. Never a bare verdict."""
+    out = []
+    for pol, m in metrics.items():
+        exc = m.get("exceptions", 0)
+        succ = (outcomes or {}).get(pol, 0)
+        if exc >= min_support and succ >= min_support:
+            out.append({
+                "policy": pol, "signal": "candidate_false_positive",
+                "evidence": {"exceptions": exc,
+                             "successful_overrides": succ,
+                             "evaluations": m["evaluations"]},
+                "confidence": confidence_for_support(min(exc, succ)),
+                "verdict": "review-required",   # §53 — never auto-judge
+                "limitations": ["exception ≠ false positive",
+                                "needs human policy review"]})
+    return out
+
+
+def policy_recommendations(metrics: dict[str, dict[str, Any]],
+                           fp_candidates: list[dict[str, Any]]
+                           ) -> list[dict[str, Any]]:
+    """§54 — tighten/relax/split-scope/warning/exception-pattern.
+    `executes: False` always — human review required (§53)."""
+    recs = []
+    fp_pols = {c["policy"] for c in fp_candidates}
+    for pol, m in metrics.items():
+        ev = m.get("evaluations", 0)
+        if ev == 0:
+            recs.append({"policy": pol, "type": "unused-policy",
+                         "recommendation": "review",
+                         "note": "unused ≠ safe to delete",  # §56
+                         "confidence": "low", "executes": False})
+            continue
+        if pol in fp_pols:
+            recs.append({"policy": pol,
+                         "recommendation": "add exception pattern",
+                         "evidence": {"exceptions": m.get("exceptions", 0)},
+                         "confidence": m["confidence"],
+                         "executes": False})
+        deny_rate = m["denies"] / ev
+        if m.get("overrides", 0) >= 3:
+            recs.append({"policy": pol, "recommendation": "split scope",
+                         "evidence": {"overrides": m["overrides"],
+                                      "deny_rate": round(deny_rate, 3)},
+                         "confidence": m["confidence"],
+                         "executes": False})
+        shadow_denies = m.get("shadow_decisions", 0)
+        if shadow_denies >= 3:
+            recs.append({"policy": pol,
+                         "recommendation": "convert to warning",
+                         "evidence": {"shadow_decisions": shadow_denies},
+                         "confidence": m["confidence"],
+                         "executes": False})
+    return recs
+
+
+def policy_drift(configured: list[str],
+                 evaluated: list[str]) -> dict[str, Any]:
+    """§55 — configured vs actually evaluated."""
+    conf, ev = set(configured), set(evaluated)
+    return {"configured": sorted(conf), "evaluated": sorted(ev),
+            "configured_not_evaluated": sorted(conf - ev),
+            "evaluated_not_configured": sorted(ev - conf),
+            "drift": bool(conf ^ ev)}
+
+
+def shadow_analytics(decisions: list[dict[str, Any]]) -> dict[str, Any]:
+    """§57 — would_deny/would_allow + affected teams."""
+    wd = [d for d in decisions if d.get("decision") == "shadow-deny"]
+    wa = [d for d in decisions if d.get("decision") == "shadow-allow"]
+    teams = {str(d.get("team")) for d in wd if d.get("team")}
+    return {"would_deny": len(wd), "would_allow": len(wa),
+            "potential_impact": len(wd),
+            "teams_affected": sorted(teams),
+            "sample_size": len(decisions)}

platformforge/analytics/reliability.py

@@ -0,0 +1,106 @@
+"""Cycle 5 Phase H (2/2) — reliability intelligence (§115–124).
+
+MTTR only from trusted timestamps (§118); change failure rate only
+when deploy↔incident links exist (§119); centrality ≠ criticality —
+reported as separate evidence (§122–124).
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from platformforge.analytics.models import confidence_for_support
+from platformforge.live.models import parse_ts
+
+
+@dataclass
+class ReliabilityProfile:
+    """§116–117."""
+    service_id: str
+    slo: dict[str, Any] = field(default_factory=dict)
+    error_budget_remaining: float | None = None
+    incident_count: int = 0
+    mttr_seconds: float | None = None
+    change_failure_rate: float | None = None
+    rollback_count: int = 0
+    dependency_criticality: str = "unknown"
+    redundancy: int | None = None
+    capacity_risk: str = "unknown"
+    confidence: str = "low"
+    sample_size: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": "platformforge/reliability-profile/v1",
+                **asdict(self)}
+
+
+def build_profile(service_id: str,
+                  incidents: list[dict[str, Any]],
+                  changes: list[dict[str, Any]],
+                  rollbacks: list[dict[str, Any]],
+                  slo: dict[str, Any] | None = None) -> ReliabilityProfile:
+    """Assemble a profile from linked events; each metric keeps its own
+    evidence requirements."""
+    p = ReliabilityProfile(service_id=service_id, slo=slo or {})
+    p.incident_count = len(incidents)
+    p.rollback_count = len(rollbacks)
+    # §118 — MTTR only when incident open/resolve timestamps parse
+    deltas = []
+    for i in incidents:
+        a, b = parse_ts(i.get("opened_at")), parse_ts(i.get("resolved_at"))
+        if a and b and b >= a:
+            deltas.append((b - a).total_seconds())
+    if deltas:
+        p.mttr_seconds = round(sum(deltas) / len(deltas), 1)
+    # §119 — change failure rate only with deploy↔incident links
+    linked = [c for c in changes if c.get("incident_linked")]
+    if changes:
+        p.change_failure_rate = round(len(linked) / len(changes), 3)
+    p.sample_size = len(incidents) + len(changes)
+    p.confidence = confidence_for_support(p.sample_size)
+    return p
+
+
+def fleet_hotspots(profiles: list[ReliabilityProfile],
+                   min_sample: int = 3) -> list[dict[str, Any]]:
+    """§120–121 — decomposed hotspot evidence."""
+    out = []
+    for p in profiles:
+        reasons = []
+        if p.incident_count >= min_sample:
+            reasons.append(f"{p.incident_count} incidents")
+        if p.rollback_count >= 2:
+            reasons.append(f"{p.rollback_count} rollbacks")
+        if p.change_failure_rate is not None and \
+           p.change_failure_rate >= 0.3 and p.sample_size >= min_sample:
+            reasons.append(f"change_failure_rate={p.change_failure_rate}")
+        if p.error_budget_remaining is not None and \
+           p.error_budget_remaining < 0.2:
+            reasons.append("error budget nearly exhausted")
+        if reasons:
+            out.append({"service_id": p.service_id, "type":
+                        "ReliabilityHotspot",
+                        "evidence": reasons,
+                        "confidence": p.confidence,
+                        "sample_size": p.sample_size})
+    return out
+
+
+def blast_concentration(graph, top: int = 5) -> list[dict[str, Any]]:
+    """§122–124 — high dependency centrality, reported *separately*
+    from criticality. Centrality alone never marks a node critical."""
+    deg: dict[str, int] = {}
+    for e in graph.edges.values():
+        if e.kind in ("depends_on", "calls", "consumes", "reads",
+                      "writes"):
+            deg[e.dst] = deg.get(e.dst, 0) + 1
+    out = []
+    for nid, d in sorted(deg.items(), key=lambda kv: -kv[1])[:top]:
+        node = graph.nodes.get(nid)
+        out.append({"node_id": nid, "in_degree": d,
+                    "declared_criticality": (node.attrs.get("criticality")
+                                             if node else None),
+                    "note": "centrality ≠ criticality",
+                    "confidence": "medium" if d >= 5 else "low"})
+    return out

platformforge/analytics/soak.py

@@ -0,0 +1,135 @@
+"""Analytics soak harness (§213–217) — deterministic replay, no wall
+clock. Rounds of bulk inserts + snapshots + queries + retention + forget
++ vacuum + close/reopen + crash + migration, all measured.
+
+Crash safety is simulated honestly: committed data must survive an
+abrupt connection drop; uncommitted data must roll back — both are
+asserted, not assumed. Migration safety is replayed by building a v1
+database by hand and opening it through the store.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import tempfile
+import tracemalloc
+from pathlib import Path
+from time import perf_counter
+from typing import Any
+
+from platformforge.analytics.store import SCHEMA_VERSION, AnalyticsStore
+
+
+def _ev(i: int, subj: str | None = None) -> dict[str, Any]:
+    return {"kind": "operation" if i % 7 else "deploy",
+            "ts": f"2025-{(i % 12) + 1:02d}-{(i % 28) + 1:02d}T00:00:00Z",
+            "subject": subj or f"svc:{i % 97}",
+            "outcome": "converged" if i % 5 else "failed",
+            "source": "soak", "attrs": {"i": i}}
+
+
+def run_soak(events: int = 10_000, rounds: int = 10,
+             snapshots_per_round: int = 5) -> dict[str, Any]:
+    """§214 — N rounds × (events/round) bulk inserts with retention,
+    forget, vacuum and reopen interleaved. Deterministic shape; every
+    number measured."""
+    rep: dict[str, Any] = {"schema": "platformforge/soak/v1",
+                           "events": events, "rounds": rounds}
+    with tempfile.TemporaryDirectory() as td:
+        db = Path(td) / "soak.db"
+        st = AnalyticsStore(db)
+        tracemalloc.start()
+        t_ins = q_ms = 0.0
+        per_round = events // rounds
+        for r in range(rounds):
+            t0 = perf_counter()
+            st.put_events([_ev(r * per_round + i) for i in range(per_round)])
+            t_ins += perf_counter() - t0
+            for s in range(snapshots_per_round):
+                st.put_snapshot(f"fleet-{s % 3}",
+                                {"round": r, "seq": s})
+            t0 = perf_counter()
+            st.events(kind="operation", limit=500)
+            q_ms += perf_counter() - t0
+        _, peak_insert = tracemalloc.get_traced_memory()
+
+        rows_before_gc = st.stats()["rows"]["events"]
+        t0 = perf_counter()
+        forgot = st.forget_subject("svc:0")
+        t_forget = perf_counter() - t0
+        assert not st.events(subject="svc:0")  # verify, not assume
+        t0 = perf_counter()
+        gc = st.gc(event_days=45)            # ~2/3 of the ts window
+        t_gc = perf_counter() - t0
+        rows_after_gc = st.stats()["rows"]["events"]
+
+        t0 = perf_counter()
+        vac = st.vacuum()
+        t_vac = perf_counter() - t0
+
+        # restart/reopen: committed rows must be intact
+        st.close()
+        st = AnalyticsStore(db)
+        rows_reopened = st.stats()["rows"]["events"]
+        reopen_ok = rows_reopened == rows_after_gc
+
+        # crash safety: an abrupt drop keeps committed rows and rolls
+        # back whatever was in flight
+        raw = sqlite3.connect(db)
+        raw.execute("INSERT INTO events(kind,ts,subject,outcome,source,"
+                    "source_ref,attrs) VALUES('x','t','s','o','s','','{}')")
+        raw.close()  # no commit — must not persist
+        rows_after_crash = st.stats()["rows"]["events"]
+        tracemalloc.stop()
+
+        rep.update({
+            "verdict": "pass" if reopen_ok
+                       and rows_after_crash == rows_reopened else "fail",
+            "bulk_insert_ms": round(t_ins * 1000, 2),
+            "query_total_ms": round(q_ms * 1000, 2),
+            "rows_before_gc": rows_before_gc,
+            "gc": gc, "gc_ms": round(t_gc * 1000, 2),
+            "rows_after_gc": rows_after_gc,
+            "forgotten": forgot["events_deleted"],
+            "forget_ms": round(t_forget * 1000, 2),
+            "vacuum": vac, "vacuum_ms": round(t_vac * 1000, 2),
+            "reopen_rows_intact": reopen_ok,
+            "crash_rollback_ok": rows_after_crash == rows_reopened,
+            "db_size_bytes": db.stat().st_size,
+            "peak_insert_kib": round(peak_insert / 1024, 1),
+            "schema_version": SCHEMA_VERSION})
+        st.close()
+    return rep
+
+
+def run_migration_replay() -> dict[str, Any]:
+    """§217 — build a schema-v1 database by hand (as a previous release
+    wrote it), reopen through the current store, verify upgrade."""
+    with tempfile.TemporaryDirectory() as td:
+        db = Path(td) / "old.db"
+        raw = sqlite3.connect(db)
+        raw.executescript("""
+            CREATE TABLE events (id INTEGER PRIMARY KEY AUTOINCREMENT,
+                kind TEXT NOT NULL, ts TEXT NOT NULL, subject TEXT NOT NULL,
+                outcome TEXT NOT NULL, source TEXT NOT NULL,
+                source_ref TEXT NOT NULL, attrs TEXT NOT NULL);
+            CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+            INSERT INTO meta VALUES('schema_version', '1');
+            INSERT INTO events VALUES(1,'op','2025-01-01','svc:a',
+                'ok','legacy','','{}');
+        """)
+        raw.commit(); raw.close()
+        st = AnalyticsStore(db)
+        ver = st._db.execute(
+            "SELECT value FROM meta WHERE key='schema_version'"
+        ).fetchone()[0]
+        idx = st._db.execute(
+            "SELECT name FROM sqlite_master WHERE type='index' AND "
+            "name='ix_events_subj_kind'").fetchone()
+        rows = st.events()
+        ok = int(ver) == SCHEMA_VERSION and idx is not None \
+            and len(rows) == 1 and rows[0]["subject"] == "svc:a"
+        st.close()
+        return {"migrated": ok, "from_version": 1,
+                "to_version": int(ver), "index_present": bool(idx),
+                "rows_preserved": len(rows)}