platformforge 0.1.0__py3-none-any.whl

platformforge/live/collectors/k8s.py

@@ -0,0 +1,389 @@
+"""Kubernetes live collector — read-only, metadata-first (cycle §22–§31).
+
+Design:
+- transport is injected: `transport(args) -> (rc, stdout, stderr)`. The
+  kubectl subprocess boundary lives in `k8s_transport.py`; tests inject
+  fakes — the collector core never touches the network.
+- metadata-first: full objects are fetched over the wire (kubectl has
+  no PartialObjectMetadata path), but the persisted envelope only keeps
+  the projected attribute subset — token economy at our side (§144).
+- pagination: `--chunk-size` + `--continue`, every page ledgered.
+- watch: resourceVersion cursors; 410 Gone/Expired → resnapshot, never
+  silent gap (§27–28); watch failures are evidence, not errors hidden.
+- coverage: per-resource-type; Forbidden → permission-limited +
+  denied_scopes, never a global failure (§8, §17).
+- read-only: only get/list/watch verbs; `required_rbac` emits a minimal
+  ClusterRole — never cluster-admin (§31).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import Any
+
+from platformforge.live.budget import ObservationBudget, ProviderCallLedger
+from platformforge.live.models import (
+    CollectorReceipt,
+    Coverage,
+    ObservationEnvelope,
+    ObservationScope,
+    ObservedObject,
+    iso,
+    now_iso,
+    parse_ts,
+)
+
+_SENSITIVE_ANNOTATION = re.compile(
+    r"(password|token|secret|private[-_.]?key|credential)", re.IGNORECASE)
+
+Transport = Callable[[list[str]], tuple[int, str, str]]
+
+COLLECTOR_VERSION = "k8s-collector/0.3.0"
+
+# §24 — default inventory set; extendable via scope.resource_types.
+# secrets: metadata-only (data stripped at projection), still useful
+# for drift/inventory without payload exposure.
+DEFAULT_RESOURCES = (
+    "deployments.apps", "statefulsets.apps", "daemonsets.apps",
+    "replicasets.apps", "pods", "services", "ingresses.networking.k8s.io",
+    "configmaps", "secrets", "serviceaccounts", "namespaces",
+    "persistentvolumeclaims", "jobs.batch", "cronjobs.batch",
+    "endpointslices.discovery.k8s.io", "networkpolicies.networking.k8s.io",
+    "roles.rbac.authorization.k8s.io", "rolebindings.rbac.authorization.k8s.io",
+    "clusterroles.rbac.authorization.k8s.io",
+    "clusterrolebindings.rbac.authorization.k8s.io")
+
+SENSITIVE_KINDS = {"Secret"}
+SECRET_DATA_KEYS = ("data", "stringData", "binaryData")
+
+WATCH_ACTION_RESNAPSHOT = "resnapshot"
+WATCH_ACTION_APPLY = "apply"
+
+
+def kind_of(api_version: str, kind: str) -> str:
+    """Normalized resource_type: `k8s:<group>/<Kind>` or `k8s:<Kind>`."""
+    group = api_version.split("/")[0] if "/" in api_version else ""
+    return f"k8s:{group}/{kind}" if group else f"k8s:{kind}"
+
+
+def canonical_id(cluster: str, namespace: str, kind: str, name: str,
+                 uid: str = "") -> str:
+    """§43 — strong identity prefers UID; namespaced, deterministic."""
+    base = f"k8s://{cluster or 'unknown'}/{namespace or '-'}/{kind}/{name}"
+    return f"{base}#{uid}" if uid else base
+
+
+def project_object(obj: dict[str, Any], *, cluster: str = "",
+                   observed_at: str = "") -> ObservedObject:
+    """Project a raw k8s object to an ObservedObject. Secret payloads are
+    blanked before they ever reach the envelope (§31, §207)."""
+    meta = obj.get("metadata", {}) or {}
+    api, kind = obj.get("apiVersion", ""), obj.get("kind", "")
+    ns, name = meta.get("namespace", ""), meta.get("name", "")
+    uid = meta.get("uid", "")
+    attrs: dict[str, Any] = {
+        "apiVersion": api, "kind": kind,
+        "resource_version": meta.get("resourceVersion", ""),
+        "generation": meta.get("generation"),
+        "labels": meta.get("labels", {}),
+        "annotations": {
+            k: v for k, v in (meta.get("annotations") or {}).items()
+            if not _SENSITIVE_ANNOTATION.search(k)},
+        "owner_refs": [
+            {"kind": r.get("kind"), "name": r.get("name"),
+             "uid": r.get("uid")}
+            for r in meta.get("ownerReferences", [])],
+        "creation_timestamp": meta.get("creationTimestamp", ""),
+        "deletion_timestamp": meta.get("deletionTimestamp", "")}
+    spec = obj.get("spec")
+    if isinstance(spec, dict):
+        attrs["spec_keys"] = sorted(spec.keys())
+        # shallow signal fields for topology/reconciliation
+        for k in ("replicas", "type", "clusterIP", "ports", "selector",
+                  "serviceAccountName", "serviceAccount"):
+            if k in spec:
+                attrs[f"spec.{k}"] = spec[k]
+    if kind in SENSITIVE_KINDS:
+        for dk in SECRET_DATA_KEYS:
+            if dk in obj:
+                attrs["secret_payload_blank"] = True
+        attrs["secret_type"] = obj.get("type", "")
+    status = obj.get("status")
+    if isinstance(status, dict):
+        attrs["status.phase"] = status.get("phase", "")
+        attrs["status.conditions"] = [
+            {"type": c.get("type"), "status": c.get("status")}
+            for c in status.get("conditions", [])][:8]
+    lifecycle = "present"
+    if meta.get("deletionTimestamp"):
+        lifecycle = "deleting"
+    return ObservedObject(
+        resource_id=canonical_id(cluster, ns, kind, name, uid),
+        resource_type=kind_of(api, kind),
+        attributes={k: v for k, v in attrs.items() if v not in ("", {}, [], None)},
+        provider="kubernetes", cluster=cluster, namespace=ns, name=name,
+        uid=uid, lifecycle=lifecycle,
+        observed_at=observed_at)
+
+
+@dataclass
+class K8sCollector:
+    """Pure collector core — `transport` is the only side effect."""
+    transport: Transport | None = None
+    context: str = ""
+    chunk_size: int = 500
+
+    def _run(self, args: list[str]) -> tuple[int, str, str]:
+        if self.transport is None:
+            raise RuntimeError("no transport — host-side kubectl adapter "
+                               "required (see k8s_transport.py)")
+        return self.transport(args)
+
+    def _base_args(self) -> list[str]:
+        return ["--context", self.context] if self.context else []
+
+    # ── discovery ─────────────────────────────────────────────
+    def discover(self) -> dict[str, Any]:
+        """api-resources --verbs=list; unsupported types are evidence."""
+        rc, out, err = self._run(
+            self._base_args() + ["api-resources", "--verbs=list",
+                                 "--no-headers", "-o",
+                                 "wide"])
+        if rc != 0:
+            return {"ok": False, "error": err.strip() or "discovery failed",
+                    "resources": []}
+        names = []
+        for line in out.splitlines():
+            parts = line.split()
+            if parts:
+                names.append(parts[0].split(",")[0])
+        return {"ok": True, "resources": sorted(set(names))}
+
+    def can_i(self, verbs: tuple[str, ...] = ("get", "list", "watch")) -> \
+            dict[str, Any]:
+        """Credential preflight — which read verbs are granted."""
+        granted, denied = [], []
+        for v in verbs:
+            rc, out, _ = self._run(
+                self._base_args() + ["auth", "can-i", v, "*", "--all-namespaces"])
+            (granted if rc == 0 and out.strip().startswith("yes") else denied).append(v)
+        return {"granted": sorted(granted), "denied": sorted(denied),
+                "cluster_admin_required": False}
+
+    # ── collection ────────────────────────────────────────────
+    def collect(self, scope: ObservationScope | None = None,
+                budget: ObservationBudget | None = None) -> ObservationEnvelope:
+        scope = scope or ObservationScope(provider="kubernetes")
+        scope.provider = "kubernetes"
+        if self.context:
+            scope.clusters = sorted(set(scope.clusters) | {self.context})
+        budget = budget or ObservationBudget()
+        ledger = ProviderCallLedger(collector=COLLECTOR_VERSION,
+                                    started_at=now_iso())
+        started = time.monotonic()
+        captured_at = now_iso()
+        envelope = ObservationEnvelope.new(
+            collector="kubernetes", version=COLLECTOR_VERSION,
+            provider="kubernetes", source_type="observed",
+            scope=scope, captured_at=captured_at)
+
+        resources = (scope.resource_types or list(DEFAULT_RESOURCES))
+        denied_scopes: list[dict[str, Any]] = []
+        per_type: dict[str, str] = {}
+        reasons: list[str] = []
+        total_pages = 0
+
+        for res in resources:
+            violation = budget.check(ledger)
+            if violation:
+                per_type[res] = "truncated"
+                reasons.append(f"budget {violation} hit — remaining types "
+                               "declared truncated, not skipped")
+                break
+            namespaced = res != "namespaces" and not res.startswith("cluster")
+            args = self._base_args() + ["get", res, "-o", "json",
+                                        "--chunk-size", str(self.chunk_size)]
+            if scope.namespaces:
+                args += ["-n", ",".join(scope.namespaces)]
+            elif namespaced:
+                args += ["--all-namespaces"]
+            if scope.selectors.get("labels"):
+                args += ["-l", scope.selectors["labels"]]
+            ledger.pages_since_reset = 0
+            rc, out, err = self._run(args)
+            ledger.record_call("k8s.get", pages=1,
+                               nbytes=len(out.encode()))
+            total_pages += 1
+            if rc != 0:
+                msg = err.strip()
+                if "Forbidden" in msg or "forbidden" in msg:
+                    per_type[res] = "permission-limited"
+                    denied_scopes.append({"resource_type": res,
+                                          "reason": msg})
+                    continue
+                if "the server doesn't have a resource type" in msg or \
+                        "NotFound" in msg:
+                    per_type[res] = "unsupported"
+                    continue
+                per_type[res] = "unknown"
+                ledger.errors.append(f"{res}: {msg}")
+                reasons.append(f"{res}: {msg}")
+                continue
+            try:
+                doc = json.loads(out)
+            except json.JSONDecodeError:
+                per_type[res] = "unknown"
+                ledger.errors.append(f"{res}: undecodable response")
+                continue
+            items = doc.get("items", []) if isinstance(doc, dict) else []
+            cont = doc.get("metadata", {}).get("continue", "")
+            rv = doc.get("metadata", {}).get("resourceVersion", "")
+            for obj in items:
+                o = project_object(obj, cluster=self.context,
+                                   observed_at=captured_at)
+                envelope.objects.append(o.to_dict())
+            ledger.record_call("k8s.get", pages=0, objects=len(items))
+            ledger.pages_since_reset = 0
+            # continuation pages (kubectl returns remaining via --continue)
+            while cont:
+                ledger.pages_since_reset += 1
+                violation = budget.check(ledger)
+                if violation:
+                    per_type[res] = "truncated"
+                    reasons.append(f"{res}: budget {violation} — partial list")
+                    cont = ""
+                    break
+                rc, out, err = self._run(
+                    self._base_args() + ["get", res, "-o", "json",
+                                         "--chunk-size", str(self.chunk_size),
+                                         "--continue", cont] +
+                    (["-n", ",".join(scope.namespaces)]
+                     if scope.namespaces else
+                     (["--all-namespaces"] if namespaced else [])))
+                ledger.record_call("k8s.get", pages=1,
+                                   nbytes=len(out.encode()))
+                total_pages += 1
+                if rc != 0:
+                    per_type[res] = "partial"
+                    ledger.errors.append(f"{res} continuation: {err.strip()}")
+                    break
+                doc = json.loads(out)
+                items = doc.get("items", [])
+                cont = doc.get("metadata", {}).get("continue", "")
+                for obj in items:
+                    envelope.objects.append(project_object(
+                        obj, cluster=self.context,
+                        observed_at=captured_at).to_dict())
+                ledger.record_call("k8s.get", pages=0, objects=len(items))
+            else:
+                per_type.setdefault(res, "complete")
+            per_type.setdefault(res, "complete")
+            if rv:
+                envelope.pagination[res] = {"resource_version": rv}
+
+        done = now_iso()
+        envelope.completed_at = done
+        cap = parse_ts(captured_at)
+        if cap:
+            envelope.fresh_until = iso(cap + timedelta(seconds=300))
+        status = "complete"
+        if any(v in ("permission-limited", "partial", "truncated")
+               for v in per_type.values()):
+            status = "partial" if any(v == "complete" for v in per_type.values()) \
+                else "permission-limited"
+        elif not per_type:
+            status = "unknown"
+        envelope.coverage = Coverage(
+            status=status, per_resource_type=per_type,
+            reasons=sorted(set(reasons))).to_dict()
+        envelope.permissions = {
+            "denied_scopes": denied_scopes,
+            "cluster_admin_required": False}
+        envelope.errors = ledger.errors
+        envelope.bytes = ledger.bytes
+        receipt = CollectorReceipt(
+            collector="kubernetes", collector_version=COLLECTOR_VERSION,
+            provider="kubernetes", started_at=ledger.started_at,
+            completed_at=done, scope=scope.to_dict(),
+            api_calls=ledger.api_calls, pages=ledger.pages,
+            objects=ledger.objects, bytes=ledger.bytes,
+            errors=ledger.errors,
+            permission_denied=denied_scopes,
+            metadata_only=True,
+            coverage=envelope.coverage,
+            freshness={"captured_at": captured_at,
+                       "fresh_until": envelope.fresh_until},
+            duration_s=round(time.monotonic() - started, 3))
+        envelope.receipt = receipt.to_dict()
+        return envelope
+
+    # ── watch (§27–28) ────────────────────────────────────────
+    def watch(self, res: str, *, resource_version: str = "",
+              timeout_s: int = 60,
+              handler: Callable[[dict[str, Any]], None] | None = None,
+              ) -> dict[str, Any]:
+        """Single watch pass. Returns cursor + events + whether a
+        resnapshot is required. Never long-polls forever — the host
+        loops; this returns bounded evidence."""
+        args = self._base_args() + ["get", res, "--watch",
+                                    "-o", "json",
+                                    "--timeout-seconds", str(timeout_s)]
+        if resource_version:
+            args += ["--resource-version", resource_version]
+        rc, out, err = self._run(args)
+        events, cursor, resnapshot = [], resource_version, False
+        for line in out.splitlines():
+            if not line.strip():
+                continue
+            try:
+                ev = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            o = ev.get("object", {})
+            rv = o.get("metadata", {}).get("resourceVersion", "")
+            if rv:
+                cursor = rv
+            if ev.get("type") == "ERROR":
+                code = (o.get("code"), o.get("reason", ""))
+                if 410 in code or "Expired" in str(code):
+                    resnapshot = True
+            events.append({"type": ev.get("type"),
+                           "kind": o.get("kind", ""),
+                           "name": o.get("metadata", {}).get("name", ""),
+                           "namespace": o.get("metadata", {}).get("namespace", ""),
+                           "uid": o.get("metadata", {}).get("uid", ""),
+                           "resource_version": rv})
+            if handler:
+                handler(events[-1])
+        if rc != 0 and ("410" in err or "Expired" in err or "Gone" in err):
+            resnapshot = True
+        return {"resource": res, "events": events, "cursor": cursor,
+                "resnapshot": resnapshot,
+                "error": err.strip() if rc != 0 else ""}
+
+
+def required_rbac(*, namespaced_only: bool = False,
+                  extra_types: list[str] | None = None) -> dict[str, Any]:
+    """§31 — minimal read-only RBAC manifest. get/list/watch only; the
+    generator structurally cannot emit cluster-admin."""
+    rules = [{"apiGroups": ["*"], "resources": ["*"],
+              "verbs": ["get", "list", "watch"]}]
+    if extra_types:
+        rules.append({"apiGroups": ["*"], "resources": extra_types,
+                      "verbs": ["get", "list", "watch"]})
+    kind = "Role" if namespaced_only else "ClusterRole"
+    manifest = {
+        "apiVersion": "rbac.authorization.k8s.io/v1",
+        "kind": kind,
+        "metadata": {"name": "platformforge-live-reader",
+                     "labels": {"app.kubernetes.io/part-of":
+                                "platformforge"}},
+        "rules": rules}
+    return {"kind": kind, "verbs": ["get", "list", "watch"],
+            "cluster_admin": False, "manifest": manifest,
+            "yaml_hint": "apply with: kubectl apply -f rbac.yaml"}

platformforge/live/collectors/k8s_transport.py

@@ -0,0 +1,85 @@
+"""Host-side kubectl transport — THE network boundary for k8s live.
+
+Nothing else in platformforge/live touches the cluster. Credentials stay
+in the user's kubeconfig; this wrapper never reads, logs, or persists
+them. Read-only by construction: only get/api-resources/auth can-i
+argument shapes are allowed through.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import Any
+
+_ALLOWED_VERBS = {"get", "api-resources", "auth", "version",
+                  "config"}
+_DENIED_SUBSTRINGS = ("--token", "--password", "client-key",
+                      "client-certificate")
+
+
+def kubectl_available() -> bool:
+    return shutil.which("kubectl") is not None
+
+
+def current_context() -> str:
+    rc, out, _ = kubectl(["config", "current-context"])
+    return out.strip() if rc == 0 else ""
+
+
+def list_contexts() -> list[str]:
+    rc, out, _ = kubectl(["config", "get-contexts", "-o", "name"])
+    return sorted(out.split()) if rc == 0 else []
+
+
+def kubectl(args: list[str], timeout: int = 120) -> tuple[int, str, str]:
+    """Run a read-only kubectl invocation. Mutating verbs and credential
+    flags are refused before the subprocess is even spawned."""
+    if not args or args[0] not in _ALLOWED_VERBS:
+        verb = args[0] if args else "?"
+        return 2, "", f"refused: verb {verb!r} not in read-only allowlist"
+    joined = " ".join(args)
+    if any(d in joined for d in _DENIED_SUBSTRINGS):
+        return 2, "", "refused: credential flags must not be passed"
+    try:
+        r = subprocess.run(["kubectl", *args], capture_output=True,
+                           text=True, timeout=timeout, check=False)
+        return r.returncode, r.stdout, r.stderr
+    except FileNotFoundError:
+        return 127, "", "kubectl not on PATH"
+    except subprocess.TimeoutExpired:
+        return 124, "", f"kubectl timed out after {timeout}s"
+
+
+def make_transport(context: str = "", timeout: int = 120):
+    """Build a Transport callable bound to a kube context."""
+
+    def transport(a: list[str]) -> tuple[int, str, str]:
+        return kubectl(a, timeout=timeout)
+
+    transport.context = context  # type: ignore[attr-defined]
+    return transport
+
+
+def preflight(context: str = "") -> dict[str, Any]:
+    """`live doctor` probe — never inventories, only checks plumbing."""
+    out: dict[str, Any] = {"kubectl": kubectl_available(),
+                           "context": context or current_context()}
+    if not out["kubectl"]:
+        out["ok"] = False
+        out["error"] = "kubectl not on PATH"
+        return out
+    rc, ver, err = kubectl(["version", "--output", "json"])
+    out["ok"] = rc == 0
+    if rc != 0:
+        out["error"] = err.strip()
+    else:
+        import json
+        try:
+            doc = json.loads(ver)
+            out["server_version"] = (
+                doc.get("serverVersion") or {}).get("gitVersion", "")
+        except json.JSONDecodeError:
+            out["server_version"] = ""
+    out["contexts"] = list_contexts()
+    return out

platformforge/live/cursors.py

@@ -0,0 +1,48 @@
+"""CursorStore — persisted watch/list cursors (resourceVersion et al.).
+
+.platformforge/live/cursors/<collector>/<key>.json — lets a collector
+resume a watch instead of relisting; staleness is reported so callers
+can decide resnapshot (§27–28, §145 incremental collection).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from platformforge.core.hashing import sha256_text
+from platformforge.live.models import now_iso
+
+CURSORS_DIR = ".platformforge/live/cursors"
+
+
+class CursorStore:
+    def __init__(self, root: str | Path, collector: str = "kubernetes"):
+        self.dir = Path(root) / CURSORS_DIR / collector
+
+    def _key(self, name: str) -> Path:
+        return self.dir / f"{sha256_text(name)[:24]}.json"
+
+    def put(self, name: str, *, cursor: str,
+            watch_state: str = "idle", **extra: Any) -> dict[str, Any]:
+        self.dir.mkdir(parents=True, exist_ok=True)
+        doc = {"name": name, "cursor": cursor, "watch_state": watch_state,
+               "updated_at": now_iso(), **extra}
+        self._key(name).write_text(json.dumps(doc, indent=2,
+                                              sort_keys=True) + "\n")
+        return doc
+
+    def get(self, name: str) -> dict[str, Any] | None:
+        p = self._key(name)
+        return json.loads(p.read_text()) if p.exists() else None
+
+    def watch_state(self, name: str) -> str:
+        c = self.get(name)
+        return c.get("watch_state", "unknown") if c else "unknown"
+
+    def all(self) -> list[dict[str, Any]]:
+        if not self.dir.exists():
+            return []
+        return [json.loads(p.read_text())
+                for p in sorted(self.dir.glob("*.json"))]

platformforge/live/drift.py

@@ -0,0 +1,130 @@
+"""Live drift — temporal diff between observations (cycle §111–§116).
+
+diff_observations(before, after) emits DriftEvent records:
+- resource appeared          → observed-out-of-band candidate evidence
+- resource disappeared       → only "deleted" when the AFTER envelope
+  is complete+fresh+covering for that type; otherwise unresolved —
+  absence needs proof, not just absence of a row (§10, ADR-0013)
+- content changed            → drift on whitelisted attr diff
+
+Noise control (§115): identical (resource_id, class, fingerprint)
+events dedup per diff; repeated flaps between the same two hashes are
+counted, not re-emitted — the event ledger keeps one record with
+occurrence count.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.live.models import DriftEvent, ObservationEnvelope, ObservationScope, canonical_hash
+
+_SAFE_DIFF_ATTRS = None  # all attrs comparable — values were redacted
+
+
+def _fresh(env: ObservationEnvelope) -> bool:
+    return env.freshness_status_at() == "fresh"
+
+
+def _covers(env: ObservationEnvelope, obj: dict[str, Any]) -> bool:
+    scope = ObservationScope.from_dict(env.scope)
+    ok, _ = scope.covers({"resource_type": obj.get("resource_type", ""),
+                          "namespace": obj.get("namespace", ""),
+                          "cluster": obj.get("cluster", ""),
+                          "account": obj.get("account", ""),
+                          "region": obj.get("region", "")})
+    return ok
+
+
+def _attr_diff(a: dict, b: dict) -> dict[str, Any]:
+    keys = set(a) | set(b)
+    changed = {k: {"before": a.get(k), "after": b.get(k)}
+               for k in sorted(keys) if a.get(k) != b.get(k)}
+    return changed
+
+
+def diff_observations(before: ObservationEnvelope | dict,
+                      after: ObservationEnvelope | dict,
+                      *, now: str = "") -> dict[str, Any]:
+    if isinstance(before, dict):
+        before = ObservationEnvelope.from_dict(before)
+    if isinstance(after, dict):
+        after = ObservationEnvelope.from_dict(after)
+    bmap = {o.get("resource_id"): o for o in before.objects}
+    amap = {o.get("resource_id"): o for o in after.objects}
+    after_fresh = _fresh(after)
+    after_complete = (after.coverage or {}).get("status") == "complete"
+
+    events: list[DriftEvent] = []
+    unresolved: list[dict[str, Any]] = []
+
+    def _ev(rid: str, cls: str, b: dict, a: dict) -> DriftEvent:
+        return DriftEvent(
+            drift_id=f"drift-{canonical_hash({'r': rid, 'c': cls, 'a': after.observation_id})[:12]}",
+            resource_id=rid, drift_class=cls,
+            before={k: v for k, v in b.items()
+                    if k in ("attributes", "content_hash", "lifecycle")},
+            after={k: v for k, v in a.items()
+                   if k in ("attributes", "content_hash", "lifecycle",
+                            "diff", "deletion_evidence")},
+            observed_at=after.captured_at or now)
+
+    # appeared / changed
+    for rid in sorted(amap):
+        a, b = amap[rid], bmap.get(rid)
+        if b is None:
+            events.append(_ev(rid, "observed-out-of-band", {},
+                              dict(a, lifecycle="present")))
+            continue
+        if a.get("content_hash") and a.get("content_hash") == \
+                b.get("content_hash"):
+            continue
+        changed = _attr_diff(b.get("attributes", {}),
+                             a.get("attributes", {}))
+        if changed:
+            events.append(_ev(rid, "config-drift", b,
+                              dict(a, diff=changed)))
+
+    # disappeared — needs proof
+    for rid in sorted(set(bmap) - set(amap)):
+        b = bmap[rid]
+        if after_complete and after_fresh and _covers(after, b):
+            events.append(_ev(rid, "desired-missing-observed", b,
+                              {"lifecycle": "deleted",
+                               "deletion_evidence":
+                               "absent-in-complete-fresh-snapshot"}))
+        else:
+            unresolved.append({
+                "resource_id": rid,
+                "reason": f"after coverage={after.coverage.get('status')} "
+                          f"fresh={after_fresh} — deletion unproven",
+                "drift_class": "uncomparable"})
+
+    events.sort(key=lambda e: (e.drift_class, e.resource_id))
+    return {"drift": [e.to_dict() for e in events],
+            "unresolved": unresolved,
+            "before": before.observation_id, "after": after.observation_id,
+            "window": {"start": before.captured_at,
+                       "end": after.captured_at},
+            "counts": {c: sum(1 for e in events if e.drift_class == c)
+                       for c in sorted({e.drift_class for e in events})},
+            "after_complete": after_complete, "after_fresh": after_fresh}
+
+
+def dedup_events(new: list[dict[str, Any]],
+                 prior: list[dict[str, Any]]) -> tuple[list[dict], int]:
+    """§115 — drop events identical to previously journaled ones
+    (same resource+class+after-hash); return (kept, suppressed)."""
+    seen = {(e.get("resource_id"), e.get("drift_class"),
+             (e.get("after") or {}).get("content_hash"))
+            for e in prior}
+    kept, suppressed = [], 0
+    for e in new:
+        key = (e.get("resource_id"), e.get("drift_class"),
+               (e.get("after") or {}).get("content_hash"))
+        if key in seen:
+            suppressed += 1
+        else:
+            kept.append(e)
+            seen.add(key)
+    return kept, suppressed