platformforge 0.1.0__py3-none-any.whl

platformforge/graph/model.py

@@ -0,0 +1,264 @@
+"""Deterministic graph model conforming to contracts/graph.schema.json
+(platformforge/graph/v1). Nodes and edges are derived from facts and carry
+source_fact_ids; inferred edges are never presented as observed."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import Any
+
+from platformforge.core.hashing import sha256_text
+from platformforge.graph.vocab import EDGE_KINDS, NODE_KINDS, PROVENANCES, impact_of
+
+SCHEMA = "platformforge/graph/v1"
+SCHEMA_V2 = "platformforge/graph/v2"
+SCHEMAS = (SCHEMA, SCHEMA_V2)
+_SLUG_RE = re.compile(r"[^a-z0-9_.\-/]+")
+
+_PROV_RANK = {"observed": 3, "planned": 2, "declared": 1, "inferred": 0}
+
+
+def _merge_evidence(a: tuple[dict, ...], b: tuple[dict, ...]) -> tuple[dict, ...]:
+    """Union edge evidence records keyed by (provenance, source_type):
+    fact_ids merge, observed_at keeps the max. Every contributing layer
+    stays visible — observed never erases declared (ADR-0015)."""
+    by_key: dict[tuple[str, str], dict] = {}
+    for rec in (*a, *b):
+        key = (rec.get("provenance", "declared"), rec.get("source_type", ""))
+        cur = by_key.get(key)
+        if cur is None:
+            by_key[key] = dict(rec, fact_ids=list(rec.get("fact_ids", [])))
+            continue
+        cur["fact_ids"] = sorted(set(cur["fact_ids"]) | set(rec.get("fact_ids", [])))
+        if rec.get("observed_at", "") > cur.get("observed_at", ""):
+            cur["observed_at"] = rec["observed_at"]
+    return tuple(by_key[k] for k in sorted(by_key))
+
+
+def _merge_temporal(a: dict, b: dict) -> dict:
+    """Temporal merge: windows span min→max, sample_count sums, expired
+    flag cleared by any new observation (fresh evidence revives)."""
+    if not a:
+        return dict(b)
+    if not b:
+        return dict(a)
+    out = dict(a)
+    for k in ("first_seen", "window_start"):
+        vals = [v for v in (a.get(k), b.get(k)) if v]
+        if vals:
+            out[k] = min(vals)
+    for k in ("last_seen", "window_end"):
+        vals = [v for v in (a.get(k), b.get(k)) if v]
+        if vals:
+            out[k] = max(vals)
+    if "sample_count" in a or "sample_count" in b:
+        out["sample_count"] = int(a.get("sample_count") or 0) + \
+            int(b.get("sample_count") or 0)
+    if not b.get("expired"):
+        out.pop("expired", None)
+    return out
+
+
+def node_id(kind: str, label: str) -> str:
+    """Deterministic node id: `kind/label` normalized."""
+    if kind not in NODE_KINDS:
+        raise ValueError(f"unknown node kind: {kind}")
+    slug = _SLUG_RE.sub("-", label.strip().lower()).strip("-")
+    if not slug:
+        raise ValueError("empty node label")
+    return f"{kind}/{slug}"
+
+
+@dataclass(frozen=True)
+class Node:
+    node_id: str
+    kind: str
+    label: str
+    attrs: dict[str, Any] = field(default_factory=dict)
+    source_fact_ids: tuple[str, ...] = ()
+
+    @classmethod
+    def make(cls, kind: str, label: str, attrs: dict[str, Any] | None = None,
+             fact_ids: Iterable[str] = ()) -> Node:
+        return cls(node_id=node_id(kind, label), kind=kind, label=label,
+                   attrs=dict(attrs or {}),
+                   source_fact_ids=tuple(sorted(set(fact_ids))))
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"node_id": self.node_id, "kind": self.kind,
+                             "label": self.label}
+        if self.attrs:
+            d["attrs"] = self.attrs
+        if self.source_fact_ids:
+            d["source_fact_ids"] = list(self.source_fact_ids)
+        return d
+
+
+@dataclass(frozen=True)
+class Edge:
+    src: str
+    dst: str
+    kind: str
+    provenance: str = "declared"        # effective (strongest) provenance
+    confidence: float = 1.0
+    source_fact_ids: tuple[str, ...] = ()
+    attrs: dict[str, Any] = field(default_factory=dict)
+    # v2 — per-layer evidence records; every contributing layer is kept
+    evidence: tuple[dict, ...] = ()
+    # v2 — temporal window for runtime edges
+    # {first_seen, last_seen, window_start, window_end, sample_count,
+    #  expired: bool}
+    temporal: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        if self.kind not in EDGE_KINDS:
+            raise ValueError(f"unknown edge kind: {self.kind}")
+        if self.provenance not in PROVENANCES:
+            raise ValueError(f"bad provenance: {self.provenance}")
+        if not (0.0 <= self.confidence <= 1.0):
+            raise ValueError("confidence out of range")
+        for rec in self.evidence:
+            if rec.get("provenance", self.provenance) not in PROVENANCES:
+                raise ValueError(f"bad evidence provenance: {rec}")
+
+    @property
+    def eid(self) -> str:
+        return f"{self.src}->{self.dst}:{self.kind}"
+
+    def layers(self) -> tuple[dict, ...]:
+        """All evidence layers. Edges loaded from v1 docs (no records)
+        synthesize a single layer from provenance+fact_ids on demand —
+        stored data is never rewritten (§94)."""
+        if self.evidence:
+            return self.evidence
+        return ({"provenance": self.provenance,
+                 "fact_ids": list(self.source_fact_ids)},)
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"from": self.src, "to": self.dst,
+                             "kind": self.kind, "provenance": self.provenance,
+                             "confidence": self.confidence}
+        if self.source_fact_ids:
+            d["source_fact_ids"] = list(self.source_fact_ids)
+        if self.evidence:
+            d["evidence"] = [dict(r) for r in self.evidence]
+        if self.temporal:
+            d["temporal"] = dict(self.temporal)
+        if self.attrs:
+            d["attrs"] = self.attrs
+        return d
+
+
+@dataclass
+class Graph:
+    nodes: dict[str, Node] = field(default_factory=dict)
+    edges: dict[str, Edge] = field(default_factory=dict)
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    def add_node(self, node: Node) -> Node:
+        existing = self.nodes.get(node.node_id)
+        if existing:
+            merged = Node(existing.node_id, existing.kind, existing.label,
+                          attrs={**existing.attrs, **node.attrs},
+                          source_fact_ids=tuple(sorted(
+                              set(existing.source_fact_ids)
+                              | set(node.source_fact_ids))))
+            self.nodes[node.node_id] = merged
+            return merged
+        self.nodes[node.node_id] = node
+        return node
+
+    def add_edge(self, edge: Edge) -> Edge:
+        if edge.src not in self.nodes or edge.dst not in self.nodes:
+            raise ValueError(f"edge endpoint missing: {edge.eid}")
+        existing = self.edges.get(edge.eid)
+        if existing:
+            stronger = existing if existing.confidence >= edge.confidence \
+                else edge
+            # §86–89 — effective provenance is the strongest *layer*;
+            # every contributing evidence record is preserved, never
+            # overwritten by a later/stronger layer.
+            provenance = max(
+                (existing.provenance, edge.provenance),
+                key=lambda p: _PROV_RANK[p])
+            merged = Edge(stronger.src, stronger.dst, stronger.kind,
+                          provenance=provenance,
+                          confidence=stronger.confidence,
+                          source_fact_ids=tuple(sorted(
+                              set(existing.source_fact_ids)
+                              | set(edge.source_fact_ids))),
+                          attrs={**existing.attrs, **edge.attrs},
+                          evidence=_merge_evidence(existing.layers(),
+                                                   edge.layers()),
+                          temporal=_merge_temporal(existing.temporal,
+                                                   edge.temporal))
+            self.edges[edge.eid] = merged
+            return merged
+        self.edges[edge.eid] = edge
+        return edge
+
+    # ── serialization ─────────────────────────────────────────
+    def to_dict(self, schema: str | None = None) -> dict[str, Any]:
+        """v2 is auto-emitted iff any edge carries evidence/temporal —
+        otherwise the document stays v1 (existing readers unaffected)."""
+        if schema is None:
+            schema = SCHEMA_V2 if any(
+                e.evidence or e.temporal for e in self.edges.values()) \
+                else SCHEMA
+        if schema not in SCHEMAS:
+            raise ValueError(f"unknown graph schema: {schema}")
+        return {
+            "schema": schema,
+            "nodes": [self.nodes[k].to_dict() for k in sorted(self.nodes)],
+            "edges": [self.edges[k].to_dict() for k in sorted(self.edges)],
+        }
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), sort_keys=True, indent=2)
+
+    @classmethod
+    def from_dict(cls, doc: dict[str, Any]) -> Graph:
+        if doc.get("schema") not in SCHEMAS:
+            raise ValueError(
+                f"not a platformforge graph document: {doc.get('schema')}")
+        g = cls()
+        for n in doc.get("nodes", []):
+            g.nodes[n["node_id"]] = Node(
+                node_id=n["node_id"], kind=n["kind"], label=n["label"],
+                attrs=n.get("attrs", {}),
+                source_fact_ids=tuple(n.get("source_fact_ids", [])))
+        for e in doc.get("edges", []):
+            evidence = tuple(dict(r) for r in e.get("evidence", []))
+            # v1 docs keep evidence empty — layers are synthesized lazily
+            # via edge.layers() so reading a v1 snapshot never rewrites
+            # its content hash (§94: migration is explicit, not silent).
+            g.edges[f"{e['from']}->{e['to']}:{e['kind']}"] = Edge(
+                src=e["from"], dst=e["to"], kind=e["kind"],
+                provenance=e.get("provenance", "declared"),
+                confidence=e.get("confidence", 1.0),
+                source_fact_ids=tuple(e.get("source_fact_ids", [])),
+                attrs=e.get("attrs", {}), evidence=evidence,
+                temporal=dict(e.get("temporal", {})))
+        return g
+
+    @property
+    def graph_hash(self) -> str:
+        return sha256_text(json.dumps(self.to_dict(), sort_keys=True))
+
+    def stats(self) -> dict[str, Any]:
+        by_kind: dict[str, int] = {}
+        for n in self.nodes.values():
+            by_kind[n.kind] = by_kind.get(n.kind, 0) + 1
+        by_edge: dict[str, int] = {}
+        for e in self.edges.values():
+            by_edge[e.kind] = by_edge.get(e.kind, 0) + 1
+        return {"nodes": len(self.nodes), "edges": len(self.edges),
+                "node_kinds": by_kind, "edge_kinds": by_edge,
+                "graph_hash": self.graph_hash}
+
+
+def impact_class(edge_kind: str) -> str:
+    return impact_of(edge_kind)

platformforge/graph/persist.py

@@ -0,0 +1,97 @@
+"""Graph persistence: canonical JSON + content-addressed snapshots.
+
+§6 — every snapshot carries an envelope: snapshot_id, timestamp, source,
+source_type (desired|planned|observed|runtime), environment, workspace,
+commit, provider, scope, graph_hash, fact_ids. Comparisons across types
+(desired↔planned↔observed) use graph.diff.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+from platformforge.graph.model import Graph
+
+GRAPH_DIR = ".platformforge/graph"
+
+SNAPSHOT_FIELDS = ("snapshot_id", "timestamp", "source", "source_type",
+                   "environment", "workspace", "commit", "provider",
+                   "scope", "graph_hash", "fact_ids")
+SOURCE_TYPES = ("desired", "planned", "observed", "runtime")
+
+
+def snapshot_meta(graph: Graph, *, source: str = "",
+                  source_type: str = "desired", environment: str = "",
+                  workspace: str = "", commit: str = "", provider: str = "",
+                  scope: str = "", fact_ids: list[str] | None = None,
+                  ) -> dict[str, Any]:
+    if source_type not in SOURCE_TYPES:
+        raise ValueError(f"source_type must be one of {SOURCE_TYPES}")
+    all_fids = sorted({fid for n in graph.nodes.values()
+                       for fid in getattr(n, "source_fact_ids", ())})
+    return {
+        "snapshot_id": f"gsnap-{graph.graph_hash[:16]}",
+        "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "source": source, "source_type": source_type,
+        "environment": environment, "workspace": workspace,
+        "commit": commit, "provider": provider, "scope": scope,
+        "graph_hash": graph.graph_hash,
+        "fact_ids": sorted(set(fact_ids or all_fids)),
+    }
+
+
+def save(graph: Graph, root: str | Path, name: str = "current",
+         **meta_kwargs: Any) -> Path:
+    d = Path(root) / GRAPH_DIR
+    d.mkdir(parents=True, exist_ok=True)
+    p = d / f"{name}.json"
+    p.write_text(graph.to_json() + "\n")
+    snap = d / "snapshots" / f"{graph.graph_hash}.json"
+    meta = d / "snapshots" / f"{graph.graph_hash}.meta.json"
+    if not snap.exists():
+        snap.parent.mkdir(parents=True, exist_ok=True)
+        snap.write_text(graph.to_json() + "\n")
+        meta.write_text(json.dumps(snapshot_meta(graph, **meta_kwargs),
+                                   indent=2, sort_keys=True) + "\n")
+    return p
+
+
+def load(root: str | Path, name: str = "current") -> Graph:
+    p = Path(root) / GRAPH_DIR / f"{name}.json"
+    if not p.exists():
+        raise FileNotFoundError(f"no graph named {name!r}")
+    return Graph.from_dict(json.loads(p.read_text()))
+
+
+def load_snapshot(root: str | Path, graph_hash: str) -> Graph:
+    p = Path(root) / GRAPH_DIR / "snapshots" / f"{graph_hash}.json"
+    if not p.exists():
+        raise FileNotFoundError(f"no snapshot {graph_hash}")
+    return Graph.from_dict(json.loads(p.read_text()))
+
+
+def snapshot_meta_of(root: str | Path, graph_hash: str) -> dict[str, Any]:
+    p = Path(root) / GRAPH_DIR / "snapshots" / f"{graph_hash}.meta.json"
+    if not p.exists():
+        return {}
+    return json.loads(p.read_text())
+
+
+def snapshots(root: str | Path) -> list[dict[str, Any]]:
+    d = Path(root) / GRAPH_DIR / "snapshots"
+    if not d.exists():
+        return []
+    out = []
+    for p in sorted(d.glob("*.json")):
+        if p.name.endswith(".meta.json"):
+            continue
+        entry: dict[str, Any] = {
+            "graph_hash": p.stem,
+            "saved_at": time.strftime(
+                "%Y-%m-%dT%H:%M:%SZ", time.gmtime(p.stat().st_mtime))}
+        entry.update(snapshot_meta_of(root, p.stem))
+        out.append(entry)
+    return out

platformforge/graph/query.py

@@ -0,0 +1,290 @@
+"""Graph queries: deps, dependents, paths, blast radius, gap detectors.
+
+Discipline (GRAPHFY.md): proximity is not causality — blast radius is
+reported per impact class and per hop, never as one merged number."""
+
+from __future__ import annotations
+
+from collections import deque
+from typing import Any
+
+from platformforge.graph.model import Edge, Graph, impact_class
+
+DEPENDENCY_KINDS = frozenset(
+    ["depends_on", "calls", "consumes", "reads", "writes", "uses_secret", "runs_on", "contained_by", "routes_to", "publishes_to", "provisioned_by"])
+
+
+def _adj(g: Graph, reverse: bool = False,
+         kinds: frozenset[str] | None = None) -> dict[str, list[Edge]]:
+    adj: dict[str, list[Edge]] = {nid: [] for nid in g.nodes}
+    for e in g.edges.values():
+        if kinds is not None and e.kind not in kinds:
+            continue
+        (adj[e.dst] if reverse else adj[e.src]).append(e)
+    return adj
+
+
+def neighbors(g: Graph, nid: str, kind: str | None = None) -> list[Edge]:
+    return [e for e in _adj(g)[nid] if kind is None or e.kind == kind]
+
+
+def dependencies(g: Graph, nid: str, transitive: bool = True,
+                 max_depth: int = 64) -> dict[str, int]:
+    """BFS downstream (what nid depends on) → {node_id: depth}."""
+    return _reach(g, nid, reverse=False, max_depth=max_depth) \
+        if transitive else {e.dst: 1 for e in
+                            _adj(g, kinds=DEPENDENCY_KINDS)[nid]}
+
+
+def dependents(g: Graph, nid: str, transitive: bool = True,
+               max_depth: int = 64) -> dict[str, int]:
+    """BFS upstream (what depends on nid) → {node_id: depth}."""
+    return _reach(g, nid, reverse=True, max_depth=max_depth) \
+        if transitive else {e.src: 1 for e in
+                            _adj(g, reverse=True,
+                                 kinds=DEPENDENCY_KINDS)[nid]}
+
+
+def _reach(g: Graph, nid: str, reverse: bool, max_depth: int,
+           kinds: frozenset[str] | None = DEPENDENCY_KINDS) -> dict[str, int]:
+    adj = _adj(g, reverse, kinds)
+    seen: dict[str, int] = {}
+    q: deque[tuple[str, int]] = deque([(nid, 0)])
+    while q:
+        cur, d = q.popleft()
+        if d >= max_depth:
+            continue
+        for e in adj.get(cur, []):
+            nxt = e.src if reverse else e.dst
+            if nxt not in seen and nxt != nid:
+                seen[nxt] = d + 1
+                q.append((nxt, d + 1))
+    return seen
+
+
+def paths(g: Graph, src: str, dst: str, max_paths: int = 16,
+          max_depth: int = 32) -> list[list[str]]:
+    """Up to `max_paths` simple src→dst paths, shortest-first (BFS).
+    A work cap keeps dense graphs bounded — the freeze dogfood bench
+    showed DFS wandering for minutes before reaching a near dst."""
+    out: list[list[str]] = []
+    adj = _adj(g)
+    q = deque([(src, [src])])
+    expansions = 0
+    while q and len(out) < max_paths and expansions < 200_000:
+        cur, path = q.popleft()
+        expansions += 1
+        if cur == dst:
+            out.append(path)
+            continue
+        if len(path) > max_depth:
+            continue
+        for e in adj.get(cur, []):
+            if e.dst not in path:
+                q.append((e.dst, path + [e.dst]))
+    return out
+
+
+def blast_radius(g: Graph, nid: str, max_depth: int = 64) -> dict[str, Any]:
+    """What breaks if nid breaks: upstream dependents (things that depend on
+    nid) decomposed by impact class and hop distance."""
+    adj_rev = _adj(g, reverse=True, kinds=DEPENDENCY_KINDS)
+    seen: dict[str, dict[str, Any]] = {}
+    q: deque[tuple[str, int, Edge | None]] = deque([(nid, 0, None)])
+    while q:
+        cur, d, _via = q.popleft()
+        if d >= max_depth:
+            continue
+        for e in adj_rev.get(cur, []):
+            if e.src == nid or e.src in seen:
+                continue
+            seen[e.src] = {"depth": d + 1,
+                           "impact_class": impact_class(e.kind),
+                           "via_edge": e.eid, "provenance": e.provenance}
+            q.append((e.src, d + 1, e))
+    by_class: dict[str, list[str]] = {}
+    for target, info in seen.items():
+        by_class.setdefault(info["impact_class"], []).append(target)
+    return {
+        "origin": nid,
+        "impacted_total": len(seen),
+        "by_class": {k: sorted(v) for k, v in sorted(by_class.items())},
+        "nodes": {k: seen[k] for k in sorted(seen)},
+        "note": "graph proximity is not proven causality; classes are "
+                "reported separately",
+    }
+
+
+def cycles(g: Graph, max_cycles: int = 100) -> list[list[str]]:
+    """Detect dependency cycles via DFS (bounded)."""
+    color: dict[str, int] = {}
+    out: list[list[str]] = []
+    adj = _adj(g, kinds=DEPENDENCY_KINDS)
+
+    def dfs(u: str, stack: list[str]) -> None:
+        color[u] = 1
+        for e in adj.get(u, []):
+            if len(out) >= max_cycles:
+                return
+            if color.get(e.dst, 0) == 1 and e.dst in stack:
+                out.append(stack[stack.index(e.dst):] + [e.dst])
+            elif color.get(e.dst, 0) == 0:
+                dfs(e.dst, stack + [e.dst])
+        color[u] = 2
+
+    for n in sorted(g.nodes):
+        if color.get(n, 0) == 0 and len(out) < max_cycles:
+            dfs(n, [n])
+    return out
+
+
+def condensation(g: Graph,
+                 kinds: frozenset[str] | None = DEPENDENCY_KINDS):
+    """SCC condensation of the dependency graph (iterative Tarjan).
+
+    Returns (node→scc int, members per scc, condensed reverse adjacency
+    scc→[parent sccs]). Nodes inside one SCC reach each other, so every
+    blast cone decomposes as: own SCC members + members of ancestor SCCs.
+    """
+    adj_fwd: dict[str, list[str]] = {n: [] for n in g.nodes}
+    for e in g.edges.values():
+        if kinds is None or e.kind in kinds:
+            adj_fwd[e.src].append(e.dst)
+    index: dict[str, int] = {}
+    low: dict[str, int] = {}
+    on_stack: set[str] = set()
+    stack: list[str] = []
+    scc_of: dict[str, int] = {}
+    members: list[list[str]] = []
+    t = 0
+    for root in g.nodes:
+        if root in index:
+            continue
+        work = [(root, 0)]
+        while work:
+            u, pi = work[-1]
+            if pi == 0:
+                index[u] = low[u] = t; t += 1
+                stack.append(u); on_stack.add(u)
+            recurse = False
+            nbrs = adj_fwd.get(u, [])
+            for i in range(pi, len(nbrs)):
+                v = nbrs[i]
+                if v not in index:
+                    work[-1] = (u, i + 1)
+                    work.append((v, 0))
+                    recurse = True
+                    break
+                if v in on_stack:
+                    low[u] = min(low[u], index[v])
+            if recurse:
+                continue
+            work.pop()
+            if work:
+                p = work[-1][0]
+                low[p] = min(low[p], low[u])
+            if low[u] == index[u]:
+                comp = []
+                while True:
+                    w = stack.pop()
+                    on_stack.discard(w)
+                    scc_of[w] = len(members)
+                    comp.append(w)
+                    if w == u:
+                        break
+                members.append(comp)
+    rev: dict[int, list[int]] = {i: [] for i in range(len(members))}
+    seen_pair: set[tuple[int, int]] = set()
+    for e in g.edges.values():
+        if kinds is not None and e.kind not in kinds:
+            continue
+        a, b = scc_of.get(e.dst), scc_of.get(e.src)
+        if a is not None and b is not None and a != b \
+                and (a, b) not in seen_pair:
+            seen_pair.add((a, b))
+            rev[a].append(b)
+    return scc_of, members, rev
+
+
+def _articulation_points(g: Graph) -> list[str]:
+    """Undirected cut vertices (iterative Tarjan) — nodes whose removal
+    increases the component count of the dependency graph."""
+    adj: dict[str, set[str]] = {n: set() for n in g.nodes}
+    for e in g.edges.values():
+        if e.kind in DEPENDENCY_KINDS:
+            adj[e.src].add(e.dst)
+            adj[e.dst].add(e.src)
+    disc: dict[str, int] = {}
+    low: dict[str, int] = {}
+    parent: dict[str, str] = {}
+    aps: set[str] = set()
+    t = 0
+    for root in g.nodes:
+        if root in disc:
+            continue
+        stack = [(root, iter(sorted(adj[root])))]
+        disc[root] = low[root] = t; t += 1
+        parent[root] = ""
+        children = 0
+        while stack:
+            u, it = stack[-1]
+            advanced = False
+            for v in it:
+                if v not in disc:
+                    parent[v] = u
+                    children += 1 if u == root else 0
+                    disc[v] = low[v] = t; t += 1
+                    stack.append((v, iter(sorted(adj[v]))))
+                    advanced = True
+                    break
+                if v != parent.get(u):
+                    low[u] = min(low[u], disc[v])
+            if not advanced:
+                stack.pop()
+                if stack:
+                    p = stack[-1][0]
+                    low[p] = min(low[p], low[u])
+                    if p != root and low[u] >= disc[p]:
+                        aps.add(p)
+        if children > 1:
+            aps.add(root)
+    return sorted(aps)
+
+
+def gaps(g: Graph) -> dict[str, Any]:
+    """Structural gaps: orphans, missing ownership/observability/protection,
+    unallocated cost, external exposure, single points of failure,
+    unreachable resources."""
+    fwd = _adj(g)
+    inbound = _adj(g, reverse=True)
+    orphans = [n for n in g.nodes if not fwd[n] and not inbound[n]]
+    owned = {e.dst for e in g.edges.values() if e.kind == "owns"}
+    observed = {e.src for e in g.edges.values() if e.kind == "observed_by"} | \
+        {e.dst for e in g.edges.values() if e.kind == "observed_by"}
+    secured = {e.src for e in g.edges.values() if e.kind == "secured_by"}
+    billed = {e.src for e in g.edges.values() if e.kind == "billed_to"}
+    exposed = {e.src for e in g.edges.values() if e.kind == "exposes"} | \
+        {nid for nid, n in g.nodes.items() if n.attrs.get("public")}
+    workloads = {nid for nid, n in g.nodes.items()
+                 if n.kind in ("workload", "service", "component")}
+    resources = {nid for nid, n in g.nodes.items()
+                 if n.kind in ("database", "bucket", "queue", "volume",
+                               "cluster", "load_balancer")}
+    # unreachable: a workload/resource nothing depends on, calls, or
+    # exposes — present in the platform but dead-ended from consumers.
+    unreachable = sorted(
+        n for n in workloads | resources
+        if n not in orphans and not inbound[n] and n not in exposed)
+    return {
+        "orphans": sorted(orphans),
+        "ownership_gaps": sorted(n for n in workloads | resources
+                                 if n not in owned),
+        "unmonitored": sorted(n for n in workloads if n not in observed),
+        "unprotected": sorted(n for n in workloads | resources
+                              if n not in secured),
+        "unallocated_cost": sorted(n for n in workloads | resources
+                                   if n not in billed),
+        "external_exposure": sorted(exposed),
+        "single_points_of_failure": _articulation_points(g),
+        "unreachable": unreachable,
+    }