platformforge 0.1.0__py3-none-any.whl

platformforge/live/incident.py

@@ -0,0 +1,200 @@
+"""Incident intelligence V3 (cycle §160–§176).
+
+Canonical timeline joins: git change, CI build, artifact, deployment,
+CloudTrail change, k8s event, runtime anomaly, alert, incident — every
+event normalized to {timestamp, source, scope, resources, actor, facts,
+confidence, kind}.
+
+Candidate scoring is deterministic and factorized — every hypothesis
+explains WHERE its rank came from (§170). Status vocabulary is closed:
+confirmed needs causal evidence — correlation alone is never enough;
+`root_cause: unresolved` is a valid, honest outcome (§174).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.live.models import parse_ts
+
+EVENT_SOURCES = ("git_change", "ci_build", "artifact", "deployment",
+                 "cloudtrail", "k8s_event", "runtime_anomaly", "alert",
+                 "incident", "manual")
+
+# §170 — fixed factor weights; every candidate's score is reproducible
+# and explainable from this table.
+WEIGHTS = {"temporal": 0.25, "graph_distance": 0.15,
+           "blast_radius": 0.10, "scope_overlap": 0.10,
+           "change_type": 0.10, "freshness": 0.10,
+           "evidence_tier": 0.10, "runtime_correlation": 0.10}
+
+MUTATING_ACTION_HINTS = ("create", "update", "put", "delete", "apply",
+                         "deploy", "scale", "patch", "modify",
+                         "attach", "detach")
+
+HYPOTHESIS_STATUSES = ("confirmed", "supported", "candidate",
+                       "contradicted", "unknown")
+
+
+def _ts(e: dict[str, Any]) -> float:
+    v = e.get("timestamp") or e.get("at") or e.get("ts") or ""
+    t = parse_ts(str(v))
+    return t.timestamp() if t else float(v) if str(v).replace(
+        ".", "", 1).isdigit() else 0.0
+
+
+def normalize_event(raw: dict[str, Any]) -> dict[str, Any]:
+    """Any event source → canonical timeline event; scoring-relevant
+    extras (blast_radius, runtime_correlated, …) pass through."""
+    e = dict(raw)
+    e.update({
+        "timestamp": raw.get("timestamp") or raw.get("at") or "",
+        "at": _ts(raw),
+        "kind": raw.get("kind") or raw.get("source") or "event",
+        "source": raw.get("source", "unknown"),
+        "scope": raw.get("scope") or {
+            k: raw.get(k) for k in ("cluster", "namespace", "account",
+                                    "region") if raw.get(k)},
+        "resources": raw.get("resources") or raw.get("resource_ids") or
+        ([raw.get("target")] if raw.get("target") else []),
+        "actor": raw.get("actor") or raw.get("user") or "",
+        "facts": raw.get("facts") or raw.get("fact_ids") or [],
+        "confidence": float(raw.get("confidence", 0.8)),
+        "summary": raw.get("summary") or raw.get("action")
+        or raw.get("message") or "",
+        "tier": raw.get("tier"), "freshness": raw.get("freshness", ""),
+        "causal": bool(raw.get("causal"))})
+    return e
+
+
+def build_timeline(events: list[dict[str, Any]]) -> dict[str, Any]:
+    norm = sorted((normalize_event(e) for e in events),
+                  key=lambda e: (e["at"], e["kind"]))
+    by_source: dict[str, int] = {}
+    for e in norm:
+        by_source[e["kind"]] = by_source.get(e["kind"], 0) + 1
+    return {"timeline": norm, "counts": {"events": len(norm),
+                                          **by_source}}
+
+
+def _factor_scores(candidate: dict[str, Any], incident_at: float,
+                   incident_resources: set[str],
+                   window_s: float, graph=None) -> dict[str, float]:
+    dt = incident_at - _ts(candidate)
+    temporal = max(0.0, 1 - abs(dt) / window_s) if dt >= 0 else 0.0
+    c_res = set(candidate.get("resources") or
+                candidate.get("resource_ids") or [])
+    overlap = len(incident_resources & c_res) / \
+        max(1, len(incident_resources | c_res)) \
+        if incident_resources or c_res else 0.0
+    action = str(candidate.get("action") or candidate.get("kind") or "")
+    change_type = 1.0 if any(h in action.lower()
+                             for h in MUTATING_ACTION_HINTS) else 0.3
+    fresh = {"fresh": 1.0, "aging": 0.6, "stale": 0.3,
+             "expired": 0.1}.get(candidate.get("freshness", ""), 0.5)
+    tier = candidate.get("tier")
+    tier_score = {0: 1.0, 1: 0.9, 2: 0.7, 3: 0.5,
+                  4: 0.4, 5: 0.3}.get(tier, 0.5)
+    gd = 0.0
+    if graph is not None and incident_resources and c_res:
+        from platformforge.graph.query import blast_radius
+        for r in c_res:
+            if r in incident_resources:
+                gd = 1.0
+                break
+            try:
+                br = blast_radius(graph, r)["nodes"]
+            except (KeyError, TypeError, ValueError):
+                br = {}
+            for ir in incident_resources:
+                if ir in br:
+                    gd = max(gd, max(0.0, 1 - 0.2 * br[ir]["depth"]))
+    blast = min(1.0, float(candidate.get("blast_radius", 0.0)))
+    runtime = 1.0 if candidate.get("runtime_correlated") else 0.0
+    return {"temporal": round(temporal, 3), "graph_distance": round(gd, 3),
+            "blast_radius": blast, "scope_overlap": round(overlap, 3),
+            "change_type": change_type, "freshness": fresh,
+            "evidence_tier": tier_score, "runtime_correlation": runtime}
+
+
+def score_candidates(incident: dict[str, Any],
+                     candidates: list[dict[str, Any]],
+                     *, window_s: float = 3600,
+                     graph=None) -> dict[str, Any]:
+    """Deterministic ranked hypotheses with per-factor explanation."""
+    incident_at = _ts(incident)
+    res = set(incident.get("resources") or
+              incident.get("resource_ids") or [])
+    ranked = []
+    for c in candidates:
+        c = normalize_event(c) if "timestamp" in c or "at" in c else c
+        factors = _factor_scores(c, incident_at, res, window_s, graph)
+        score = round(sum(WEIGHTS[k] * factors[k] for k in WEIGHTS), 3)
+        dt = incident_at - _ts(c)
+        if c.get("contradicted") or dt < 0:
+            status = "contradicted"   # change after incident ≠ cause
+        elif c.get("causal") and c.get("facts"):
+            status = "confirmed"      # causal evidence present
+        elif score >= 0.65:
+            status = "supported"
+        elif score >= 0.3:
+            status = "candidate"
+        else:
+            status = "unknown"
+        ranked.append({"candidate": c.get("summary") or
+                       c.get("action") or c.get("kind", "?"),
+                       "resources": sorted(c.get("resources") or
+                                           c.get("resource_ids") or []),
+                       "actor": c.get("actor", ""),
+                       "timestamp": c.get("timestamp") or c.get("at"),
+                       "score": score, "status": status,
+                       "explain": {"factors": factors,
+                                   "weights": WEIGHTS,
+                                   "dt_seconds": round(dt, 1)}})
+    ranked.sort(key=lambda r: (-r["score"], r["candidate"]))
+    for i, r in enumerate(ranked):
+        r["rank"] = i + 1
+    return {"ranked": ranked,
+            "statuses": {s: sum(1 for r in ranked if r["status"] == s)
+                         for s in HYPOTHESIS_STATUSES},
+            "note": "correlation ≠ causation — 'confirmed' requires "
+                    "causal evidence, rank explains score only"}
+
+
+def postmortem_v3(incident: dict[str, Any],
+                  timeline: dict[str, Any],
+                  ranked: dict[str, Any]) -> dict[str, Any]:
+    """§174 — evidence-only postmortem draft. Root cause stays
+    `unresolved` unless a confirmed hypothesis exists (causal evidence,
+    not correlation)."""
+    hyps = ranked.get("ranked", [])
+    confirmed = [h for h in hyps if h["status"] == "confirmed"]
+    supported = [h for h in hyps if h["status"] == "supported"]
+    root = ({"status": "confirmed-candidate",
+             "evidence": confirmed[0],
+             "note": "causal evidence present — still requires human "
+                     "sign-off"} if len(confirmed) == 1 else
+            {"status": "unresolved",
+             "reason": ("multiple confirmed candidates" if confirmed else
+                        "no causal evidence — correlation only")})
+    unknowns = [h["candidate"] for h in hyps if h["status"] == "unknown"]
+    return {"postmortem": {
+        "title": incident.get("title", "incident"),
+        "incident_id": incident.get("incident_id", ""),
+        "status": "draft",
+        "timeline": timeline.get("timeline", []),
+        "impact": incident.get("impact", {}),
+        "observed_changes": confirmed + supported,
+        "runtime_signals": [e for e in timeline.get("timeline", [])
+                            if e["kind"] in ("runtime_anomaly",
+                                             "alert")],
+        "candidate_causes": hyps,
+        "root_cause": root,
+        "unknowns": unknowns,
+        "follow_ups": [
+            "confirm or reject top hypothesis with independent evidence",
+            ("verify declared state vs observed drift for affected "
+             "resources"),
+            "add regression coverage for the failing invariant"],
+        "note": "draft generated from evidence only — 'unresolved' is "
+                "a true state, not a template gap"}}

platformforge/live/models.py

@@ -0,0 +1,435 @@
+"""Cycle 3 — observation model. Canonical contracts for live evidence.
+
+The load-bearing invariant: **OBSERVED ≠ COMPLETE**. Every observation
+carries explicit scope + coverage + freshness so absence is only a
+verdict when it was actually *seen to be absent* under a complete, fresh,
+covering observation (ADR-0013/0014).
+
+Runtime is not a provenance (cycle §4): `source_type=runtime` +
+`tier=T0` on extracted facts keeps the distinction without inventing a
+new provenance value.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+SCHEMA = "platformforge/observation/v1"
+RECEIPT_SCHEMA = "platformforge/collector-receipt/v1"
+CHANGE_EVENT_SCHEMA = "platformforge/change-event/v1"
+DRIFT_EVENT_SCHEMA = "platformforge/drift-event/v1"
+
+SOURCE_TYPES = ("observed", "runtime")
+COVERAGE_STATUSES = ("complete", "partial", "sampled", "truncated",
+                     "permission-limited", "unsupported", "unknown")
+FRESHNESS_STATUSES = ("fresh", "aging", "stale", "expired", "unknown")
+LIFECYCLES = ("present", "deleting", "deleted", "unknown")
+BUDGET_OUTCOMES = ("complete", "reduced_scope", "sampled", "refused")
+
+# §9 — default per-source TTLs (seconds); configurable per domain/source,
+# never a hidden universal constant embedded in logic.
+DEFAULT_FRESH_TTL: dict[str, int] = {
+    "runtime": 120, "kubernetes": 300, "aws": 3600, "default": 900}
+
+_OBS_ID_RE = re.compile(r"^obs-[0-9a-f]{16}$")
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def parse_ts(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def iso(dt: datetime) -> str:
+    return dt.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def age_seconds(captured_at: str | None, at: datetime | None = None) -> float | None:
+    ts = parse_ts(captured_at)
+    if ts is None:
+        return None
+    return ((at or datetime.now(timezone.utc)) - ts).total_seconds()
+
+
+def canonical_hash(obj: Any) -> str:
+    return hashlib.sha256(json.dumps(
+        obj, sort_keys=True, separators=(",", ":"), default=str
+    ).encode()).hexdigest()
+
+
+@dataclass
+class ObservationScope:
+    """§7 — WHAT WAS OBSERVED? Explicit, declarative, comparable."""
+    provider: str = ""
+    accounts: list[str] = field(default_factory=list)
+    regions: list[str] = field(default_factory=list)
+    services: list[str] = field(default_factory=list)
+    resource_types: list[str] = field(default_factory=list)
+    namespaces: list[str] = field(default_factory=list)
+    clusters: list[str] = field(default_factory=list)
+    selectors: dict[str, Any] = field(default_factory=dict)
+    exclusions: list[str] = field(default_factory=list)
+
+    def covers(self, target: dict[str, Any]) -> tuple[bool, str]:
+        """Is `target` inside this scope? Conservative: an unset axis
+        means 'all' only if the axis was declared unbounded; otherwise
+        exclusion/omission wins (honest gaps)."""
+        checks = []
+        if self.accounts:
+            checks.append((target.get("account") in self.accounts,
+                           f"account {target.get('account')} not in scope"))
+        if self.regions:
+            checks.append((target.get("region") in self.regions,
+                           f"region {target.get('region')} not in scope"))
+        if self.namespaces:
+            checks.append((target.get("namespace") in self.namespaces,
+                           f"namespace {target.get('namespace')} not in scope"))
+        if self.clusters:
+            checks.append((target.get("cluster") in self.clusters,
+                           f"cluster {target.get('cluster')} not in scope"))
+        if self.resource_types:
+            checks.append((target.get("resource_type") in self.resource_types,
+                           f"type {target.get('resource_type')} not in scope"))
+        excl = target.get("resource_id") or target.get("name") or ""
+        if excl and excl in self.exclusions:
+            checks.append((False, f"{excl} explicitly excluded"))
+        for ok, why in checks:
+            if not ok:
+                return False, why
+        return True, "in scope"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {k: v for k, v in asdict(self).items() if v not in ([], {}, "")}
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any] | None) -> ObservationScope:
+        return cls(**{k: v for k, v in (d or {}).items() if k in cls.__dataclass_fields__})
+
+
+@dataclass
+class Coverage:
+    """§8 — coverage is per-resource-type, never one global claim."""
+    status: str = "unknown"
+    per_resource_type: dict[str, str] = field(default_factory=dict)
+    reasons: list[str] = field(default_factory=list)
+
+    def __post_init__(self):
+        if self.status not in COVERAGE_STATUSES:
+            raise ValueError(f"invalid coverage status: {self.status}")
+        for rt, st in self.per_resource_type.items():
+            if st not in COVERAGE_STATUSES:
+                raise ValueError(f"invalid coverage for {rt}: {st}")
+
+    def for_type(self, resource_type: str) -> str:
+        return self.per_resource_type.get(resource_type, self.status)
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"status": self.status}
+        if self.per_resource_type:
+            d["per_resource_type"] = dict(sorted(self.per_resource_type.items()))
+        if self.reasons:
+            d["reasons"] = self.reasons
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any] | None) -> Coverage:
+        d = d or {}
+        return cls(status=d.get("status", "unknown"),
+                   per_resource_type=dict(d.get("per_resource_type", {})),
+                   reasons=list(d.get("reasons", [])))
+
+
+@dataclass
+class Freshness:
+    """§9 — captured_at + fresh_until → status at a point in time."""
+    captured_at: str = ""
+    fresh_until: str = ""
+    status: str = "unknown"
+
+    def status_at(self, at: datetime | None = None,
+                  ttl: int | None = None) -> str:
+        at = at or datetime.now(timezone.utc)
+        cap = parse_ts(self.captured_at)
+        if cap is None:
+            return "unknown"
+        until = parse_ts(self.fresh_until)
+        if until is None and ttl:
+            from datetime import timedelta
+            until = cap + timedelta(seconds=ttl)
+        age = (at - cap).total_seconds()
+        if until is None:
+            return "unknown"
+        if at > until:
+            span = (until - cap).total_seconds() or 1.0
+            return "expired" if age > span * 2 else "stale"
+        return "fresh" if age < 0.6 * (until - cap).total_seconds() else "aging"
+
+    def to_dict(self) -> dict[str, Any]:
+        d = {"captured_at": self.captured_at, "status": self.status}
+        if self.fresh_until:
+            d["fresh_until"] = self.fresh_until
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any] | None) -> Freshness:
+        d = d or {}
+        return cls(captured_at=d.get("captured_at", ""),
+                   fresh_until=d.get("fresh_until", ""),
+                   status=d.get("status", "unknown"))
+
+
+@dataclass
+class ObservedObject:
+    """One provider-observed object inside an envelope."""
+    resource_id: str                    # provider-native (arn/uid/path)
+    resource_type: str                  # normalized kind (k8s:Deployment…)
+    attributes: dict[str, Any] = field(default_factory=dict)  # redacted!
+    provider: str = ""
+    account: str = ""
+    region: str = ""
+    cluster: str = ""
+    namespace: str = ""
+    name: str = ""
+    uid: str = ""
+    lifecycle: str = "present"          # present|deleting|deleted|unknown
+    deletion_evidence: str = ""         # strong evidence type if deleted
+    content_hash: str = ""              # canonical normalized fingerprint
+    observed_at: str = ""
+    artifact: str = ""                  # artifact://sha256/… for raw doc
+
+    def __post_init__(self):
+        if self.lifecycle not in LIFECYCLES:
+            raise ValueError(f"invalid lifecycle: {self.lifecycle}")
+        if self.lifecycle == "deleted" and not self.deletion_evidence:
+            raise ValueError(
+                "lifecycle=deleted requires deletion_evidence "
+                "(ADR-0013: missing-from-snapshot is not proof)")
+
+    def fingerprint(self) -> str:
+        """§144 — canonical normalized hash for delta ingestion."""
+        return self.content_hash or canonical_hash({
+            "id": self.resource_id, "type": self.resource_type,
+            "attrs": self.attributes})
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        if not self.content_hash:
+            d["content_hash"] = self.fingerprint()
+        return {k: v for k, v in d.items() if v not in ("", {}, [])}
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> ObservedObject:
+        return cls(**{k: v for k, v in d.items() if k in cls.__dataclass_fields__})
+
+
+@dataclass
+class CollectorReceipt:
+    """§18 — every collection emits an auditable receipt."""
+    collector: str
+    collector_version: str
+    provider: str
+    started_at: str
+    completed_at: str = ""
+    scope: dict[str, Any] = field(default_factory=dict)
+    api_calls: int = 0
+    pages: int = 0
+    objects: int = 0
+    bytes: int = 0
+    throttles: int = 0
+    retries: int = 0
+    cache_hits: int = 0
+    errors: list[str] = field(default_factory=list)
+    permission_denied: list[dict[str, Any]] = field(default_factory=list)
+    unsupported: list[str] = field(default_factory=list)
+    cursor: str = ""
+    metadata_only: bool = True
+    fallback: str = ""
+    coverage: dict[str, Any] = field(default_factory=dict)
+    freshness: dict[str, Any] = field(default_factory=dict)
+    budget_outcome: str = "complete"
+    duration_s: float = 0.0
+
+    def __post_init__(self):
+        if self.budget_outcome not in BUDGET_OUTCOMES:
+            raise ValueError(f"invalid budget outcome: {self.budget_outcome}")
+
+    def to_dict(self) -> dict[str, Any]:
+        d = {"schema": RECEIPT_SCHEMA, **asdict(self)}
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> CollectorReceipt:
+        return cls(**{k: v for k, v in d.items()
+                      if k in cls.__dataclass_fields__})
+
+
+@dataclass
+class ObservationEnvelope:
+    """§6 — canonical live-observation artifact (observation/v1)."""
+    observation_id: str
+    collector: str
+    collector_version: str
+    provider: str
+    source_type: str                          # observed | runtime
+    captured_at: str
+    completed_at: str = ""
+    fresh_until: str = ""
+    scope: dict[str, Any] = field(default_factory=dict)
+    coverage: dict[str, Any] = field(default_factory=lambda: {"status": "unknown"})
+    pagination: dict[str, Any] = field(default_factory=dict)
+    permissions: dict[str, Any] = field(default_factory=dict)
+    errors: list[str] = field(default_factory=list)
+    objects: list[dict[str, Any]] = field(default_factory=list)
+    bytes: int = 0
+    hashes: dict[str, Any] = field(default_factory=dict)
+    receipt: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        if self.source_type not in SOURCE_TYPES:
+            raise ValueError(f"invalid source_type: {self.source_type}")
+        if not _OBS_ID_RE.match(self.observation_id):
+            raise ValueError(f"invalid observation_id: {self.observation_id}")
+
+    @classmethod
+    def new(cls, collector: str, version: str, provider: str,
+            source_type: str, scope: ObservationScope | dict | None = None,
+            captured_at: str | None = None, **kw) -> ObservationEnvelope:
+        sc = (scope.to_dict() if isinstance(scope, ObservationScope)
+              else (scope or {}))
+        obs_id = "obs-" + canonical_hash(
+            {"collector": collector, "provider": provider,
+             "captured_at": captured_at or "", "scope": sc})[:16]
+        return cls(observation_id=obs_id, collector=collector,
+                   collector_version=version, provider=provider,
+                   source_type=source_type,
+                   captured_at=captured_at or now_iso(), scope=sc, **kw)
+
+    def coverage_status(self, resource_type: str = "") -> str:
+        cov = Coverage.from_dict(self.coverage)
+        return cov.for_type(resource_type) if resource_type else cov.status
+
+    def freshness_status_at(self, at: datetime | None = None) -> str:
+        f = Freshness.from_dict({"captured_at": self.captured_at,
+                                 "fresh_until": self.fresh_until})
+        return f.status_at(at, ttl=DEFAULT_FRESH_TTL.get(
+            self.provider, DEFAULT_FRESH_TTL["default"]))
+
+    def can_conclude_absent(self, target: dict[str, Any],
+                            at: datetime | None = None) -> tuple[bool, str]:
+        """§10 — absence is only provable when scope covers the target
+        AND coverage is complete for its type AND the snapshot is fresh.
+        Everything else → unresolved."""
+        in_scope, why = ObservationScope.from_dict(self.scope).covers(target)
+        if not in_scope:
+            return False, f"scope does not cover target: {why}"
+        cov = self.coverage_status(target.get("resource_type", ""))
+        if cov != "complete":
+            return False, f"coverage={cov} — absence unresolved"
+        fs = self.freshness_status_at(at)
+        if fs != "fresh":
+            return False, f"freshness={fs} — absence unresolved"
+        return True, "absence provable (scope+complete+fresh)"
+
+    def signature(self) -> str:
+        return self.hashes.get("envelope") or canonical_hash(
+            self.to_dict(include_hashes=False))
+
+    def to_dict(self, include_hashes: bool = True) -> dict[str, Any]:
+        d = {"schema": SCHEMA, "observation_id": self.observation_id,
+             "collector": self.collector,
+             "collector_version": self.collector_version,
+             "provider": self.provider, "source_type": self.source_type,
+             "captured_at": self.captured_at, "scope": self.scope,
+             "coverage": self.coverage, "objects": self.objects}
+        for k in ("completed_at", "fresh_until", "pagination",
+                  "permissions", "bytes", "receipt"):
+            v = getattr(self, k)
+            if v not in ("", {}, [], 0):
+                d[k] = v
+        if self.errors:
+            d["errors"] = self.errors
+        if include_hashes:
+            h = dict(self.hashes)
+            h.setdefault("envelope", canonical_hash(
+                {k: v for k, v in d.items() if k != "hashes"}))
+            d["hashes"] = h
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> ObservationEnvelope:
+        return cls(**{k: v for k, v in d.items()
+                      if k in cls.__dataclass_fields__})
+
+
+@dataclass
+class ChangeEvent:
+    """§78 — provider-observed change evidence (CloudTrail et al., T1)."""
+    event_id: str
+    timestamp: str
+    source: str                              # cloudtrail | k8s-event | …
+    action: str
+    actor: str = ""
+    resource_ids: list[str] = field(default_factory=list)
+    account: str = ""
+    region: str = ""
+    request: dict[str, Any] = field(default_factory=dict)   # redacted!
+    result: str = ""                                        # success|error
+    evidence: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": CHANGE_EVENT_SCHEMA,
+                **{k: v for k, v in asdict(self).items() if v not in ("", {}, [])}}
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> ChangeEvent:
+        return cls(**{k: v for k, v in d.items()
+                      if k in cls.__dataclass_fields__})
+
+
+@dataclass
+class DriftEvent:
+    """§113 — a classified change between two observations."""
+    drift_id: str
+    resource_id: str
+    drift_class: str                         # §102 set
+    before: dict[str, Any] = field(default_factory=dict)
+    after: dict[str, Any] = field(default_factory=dict)
+    facts: list[str] = field(default_factory=list)
+    change_event: str = ""                   # event_id if correlated
+    risk: str = ""
+    owner: str = ""
+    observed_at: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": DRIFT_EVENT_SCHEMA,
+                **{k: v for k, v in asdict(self).items() if v not in ("", {}, [])}}
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> DriftEvent:
+        return cls(**{k: v for k, v in d.items()
+                      if k in cls.__dataclass_fields__})
+
+
+# §102 — normative drift classes (closed set; validated, not free-text)
+DRIFT_CLASSES = (
+    "converged", "planned-not-applied", "observed-out-of-band",
+    "desired-missing-observed", "observed-orphan", "config-drift",
+    "identity-drift", "policy-drift", "security-drift", "network-drift",
+    "version-drift", "runtime-undeclared", "stale-observation",
+    "permission-unknown", "scope-mismatch", "uncomparable", "unknown")
+
+# §125 — declared vs runtime behavior classes
+BEHAVIOR_CLASSES = ("declared-and-observed", "observed-undeclared",
+                    "declared-not-seen-in-window", "unknown")