platformforge 0.1.0__py3-none-any.whl

platformforge/observe/postmortem.py

@@ -0,0 +1,72 @@
+"""§88/§89 Incident timeline + postmortem engine.
+
+Timeline: merge alerts/changes/logs/k8s events into one canonical,
+sorted sequence (§88). Postmortem: draft strictly from evidence —
+root cause stays `unresolved` unless a single hypothesis is both
+strongly-supported and uncontradicted (§89: never invent a cause).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+EVENT_KINDS = ("change", "deploy", "alert", "log", "trace", "metric",
+               "k8s_event", "cloud_event")
+
+
+def timeline(events: list[dict[str, Any]]) -> dict[str, Any]:
+    """Canonical sorted timeline; every event carries its declared kind
+    and source — nothing is reclassified as causal."""
+    norm = []
+    for e in events:
+        norm.append({"at": float(e.get("at") or e.get("ts") or 0),
+                     "kind": e.get("kind", "event"),
+                     "summary": e.get("summary") or e.get("message")
+                                or e.get("name") or "?",
+                     "source": e.get("source", "unknown"),
+                     "target": e.get("target") or e.get("service"),
+                     "raw_ref": e.get("id") or e.get("fact_id")})
+    norm.sort(key=lambda e: e["at"])
+    kinds = {}
+    for e in norm:
+        kinds[e["kind"]] = kinds.get(e["kind"], 0) + 1
+    return {"timeline": norm, "counts": {"events": len(norm), **kinds}}
+
+
+def postmortem(incident: dict[str, Any],
+               hypotheses: list[dict[str, Any]] | None = None,
+               facts: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+    """Draft postmortem — evidence-only, gaps named as gaps."""
+    hyps = hypotheses or incident.get("hypotheses") or []
+    # root cause only when exactly one hypothesis is strongly-supported
+    strong = [h for h in hyps if h.get("causality") == "strongly-supported"]
+    contradicted = [h for h in hyps if h.get("causality") == "contradicted"]
+    if len(strong) == 1 and not contradicted:
+        root = {"status": "candidate-root-cause",
+                "evidence": strong[0],
+                "note": "strongly-supported ≠ confirmed — human sign-off "
+                        "required"}
+    else:
+        root = {"status": "unresolved",
+                "reason": ("multiple equally-supported hypotheses"
+                           if len(strong) > 1 else
+                           "contradiction present"
+                           if contradicted else
+                           "no hypothesis reached strongly-supported")}
+    return {
+        "postmortem": {
+            "title": incident.get("title", "incident"),
+            "status": "draft",
+            "root_cause": root,
+            "timeline_events": len(incident.get("timeline") or []),
+            "hypotheses": [{"summary": (h.get("change") or h),
+                            "causality": h.get("causality", "unknown")}
+                           for h in hyps],
+            "evidence_ids": [f.get("fact_id") for f in facts or []
+                             if f.get("fact_id")],
+            "open_questions": [
+                "confirm root cause via independent evidence",
+                "verify action items against observed state",
+            ],
+            "note": "draft generated from evidence only — a blank root "
+                    "cause is a true state, not a template error"}}

platformforge/observe/prometheus.py

@@ -0,0 +1,88 @@
+"""§85 Prometheus — offline ingestion of rule files and query exports.
+
+Rules (PrometheusRule CRDs or prometheus.yml `groups[].rules[]`) are T3
+declared config. Query exports (instant/range JSON `data.result[]`) are
+T1 provider-observed measurements. The two never share a tier.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from platformforge.models.base import stable_id
+
+
+def _rule_groups(doc: dict[str, Any]) -> list[dict[str, Any]]:
+    spec = doc.get("spec") or doc
+    return [g for g in spec.get("groups") or [] if isinstance(g, dict)]
+
+
+def analyze_prometheus(path: str | Path) -> dict[str, Any]:
+    root = Path(path)
+    files = (sorted(root.rglob("*.yaml")) + sorted(root.rglob("*.yml")) +
+             sorted(root.rglob("*.json"))) if root.is_dir() else [root]
+    facts: list[dict[str, Any]] = []
+    unresolved: list[dict[str, Any]] = []
+
+    for f in files:
+        try:
+            text = f.read_text()
+            doc = (yaml.safe_load(text) if f.suffix in (".yaml", ".yml")
+                   else json.loads(text))
+        except (OSError, yaml.YAMLError, json.JSONDecodeError):
+            continue
+        if not isinstance(doc, dict):
+            continue
+        # Prometheus query export: {"status":"success","data":{"result":[...]}}
+        if isinstance(doc.get("data"), dict) and \
+                isinstance(doc["data"].get("result"), list):
+            for series in doc["data"]["result"]:
+                metric = series.get("metric") or {}
+                name = metric.get("__name__", "?")
+                val = series.get("value") or series.get("values")
+                facts.append({
+                    "fact_id": stable_id("PF-PROM", "series",
+                                         f"{f}:{name}:{len(facts)}"),
+                    "kind": "prometheus.series", "source": str(f),
+                    "location": name, "tier": 1,  # measured
+                    "attrs": {"metric": name, "labels": metric,
+                              "points": len(val) if isinstance(val, list)
+                              else (1 if val else 0),
+                              "result_type": doc["data"].get("resultType")}})
+            continue
+        # Rule files: groups[].rules[] (native or PrometheusRule CRD)
+        groups = _rule_groups(doc)
+        for g in groups:
+            for r in g.get("rules") or []:
+                if not isinstance(r, dict):
+                    continue
+                is_alert = "alert" in r
+                name = r.get("alert") or r.get("record") or "?"
+                loc = f"{f}::{g.get('name', '?')}/{name}"
+                expr = str(r.get("expr", ""))
+                facts.append({
+                    "fact_id": stable_id("PF-PROM", "rule", loc),
+                    "kind": "prometheus.alert" if is_alert
+                            else "prometheus.recording",
+                    "source": str(f), "location": loc, "tier": 3,
+                    "attrs": {
+                        "name": name, "group": g.get("name"),
+                        "kind": "alert" if is_alert else "record",
+                        "expr": expr, "for": r.get("for"),
+                        "severity": (r.get("labels") or {}).get("severity"),
+                        "has_runbook": bool(
+                            (r.get("annotations") or {}).get("runbook_url")),
+                        "service_refs": sorted({
+                            p.split('"')[0]
+                            for p in expr.split('service="')[1:]})
+                            if 'service="' in expr else [],
+                        "graph": {
+                            "nodes": [{"kind": "alert", "label": name}]
+                            if is_alert else [],
+                            "edges": []}}})
+    return {"facts": facts, "unresolved": unresolved,
+            "counts": {"facts": len(facts)}}

platformforge/observe/slo.py

@@ -0,0 +1,125 @@
+"""SLO contracts + error budgets per contracts/slo-contract.schema.json.
+
+Budget = (1 − target) × total events. Burn rate = observed error ratio ÷
+allowed error ratio. Unresolved inputs produce unresolved outputs — never a
+hedged number.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from platformforge.models.base import stable_id
+
+_WINDOW_RE = re.compile(r"^(\d+)([dhm])$")
+_WINDOW_SECONDS = {"d": 86400, "h": 3600, "m": 60}
+
+
+@dataclass
+class SloContract:
+    service: str
+    sli: str
+    target: float
+    window: str
+    burn_rate_alerts: list[dict[str, Any]] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> SloContract:
+        if not _WINDOW_RE.match(d.get("window", "")):
+            raise ValueError(f"bad window: {d.get('window')!r} (use 30d/24h/60m)")
+        return cls(service=d["service"], sli=d["sli"], target=float(d["target"]),
+                   window=d["window"],
+                   burn_rate_alerts=d.get("burn_rate_alerts") or [])
+
+    @classmethod
+    def load(cls, path: str | Path) -> SloContract:
+        doc = yaml.safe_load(Path(path).read_text())
+        return cls.from_dict(doc)
+
+    @property
+    def window_seconds(self) -> int:
+        n, u = _WINDOW_RE.match(self.window).groups()
+        return int(n) * _WINDOW_SECONDS[u]
+
+    @property
+    def allowed_error_ratio(self) -> float:
+        return 1.0 - self.target / 100.0
+
+
+def error_budget(contract: SloContract,
+                 good_events: int | None = None,
+                 bad_events: int | None = None,
+                 total_events: int | None = None) -> dict[str, Any]:
+    """Budget math over measured events. Missing events → unresolved fields."""
+    if total_events is None and good_events is not None \
+            and bad_events is not None:
+        total_events = good_events + bad_events
+    if bad_events is None and good_events is not None \
+            and total_events is not None:
+        bad_events = total_events - good_events
+    if total_events is None or total_events <= 0 or bad_events is None:
+        return {"service": contract.service, "sli": contract.sli,
+                "status": "unresolved",
+                "unresolved": "platform.slo.unresolved",
+                "missing": ["good_events|bad_events|total_events"]}
+    allowed_total = contract.allowed_error_ratio * total_events
+    consumed = bad_events
+    remaining = allowed_total - consumed
+    observed_ratio = bad_events / total_events
+    burn = (observed_ratio / contract.allowed_error_ratio
+            if contract.allowed_error_ratio > 0 else float("inf"))
+    status = "exhausted" if remaining <= 0 else \
+        ("at_risk" if burn >= 1.0 else "ok")
+    # time-to-exhaustion at current burn (window remaining fraction)
+    alerts = []
+    for a in contract.burn_rate_alerts:
+        if burn >= a.get("burn_rate", 0):
+            alerts.append({"window": a["window"], "burn_rate": a["burn_rate"],
+                           "firing": True})
+    return {
+        "service": contract.service, "sli": contract.sli,
+        "target": contract.target, "window": contract.window,
+        "status": status,
+        "total_events": total_events, "bad_events": bad_events,
+        "observed_error_ratio": round(observed_ratio, 6),
+        "allowed_error_ratio": round(contract.allowed_error_ratio, 6),
+        "burn_rate": round(burn, 4),
+        "budget": {"total_allowed_events": round(allowed_total, 2),
+                   "consumed_events": consumed,
+                   "remaining_events": round(remaining, 2),
+                   "remaining_fraction": round(
+                       remaining / allowed_total, 4) if allowed_total else 0},
+        "burn_alerts_firing": alerts,
+        "fact_id": stable_id("PF-SLO", contract.service, contract.sli,
+                             str(total_events), str(bad_events)),
+    }
+
+
+def multi_window_burn(contract: SloContract,
+                      windows: dict[str, dict[str, int]]) -> dict[str, Any]:
+    """§87 — multi-window burn rate (Google SRE alerting shape):
+    {window: {good, bad}} per window; each window reports its own burn
+    and only windows with data produce verdicts."""
+    results = {}
+    for w, ev in sorted(windows.items()):
+        good, bad = ev.get("good_events"), ev.get("bad_events")
+        if good is None or bad is None or (good + bad) <= 0:
+            results[w] = {"status": "unresolved",
+                          "missing": ["good_events|bad_events"]}
+            continue
+        total = good + bad
+        ratio = bad / total
+        burn = (ratio / contract.allowed_error_ratio
+                if contract.allowed_error_ratio else float("inf"))
+        results[w] = {"total_events": total, "burn_rate": round(burn, 4),
+                      "status": "firing" if burn >= 1 else "ok"}
+    firing = [w for w, r in results.items() if r.get("status") == "firing"]
+    return {"service": contract.service, "sli": contract.sli,
+            "windows": results, "firing_windows": firing,
+            "note": "burn is per-window measured; unresolved windows are "
+                    "not smoothed into a verdict"}

platformforge/ops/__init__.py

@@ -0,0 +1,8 @@
+"""Cycle 4 — governed operations plane.
+
+The operations plane never acts directly: intent → plan → simulate →
+risk → policy → approval → execution envelope → preconditions →
+typed-action executors → verify → converge/rollback → audit. The core
+package is deterministic and SDK-free; mutation happens only inside
+host-side executor transports behind typed actions (ADR-0021/0027).
+"""

platformforge/ops/actions.py

@@ -0,0 +1,215 @@
+"""Cycle 4 — typed action vocabulary (§68–69, ADR-0021).
+
+Every mutation is a *typed action* with a declared executor, params
+schema, risk base, dry-run and rollback support. There is deliberately
+**no `shell.run`** — anything that cannot be expressed as a typed action
+refuses (`PF-OPS-UNSTRUCTURED`) instead of degrading to arbitrary shell.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ActionSpec:
+    """Contract for one typed action (§70 executor contract fields,
+    extended cycle-4.1 §32: explicit rollback contract)."""
+    action: str
+    executor: str                    # git|terraform|tofu|argocd|kubernetes|observe
+    mutating: bool = False
+    risk_base: str = "R0"
+    required_params: tuple[str, ...] = ()
+    optional_params: tuple[str, ...] = ()
+    dry_run: bool = True             # executor supports dry-run
+    idempotent: bool = True
+    rollback_action: str = ""        # typed action that reverses it
+    required_permissions: tuple[str, ...] = ()
+    timeout_s: int = 300
+    side_effects: str = ""           # declared blast: pr-created, pods…
+    # §32 — rollback contract v2
+    rollback_strategy: str = "unknown"   # direct-inverse|source-revert|
+        # previous-revision|compensating-operation|replan-required|
+        # manual-only|impossible|unknown
+    pre_state_requirements: tuple[str, ...] = ()   # §31 capture contract
+    post_result_requirements: tuple[str, ...] = ()  # from exec result
+    rollback_builder: str = ""       # key into rollback_builders.BUILDERS
+
+
+_ACTIONS: dict[str, ActionSpec] = {a.action: a for a in [
+    # ---- Git (source-of-truth executor) --------------------------------
+    ActionSpec("git.create_branch", "git", True, "R0",
+               ("repo", "branch", "base"), ("remote",),
+               rollback_action="git.delete_branch",
+               required_permissions=("git:write",),
+               rollback_strategy="direct-inverse",
+               rollback_builder="git.create_branch"),
+    ActionSpec("git.apply_patch", "git", True, "R1",
+               ("repo", "patch"), ("branch", "check_only"),
+               rollback_action="git.revert_commit",
+               rollback_strategy="direct-inverse",
+               pre_state_requirements=("pre_change_commit",),
+               post_result_requirements=("resulting_commit",),
+               rollback_builder="git.apply_patch"),
+    ActionSpec("git.commit", "git", True, "R1",
+               ("repo", "message"), ("signoff",),
+               rollback_action="git.revert_commit",
+               rollback_strategy="direct-inverse",
+               post_result_requirements=("resulting_commit",),
+               rollback_builder="git.commit"),
+    ActionSpec("git.push", "git", True, "R1", ("repo", "branch"),
+               ("remote",),
+               rollback_strategy="manual-only"),
+    ActionSpec("git.open_pr", "git", True, "R2",
+               ("repo", "title", "head", "base", "body"),
+               ("draft", "labels"), rollback_action="git.close_pr",
+               required_permissions=("github:pull-request:write",),
+               side_effects="pr-created",
+               rollback_strategy="direct-inverse",
+               post_result_requirements=("pr",),
+               rollback_builder="git.open_pr"),
+    ActionSpec("git.delete_branch", "git", True, "R1", ("repo", "branch"),
+               rollback_strategy="previous-revision",
+               pre_state_requirements=("branch_sha",),
+               rollback_builder="git.delete_branch"),
+    ActionSpec("git.revert_commit", "git", True, "R1",
+               ("repo", "commit_sha"),
+               rollback_strategy="manual-only"),
+    ActionSpec("git.close_pr", "git", True, "R1", ("repo", "pr"),
+               rollback_strategy="manual-only"),
+    # ---- Terraform / OpenTofu -------------------------------------------
+    ActionSpec("terraform.validate", "terraform", False, "R0", ("workdir",)),
+    ActionSpec("terraform.plan", "terraform", False, "R0",
+               ("workdir",), ("out", "target", "refresh_only")),
+    ActionSpec("terraform.show", "terraform", False, "R0", ("workdir", "plan_file")),
+    ActionSpec("terraform.apply_saved_plan", "terraform", True, "R3",
+               ("workdir", "plan_file", "plan_hash"),
+               rollback_action="terraform.apply_saved_plan",
+               required_permissions=("terraform:apply",),
+               timeout_s=1800,
+               side_effects="infrastructure-mutation",
+               # §15–19 — a saved forward plan is NEVER a rollback plan;
+               # reversal is a new governed op (source-revert → plan BA).
+               rollback_strategy="replan-required",
+               pre_state_requirements=("source_ref", "workspace",
+                                       "state_serial",
+                                       "resource_addresses"),
+               rollback_builder="terraform.apply_saved_plan"),
+    ActionSpec("tofu.validate", "tofu", False, "R0", ("workdir",)),
+    ActionSpec("tofu.plan", "tofu", False, "R0", ("workdir",),
+               ("out", "refresh_only")),
+    ActionSpec("tofu.apply_saved_plan", "tofu", True, "R3",
+               ("workdir", "plan_file", "plan_hash"),
+               required_permissions=("tofu:apply",), timeout_s=1800,
+               side_effects="infrastructure-mutation",
+               rollback_strategy="replan-required",
+               pre_state_requirements=("source_ref", "workspace",
+                                       "state_serial",
+                                       "resource_addresses"),
+               rollback_builder="tofu.apply_saved_plan"),
+    # ---- GitOps -----------------------------------------------------------
+    ActionSpec("argocd.sync", "argocd", True, "R3",
+               ("app",), ("revision", "resource", "dry_run"),
+               rollback_action="argocd.rollback",
+               required_permissions=("argocd:sync",),
+               side_effects="cluster-reconcile",
+               rollback_strategy="previous-revision",
+               pre_state_requirements=("history_id", "previous_revision"),
+               rollback_builder="argocd.sync"),
+    ActionSpec("argocd.diff", "argocd", False, "R0", ("app",), ("revision",)),
+    ActionSpec("argocd.wait", "argocd", False, "R0", ("app",),
+               ("health", "timeout_s")),
+    ActionSpec("argocd.rollback", "argocd", True, "R3",
+               ("app",), ("history_id",),
+               required_permissions=("argocd:sync",),
+               rollback_strategy="manual-only"),
+    # ---- Kubernetes (narrow, §82) ----------------------------------------
+    ActionSpec("kubernetes.scale", "kubernetes", True, "R2",
+               ("kind", "name", "replicas"),
+               ("namespace", "context", "current_replicas",
+                "resource_version"),
+               rollback_action="kubernetes.scale",
+               required_permissions=("k8s:*/scale:update",),
+               side_effects="workload-capacity",
+               rollback_strategy="direct-inverse",
+               pre_state_requirements=("replicas", "resource_version"),
+               rollback_builder="kubernetes.scale"),
+    ActionSpec("kubernetes.rollout_restart", "kubernetes", True, "R2",
+               ("kind", "name"), ("namespace", "context"),
+               rollback_action="kubernetes.rollout_undo",
+               required_permissions=("k8s:workloads:patch",),
+               side_effects="pod-recreation",
+               rollback_strategy="previous-revision",
+               pre_state_requirements=("revision",),
+               rollback_builder="kubernetes.rollout_restart"),
+    ActionSpec("kubernetes.rollout_undo", "kubernetes", True, "R3",
+               ("kind", "name"), ("namespace", "to_revision"),
+               required_permissions=("k8s:workloads:patch",),
+               rollback_strategy="manual-only"),
+    ActionSpec("kubernetes.annotate", "kubernetes", True, "R1",
+               ("kind", "name", "annotations"),
+               ("namespace", "resource_version", "remove_annotations"),
+               rollback_action="kubernetes.annotate",
+               side_effects="metadata-only",
+               rollback_strategy="direct-inverse",
+               pre_state_requirements=("annotations",),
+               rollback_builder="kubernetes.annotate"),
+    ActionSpec("kubernetes.rollout_status", "kubernetes", False, "R0",
+               ("kind", "name"), ("namespace", "timeout_s")),
+    # ---- Observation (read-only steps) ------------------------------------
+    ActionSpec("k8s.observe", "observe", False, "R0",
+               ("resource_types",), ("namespace",)),
+    ActionSpec("aws.observe", "observe", False, "R0", ("services",),
+               ("region",)),
+]}
+
+FORBIDDEN_ACTIONS = ("shell.run", "execute_anything", "aws.call",
+                     "kubectl.exec", "eval")
+
+
+def spec_for(action: str) -> ActionSpec | None:
+    return _ACTIONS.get(action)
+
+
+def validate_action(action: str, params: dict[str, Any]
+                    ) -> dict[str, Any] | None:
+    """Return None when valid, else a refusal dict."""
+    if action in FORBIDDEN_ACTIONS:
+        return {"refusal": "PF-OPS-UNSTRUCTURED",
+                "unlock": "use a typed action from the vocabulary — "
+                          "arbitrary shell is refused by design (ADR-0021)"}
+    spec = _ACTIONS.get(action)
+    if spec is None:
+        return {"refusal": "PF-OPS-UNKNOWN-ACTION",
+                "unlock": f"action must be one of {sorted(_ACTIONS)}"}
+    missing = [p for p in spec.required_params if p not in params]
+    if missing:
+        return {"refusal": "PF-OPS-ACTION-PARAMS",
+                "unlock": f"{action} requires params {missing}"}
+    unknown = [p for p in params
+               if p not in spec.required_params + spec.optional_params]
+    if unknown:
+        return {"refusal": "PF-OPS-ACTION-PARAMS",
+                "unlock": f"{action} does not accept params {unknown}"}
+    return None
+
+
+def actions_for_executor(executor: str) -> list[str]:
+    return sorted(a for a, s in _ACTIONS.items() if s.executor == executor)
+
+
+def catalog() -> dict[str, Any]:
+    return {a: {"executor": s.executor, "mutating": s.mutating,
+                "risk_base": s.risk_base, "dry_run": s.dry_run,
+                "idempotent": s.idempotent,
+                "rollback_action": s.rollback_action,
+                "rollback_strategy": s.rollback_strategy,
+                "pre_state_requirements": list(s.pre_state_requirements),
+                "post_result_requirements":
+                    list(s.post_result_requirements),
+                "rollback_builder": s.rollback_builder,
+                "required_permissions": list(s.required_permissions),
+                "timeout_s": s.timeout_s,
+                "side_effects": s.side_effects}
+            for a, s in sorted(_ACTIONS.items())}

platformforge/ops/analytics.py

@@ -0,0 +1,83 @@
+"""Cycle 4 §172–175, §250–254 — LEARN phase: roll stored operations up
+into honest, reproducible analytics.
+
+Everything here derives *only* from the append-only store — no external
+telemetry, no estimates. Absent data is reported as absent, never zero.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.live.models import now_iso, parse_ts
+from platformforge.ops.store import OperationStore
+
+ANALYTICS_SCHEMA = "platformforge/ops-analytics/v1"
+
+
+def operation_analytics(store: OperationStore) -> dict[str, Any]:
+    """Roll up every stored operation into outcome/economy metrics."""
+    ops = store.list_operations()
+    by_state: dict[str, int] = {}
+    events: dict[str, int] = {}
+    per_action: dict[str, dict[str, int]] = {}
+    durations_s: list[float] = []
+    terminal = {"converged", "failed", "rolled-back", "cancelled",
+                "expired"}
+    succeeded = failed = rolled = denied = 0
+    for op_id in ops:
+        op = store.load_operation(op_id)
+        led = store.load_ledger(op_id)
+        state = op.state if op else "unknown"
+        by_state[state] = by_state.get(state, 0) + 1
+        if state == "converged":
+            succeeded += 1
+        elif state == "rolled-back":
+            rolled += 1
+        elif state == "failed":
+            failed += 1
+        for e in led.entries:
+            events[e.event] = events.get(e.event, 0) + 1
+            act = (e.data or {}).get("action")
+            if act and e.event.startswith("step."):
+                a = per_action.setdefault(
+                    act, {"started": 0, "completed": 0, "failed": 0})
+                if e.event == "step.started":
+                    a["started"] += 1
+                elif e.event == "step.completed":
+                    a["completed"] += 1
+                elif e.event == "step.failed":
+                    a["failed"] += 1
+            if e.event == "approval.denied":
+                denied += 1
+        # duration from history transitions
+        if op and len(op.history) >= 2:
+            t0 = parse_ts(op.history[0].get("at", ""))
+            t1 = parse_ts(op.history[-1].get("at", ""))
+            if t0 and t1 and t1 >= t0:
+                durations_s.append((t1 - t0).total_seconds())
+    closed = succeeded + failed + rolled
+    return {
+        "schema": ANALYTICS_SCHEMA,
+        "generated_at": now_iso(),
+        "operations": {
+            "total": len(ops), "by_state": by_state,
+            "terminal": sum(by_state.get(s, 0) for s in terminal),
+            "converged": succeeded, "failed": failed,
+            "rolled_back": rolled,
+            "success_rate": (succeeded / closed if closed else None),
+            "rollback_rate": (rolled / closed if closed else None)},
+        "approvals": {"denied": denied},
+        "ledger_events": events,
+        "per_action": per_action,
+        "durations_s": {
+            "count": len(durations_s),
+            "avg": (sum(durations_s) / len(durations_s)
+                    if durations_s else None),
+            "max": max(durations_s) if durations_s else None},
+        "notes": [
+            ("derived from the local append-only store only — "
+             "a remote host's operations are not visible"),
+            ("success/rollback rates are None (not zero) when no "
+             "terminal operations exist"),
+        ]}