platformforge 0.1.0__py3-none-any.whl

platformforge/analytics/goldenpath.py

@@ -0,0 +1,131 @@
+"""Cycle 5 Phase E — golden path intelligence (§72–81).
+
+Escape hatches are *platform gap signals*, never developer blame
+(§75–76). Comparisons carry caveats — correlation ≠ causality (§78–79).
+DX metrics measure platform friction, never individual people
+(§144–149, §305).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.analytics.models import confidence_for_support
+
+ESCAPE_REASONS = ("missing-capability", "insufficient-flexibility",
+                  "policy-block", "performance", "cost",
+                  "unsupported-runtime", "manual-preference", "unknown")
+
+
+def golden_path_analytics(requests: list[dict[str, Any]],
+                          outcomes: list[dict[str, Any]] | None = None,
+                          escapes: list[dict[str, Any]] | None = None,
+                          ) -> dict[str, Any]:
+    """§73–80 — adoption + friction + escapes + outcome correlation."""
+    by_path: dict[str, dict[str, Any]] = {}
+    for r in requests:
+        p = by_path.setdefault(
+            str(r.get("path") or r.get("template") or "unknown"),
+            {"requests": 0, "successful": 0, "failed": 0,
+             "abandoned": 0, "manual_overrides": 0,
+             "approval_waits": [], "retries": 0})
+        p["requests"] += 1
+        st = r.get("status")
+        if st in ("provisioned", "converged", "ready"):
+            p["successful"] += 1
+        elif st in ("failed", "refused"):
+            p["failed"] += 1
+        elif st == "abandoned":
+            p["abandoned"] += 1
+        if r.get("manual_override"):
+            p["manual_overrides"] += 1
+        if r.get("approval_wait_s"):
+            p["approval_waits"].append(r["approval_wait_s"])
+        p["retries"] += int(r.get("retries", 0))
+    esc_by_path: dict[str, dict[str, int]] = {}
+    for e in escapes or []:
+        path = str(e.get("path") or "unknown")
+        reason = str(e.get("reason") or "unknown")
+        if reason not in ESCAPE_REASONS:
+            reason = "unknown"
+        d = esc_by_path.setdefault(path, {})
+        d[reason] = d.get(reason, 0) + 1
+    for path, p in by_path.items():
+        n = p["requests"] or 1
+        p["success_rate"] = round(p["successful"] / n, 3)
+        p["escape_reasons"] = esc_by_path.get(path, {})
+        p["escapes"] = sum(p["escape_reasons"].values())
+        p["friction"] = {
+            "failed": p["failed"], "manual_overrides":
+            p["manual_overrides"], "retries": p["retries"],
+            "median_approval_wait_s": (
+                sorted(p["approval_waits"])[len(p["approval_waits"]) // 2]
+                if p["approval_waits"] else None)}
+        del p["approval_waits"]
+        p["sample_size"] = p["requests"]
+        p["confidence"] = confidence_for_support(p["requests"])
+    # §78–79 — outcome comparison with caveats
+    comparison = _compare(by_path, outcomes or [])
+    return {"schema": "platformforge/golden-path-analytics/v1",
+            "paths": by_path, "comparison": comparison,
+            "caveats": ["correlation is not causality",
+                        "escape = platform gap signal, not blame",
+                        "small samples cap confidence"]}
+
+
+def _compare(paths: dict[str, dict[str, Any]],
+             outcomes: list[dict[str, Any]]) -> dict[str, Any]:
+    """Correlate path → deployment quality/ops success/incidents."""
+    out: dict[str, Any] = {}
+    for o in outcomes:
+        path = str(o.get("path") or "unknown")
+        d = out.setdefault(path, {"deployments": 0, "incidents": 0,
+                                  "rollbacks": 0})
+        d["deployments"] += 1
+        if o.get("incident"):
+            d["incidents"] += 1
+        if o.get("rollback"):
+            d["rollbacks"] += 1
+    for path, d in out.items():
+        n = d["deployments"] or 1
+        d["incident_rate"] = round(d["incidents"] / n, 3)
+        d["rollback_rate"] = round(d["rollbacks"] / n, 3)
+        d["confidence"] = confidence_for_support(d["deployments"])
+        d["causal_claim"] = False
+    return out
+
+
+def golden_path_recommendations(analytics: dict[str, Any],
+                                min_support: int = 3) -> list[dict[str, Any]]:
+    """§80 — evidence-backed improvement suggestions only."""
+    recs = []
+    for path, p in analytics.get("paths", {}).items():
+        if p["requests"] < min_support:
+            continue
+        esc = p.get("escape_reasons", {})
+        top_escape = max(esc.items(), key=lambda kv: kv[1], default=None)
+        if p["escapes"] >= 3 and top_escape:
+            recs.append({
+                "path": path, "type": "improve-golden-path",
+                "action": {"missing-capability": "add capability",
+                           "insufficient-flexibility": "improve default",
+                           "policy-block": "reduce approval",
+                           "performance": "automate stage",
+                           "cost": "improve default",
+                           "unsupported-runtime": "add capability",
+                           "manual-preference": "change documentation",
+                           "unknown": "change documentation"}.get(
+                               top_escape[0], "change documentation"),
+                "evidence": {"escapes": p["escapes"],
+                             "top_reason": top_escape[0],
+                             "requests": p["requests"]},
+                "confidence": p["confidence"],
+                "executes": False})
+        fr = p.get("friction", {})
+        if fr.get("failed", 0) >= 3:
+            recs.append({"path": path, "type": "reduce-friction",
+                         "action": "automate stage",
+                         "evidence": {"failed": fr["failed"]},
+                         "confidence": p["confidence"],
+                         "executes": False})
+    return recs

platformforge/analytics/history.py

@@ -0,0 +1,233 @@
+"""Cycle 5 Phase C — HistoryEngine (§36–48).
+
+Unifies historical sources into one *normalized event stream* — never
+mutating the source stores (§298). Windows: 24h/7d/30d/90d/custom
+(§39). Patterns are deterministic counts with explicit support +
+confidence caps from sample size (§44, §232–233); correlation is
+reported, never causality (§41).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from platformforge.analytics.models import HistoricalPattern, confidence_for_support
+from platformforge.live.models import parse_ts
+
+WINDOWS = {"24h": timedelta(hours=24), "7d": timedelta(days=7),
+           "30d": timedelta(days=30), "90d": timedelta(days=90)}
+
+EVENT_KINDS = ("observation", "operation", "drift", "incident",
+               "deployment", "policy_decision", "approval", "rollback",
+               "golden_path_request", "cost", "slo", "remediation")
+
+
+@dataclass
+class HistoryEvent:
+    """Normalized event — `source_ref` points back to the store record."""
+    kind: str
+    ts: datetime
+    subject: str = ""               # resource/service/policy id
+    outcome: str = ""
+    source: str = ""                # store name
+    source_ref: str = ""            # entry hash / event id
+    attrs: dict[str, Any] = field(default_factory=dict)
+
+
+class HistoryEngine:
+    """Aggregates normalized events from pluggable sources.
+
+    Sources register as callables returning `HistoryEvent`s; built-in
+    adapters cover Observation/Operation stores, drift journal,
+    incidents and golden-path requests (§37).
+    """
+
+    def __init__(self):
+        self._sources: list[tuple[str, Any]] = []
+        self._events: list[HistoryEvent] = []
+
+    def register(self, name: str, fn) -> None:
+        self._sources.append((name, fn))
+
+    # -- ingest adapters (§37) --------------------------------------
+    def ingest_operations(self, store) -> int:
+        """OperationStore ledgers → operation/rollback/approval events."""
+        n = 0
+        for op_id in store.list_operations():
+            try:
+                led = store.load_ledger(op_id)
+            except (OSError, ValueError, KeyError):
+                continue
+            for ent in led.entries:
+                kind = {"step.completed": "operation",
+                        "rollback.completed": "rollback",
+                        "rollback.failed": "rollback",
+                        "created": "operation"}.get(ent.event)
+                if kind is None:
+                    kind = "operation" if ent.event.startswith(
+                        "step.") else None
+                if kind is None:
+                    continue
+                self._events.append(HistoryEvent(
+                    kind=kind, ts=parse_ts(ent.ts) or
+                    datetime.now(timezone.utc),
+                    subject=op_id, outcome=str(ent.data.get("outcome",
+                                                            ent.event)),
+                    source="operation_store", source_ref=ent.hash,
+                    attrs={"event": ent.event, **ent.data}))
+                n += 1
+        return n
+
+    def ingest_events(self, kind: str, events: list[dict[str, Any]],
+                      source: str) -> int:
+        """Generic adapter — drift journal, incidents, deploys, SLO…"""
+        n = 0
+        for ev in events:
+            ts = parse_ts(str(ev.get("ts") or ev.get("observed_at") or ""))
+            if ts is None:
+                continue
+            self._events.append(HistoryEvent(
+                kind=kind, ts=ts,
+                subject=str(ev.get("subject") or ev.get("resource") or ""),
+                outcome=str(ev.get("outcome") or ev.get("type") or ""),
+                source=source,
+                source_ref=str(ev.get("event_id") or ev.get("hash") or ""),
+                attrs=ev))
+            n += 1
+        return n
+
+    # -- queries ----------------------------------------------------
+    def events(self, window: str = "30d", *,
+               kind: str | None = None, subject: str | None = None,
+               now: datetime | None = None,
+               since: datetime | None = None,
+               until: datetime | None = None) -> list[HistoryEvent]:
+        """§39/§299 — strict window filtering."""
+        now = now or datetime.now(timezone.utc)
+        if since is None:
+            since = now - WINDOWS.get(window, WINDOWS["30d"])
+        until = until or now
+        return [e for e in self._events
+                if since <= e.ts <= until
+                and (kind is None or e.kind == kind)
+                and (subject is None or e.subject == subject)]
+
+    def count_by(self, window: str = "30d", key: str = "kind",
+                 **kw) -> dict[str, int]:
+        out: dict[str, int] = {}
+        for e in self.events(window, **kw):
+            k = getattr(e, key, "") or str(e.attrs.get(key, ""))
+            out[k] = out.get(k, 0) + 1
+        return out
+
+    # -- patterns (§42–44) ------------------------------------------
+    def patterns(self, window: str = "90d", *,
+                 group: str = "subject",
+                 min_support: int = 2) -> list[HistoricalPattern]:
+        """Group (subject, kind, outcome) triples; report support."""
+        groups: dict[tuple, list[HistoryEvent]] = {}
+        for e in self.events(window):
+            k = (getattr(e, group, e.subject), e.kind, e.outcome)
+            groups.setdefault(k, []).append(e)
+        out = []
+        for (subj, kind, outcome), evs in sorted(groups.items()):
+            if len(evs) < min_support:
+                continue
+            evs.sort(key=lambda e: e.ts)
+            out.append(HistoricalPattern(
+                pattern_id=f"{kind}:{subj}:{outcome}",
+                window=window, events=[e.source_ref or e.kind
+                                       for e in evs],
+                support=len(evs), sample_size=len(evs),
+                confidence=confidence_for_support(len(evs)),
+                evidence=[e.source_ref for e in evs if e.source_ref],
+                scope={"subject": subj},
+                hypothesis="",
+                limitations=["correlation is not causality",
+                             "deterministic count only"]))
+        return out
+
+    def before(self, event_kind: str, within: str = "24h",
+               window: str = "90d") -> list[HistoricalPattern]:
+        """§40 — 'what repeatedly changed before incidents?': for each
+        `event_kind` occurrence, count preceding event kinds within
+        `within`. Support count only — never a causal claim (§41)."""
+        incidents = self.events(window, kind=event_kind)
+        delta = WINDOWS.get(within, WINDOWS["24h"])
+        counts: dict[str, int] = {}
+        for inc in incidents:
+            for e in self._events:
+                if e is inc:
+                    continue
+                if inc.ts - delta <= e.ts < inc.ts:
+                    counts[e.kind] = counts.get(e.kind, 0) + 1
+        return [HistoricalPattern(
+            pattern_id=f"precedes:{k}->{event_kind}",
+            window=window, support=n, sample_size=n,
+            confidence=confidence_for_support(n),
+            scope={"preceding_kind": k, "following": event_kind},
+            events=[k], evidence=[],
+            hypothesis=f"{k} precedes {event_kind} "
+                       f"{n}x in {within}",
+            limitations=["temporal proximity is not causality",
+                         "sample size limits confidence"])
+            for k, n in sorted(counts.items(), key=lambda kv: -kv[1])]
+
+    # -- operation/runbook stats (§46–48) ---------------------------
+    def operation_stats(self, window: str = "90d") -> dict[str, Any]:
+        ops = self.events(window, kind="operation")
+        rbs = self.events(window, kind="rollback")
+        out: dict[str, Any] = {"operations": len(ops),
+                               "rollbacks": len(rbs)}
+        by_action: dict[str, dict[str, int]] = {}
+        for e in ops:
+            action = str(e.attrs.get("action") or
+                         e.attrs.get("step_id") or "unknown")
+            d = by_action.setdefault(action, {"count": 0, "failed": 0})
+            d["count"] += 1
+            if "fail" in e.outcome:
+                d["failed"] += 1
+        out["by_action"] = by_action
+        out["sample_size"] = len(ops)
+        out["confidence"] = confidence_for_support(len(ops))
+        return out
+
+    def runbook_effectiveness(self, window: str = "90d"
+                              ) -> dict[str, dict[str, Any]]:
+        """§47–48 — decomposed: success/coverage/evidence/freshness/
+        rollback rate — never an opaque score."""
+        out: dict[str, dict[str, Any]] = {}
+        for e in self.events(window, kind="operation"):
+            rb = str(e.attrs.get("runbook") or e.attrs.get("runbook_id")
+                     or "")
+            if not rb:
+                continue
+            d = out.setdefault(rb, {"selected": 0, "converged": 0,
+                                    "failed": 0, "rolled_back": 0,
+                                    "manual_intervention": 0})
+            d["selected"] += 1
+            if e.outcome in ("converged", "step.completed"):
+                d["converged"] += 1
+            elif "fail" in e.outcome:
+                d["failed"] += 1
+        for e in self.events(window, kind="rollback"):
+            rb = str(e.attrs.get("runbook") or "")
+            if rb in out:
+                out[rb]["rolled_back"] += 1
+        for rb, d in out.items():
+            sel = d["selected"] or 1
+            d["success_rate"] = round(d["converged"] / sel, 3)
+            d["rollback_rate"] = round(d["rolled_back"] / sel, 3)
+            d["sample_size"] = d["selected"]
+            d["confidence"] = confidence_for_support(d["selected"])
+        return out
+
+
+def engine_from_events(events: list[dict[str, Any]], kind: str,
+                       source: str = "fixture") -> HistoryEngine:
+    """Test/lab helper."""
+    eng = HistoryEngine()
+    eng.ingest_events(kind, events, source)
+    return eng

platformforge/analytics/measurement.py

@@ -0,0 +1,149 @@
+"""Cycle 5 Phase D — platform measurement (§58–71, §252–256).
+
+Diagnostic, never a marketing score (§66, §253). Every dimension shows
+observed/declared evidence + gaps + confidence (§67); `unknown` stays
+visible (§255); no single collapsed number (§253).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from platformforge.analytics.models import AnalyticsDataQuality, PlatformMetric
+
+MATURITY_DIMENSIONS = ("investment", "adoption", "interfaces",
+                       "operations", "measurement")
+VALUE_DIMENSIONS = ("adoption", "self-service", "reliability",
+                    "delivery", "cost-efficiency", "security",
+                    "operational-toil", "developer-experience",
+                    "standardization", "policy-compliance")
+SCORECARD_LEVELS = ("strong", "moderate", "partial", "at-risk",
+                    "unknown")
+
+
+@dataclass
+class MaturityDimension:
+    """§67 — one diagnostic axis."""
+    name: str
+    level: str = "unknown"             # initial|managed|defined|measured|optimizing
+    observed_evidence: list[str] = field(default_factory=list)
+    declared_evidence: list[str] = field(default_factory=list)
+    gaps: list[str] = field(default_factory=list)
+    confidence: str = "low"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"name": self.name, "level": self.level,
+                "observed_evidence": self.observed_evidence,
+                "declared_evidence": self.declared_evidence,
+                "gaps": self.gaps, "confidence": self.confidence}
+
+
+def maturity_assessment(signals: dict[str, dict[str, Any]],
+                        dq: AnalyticsDataQuality | None = None
+                        ) -> dict[str, Any]:
+    """§65–67 — maturity V3. `signals`: per-dimension dicts of observed
+    facts (each signal lists the capability IDs it observed). Missing
+    dimensions report `unknown`, never zero."""
+    cap = (dq or AnalyticsDataQuality(sample_size=3,
+                                     coverage=1.0,
+                                     completeness=1.0)).confidence_cap
+    dims = []
+    for name in MATURITY_DIMENSIONS:
+        sig = signals.get(name)
+        if not sig:
+            dims.append(MaturityDimension(
+                name=name, gaps=[f"no {name} evidence collected"]))
+            continue
+        obs = sig.get("observed", [])
+        dec = sig.get("declared", [])
+        score = len(obs) + len(dec)
+        level = ("optimizing" if score >= 8 else
+                 "measured" if score >= 5 else
+                 "defined" if score >= 3 else
+                 "managed" if score >= 1 else "initial")
+        dims.append(MaturityDimension(
+            name=name, level=level, observed_evidence=list(obs),
+            declared_evidence=list(dec),
+            gaps=list(sig.get("gaps", [])),
+            confidence=cap if score >= 3 else "low"))
+    return {"schema": "platformforge/maturity/v3",
+            "dimensions": [d.to_dict() for d in dims],
+            "unknown_dimensions": [d.name for d in dims
+                                   if d.level == "unknown"],
+            "note": "diagnostic dimensions — not a marketing score"}
+
+
+def self_service_ratio(successful: int | None,
+                       eligible: int | None) -> PlatformMetric:
+    """§68 — only when the denominator is observable."""
+    m = PlatformMetric(metric_id="platform.self-service-ratio",
+                       dimension="self-service",
+                       scope={"level": "platform"},
+                       unit="ratio", source="golden_path_requests")
+    if not eligible:
+        m.value = None                # §64 — unknown, not zero
+        m.confidence = "low"
+        m.evidence = ["denominator not observable"]
+        return m
+    m.value = round((successful or 0) / eligible, 3)
+    m.completeness = 1.0
+    m.confidence = "medium" if eligible >= 10 else "low"
+    return m
+
+
+def toil_metrics(events: list[dict[str, Any]]) -> list[PlatformMetric]:
+    """§69 — platform-team toil: manual interventions, owner approvals,
+    failed self-service, repeated incidents."""
+    def _m(mid, val, ev):
+        return PlatformMetric(metric_id=mid, dimension="operational-toil",
+                              scope={"level": "platform"}, value=val,
+                              unit="count", source="history",
+                              evidence=ev,
+                              confidence="medium" if val else "low")
+    manual = [e for e in events if e.get("type") == "manual-intervention"]
+    approvals = [e for e in events
+                 if e.get("type") == "approval-required"]
+    failed_ss = [e for e in events
+                 if e.get("type") == "self-service-failed"]
+    return [_m("platform.toil.manual-interventions", len(manual),
+               [str(e.get("ref", "")) for e in manual[:20]]),
+            _m("platform.toil.owner-approvals", len(approvals),
+               [str(e.get("ref", "")) for e in approvals[:20]]),
+            _m("platform.toil.failed-self-service", len(failed_ss),
+               [str(e.get("ref", "")) for e in failed_ss[:20]])]
+
+
+def time_to_provision(requests: list[dict[str, Any]]) -> PlatformMetric:
+    """§70 — median request→ready when both timestamps exist."""
+    deltas = []
+    for r in requests:
+        req, ready = r.get("requested_at"), r.get("ready_at")
+        if req and ready:
+            from platformforge.live.models import parse_ts
+            a, b = parse_ts(req), parse_ts(ready)
+            if a and b:
+                deltas.append((b - a).total_seconds())
+    m = PlatformMetric(metric_id="platform.time-to-provision",
+                       dimension="delivery", scope={"level": "platform"},
+                       unit="seconds", source="golden_path_requests")
+    if not deltas:
+        m.value = None
+        m.confidence = "low"
+        return m
+    deltas.sort()
+    m.value = deltas[len(deltas) // 2]
+    m.completeness = len(deltas) / max(len(requests), 1)
+    m.confidence = "medium" if len(deltas) >= 5 else "low"
+    return m
+
+
+def scorecard(dimensions: dict[str, str]) -> dict[str, Any]:
+    """§252–255 — decomposed dashboard; unknown stays unknown."""
+    out = {k: (v if v in SCORECARD_LEVELS else "unknown")
+           for k, v in dimensions.items()}
+    return {"schema": "platformforge/scorecard/v1",
+            "dimensions": out,
+            "unknown": [k for k, v in out.items() if v == "unknown"],
+            "collapsed_score": None,
+            "note": "no single number — read the dimensions"}

platformforge/analytics/models.py

@@ -0,0 +1,127 @@
+"""Cycle 5 Phase A — analytics contracts (§42–43, §61–63, §243–244,
+§249–250).
+
+Invariants:
+- `PlatformMetric`: `value` may be absent → reported as `unknown`,
+  never coerced to zero (§64, §304);
+- every metric carries source + evidence + confidence + completeness
+  (§62–63);
+- `AnalysisReceipt` makes every aggregate reproducible: same inputs →
+  same hash (§243–244);
+- `AnalyticsDataQuality` gates confidence — low quality lowers every
+  recommendation (§249–251);
+- `HistoricalPattern` reports support counts, never causal claims
+  (§41–44).
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from platformforge.live.models import canonical_hash
+
+METRIC_SCHEMA = "platformforge/metric/v1"
+RECEIPT_SCHEMA = "platformforge/analysis-receipt/v1"
+PATTERN_SCHEMA = "platformforge/historical-pattern/v1"
+DQ_SCHEMA = "platformforge/analytics-data-quality/v1"
+
+CONFIDENCE_LEVELS = ("low", "medium", "high")
+
+
+@dataclass
+class PlatformMetric:
+    """§61–63 — one measured value with full provenance."""
+    metric_id: str
+    dimension: str                    # adoption|reliability|cost|...
+    scope: dict[str, str]             # fleet/org/env/team/cluster/…
+    value: float | int | str | None = None
+    unit: str = ""
+    window: str = ""                  # 24h|7d|30d|90d|custom range
+    source: str = ""                  # store/ledger/collector id
+    evidence: list[str] = field(default_factory=list)
+    confidence: str = "low"
+    completeness: float | None = None  # 0..1; None when unknown
+
+    def to_dict(self) -> dict[str, Any]:
+        d = {"schema": METRIC_SCHEMA, **asdict(self)}
+        if self.value is None:
+            d["value"] = "unknown"    # §64 — never a fake zero
+        return d
+
+
+@dataclass
+class AnalyticsDataQuality:
+    """§249–251 — data quality gates analytic confidence."""
+    coverage: float | None = None
+    freshness: str = "unknown"
+    completeness: float | None = None
+    consistency: str = "unknown"
+    sample_size: int = 0
+
+    @property
+    def confidence_cap(self) -> str:
+        """§251 — low data quality caps recommendation confidence."""
+        if self.sample_size < 3:
+            return "low"
+        cov = self.coverage if self.coverage is not None else 0.0
+        comp = self.completeness if self.completeness is not None else 0.0
+        if self.freshness in ("stale", "expired") or cov < 0.8 or comp < 0.8:
+            return "low"
+        if cov < 1.0 or comp < 1.0 or self.sample_size < 10:
+            return "medium"
+        return "high"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": DQ_SCHEMA, **asdict(self),
+                "confidence_cap": self.confidence_cap}
+
+
+@dataclass
+class AnalysisReceipt:
+    """§243 — reproducible aggregate receipt."""
+    analysis: str
+    scope: dict[str, str]
+    window: str = ""
+    inputs: list[str] = field(default_factory=list)   # source ids/hashes
+    coverage: dict[str, Any] = field(default_factory=dict)
+    algorithm: str = ""
+    results: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        body = {"schema": RECEIPT_SCHEMA, "analysis": self.analysis,
+                "scope": self.scope, "window": self.window,
+                "inputs": self.inputs, "coverage": self.coverage,
+                "algorithm": self.algorithm, "results": self.results}
+        body["hash"] = "sha256:" + canonical_hash(body)
+        return body
+
+
+@dataclass
+class HistoricalPattern:
+    """§42–44 — recurring pattern with honest support/confidence.
+    `hypothesis` names the *possible* explanation; `limitations` keeps
+    correlation ≠ causality visible (§41)."""
+    pattern_id: str
+    window: str
+    events: list[str] = field(default_factory=list)
+    support: int = 0
+    confidence: str = "low"
+    evidence: list[str] = field(default_factory=list)
+    scope: dict[str, str] = field(default_factory=dict)
+    hypothesis: str = ""
+    limitations: list[str] = field(default_factory=list)
+    sample_size: int = 0              # §233 — recorded, not hidden
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": PATTERN_SCHEMA, **asdict(self),
+                "causal_claim": False}
+
+
+def confidence_for_support(n: int) -> str:
+    """§232 — 2 occurrences ≠ 200 occurrences."""
+    if n < 3:
+        return "low"
+    if n < 10:
+        return "medium"
+    return "high"