platformforge 0.1.0__py3-none-any.whl

platformforge/finops/insights.py

@@ -0,0 +1,193 @@
+"""§90 FinOps v2 — rightsizing, idle, shared cost, forecast, anomalies,
+commitments, rate/usage optimization. Every insight is evidence-bound:
+without the measured signal the output is `unresolved` + what would
+unlock it. No savings number is ever asserted without a denominator.
+"""
+
+from __future__ import annotations
+
+import statistics
+from typing import Any
+
+
+def _costs(cost_facts: list[dict[str, Any]]) -> list[tuple[str, float, str]]:
+    out = []
+    for f in cost_facts:
+        if f.get("kind") != "finops.cost":
+            continue
+        a = f.get("attrs", {})
+        out.append((a.get("resource", "?"), float(a.get("amount") or 0),
+                    a.get("period", "unknown")))
+    return out
+
+
+def idle_resources(cost_facts: list[dict[str, Any]],
+                   utilization: dict[str, float] | None = None,
+                   idle_threshold: float = 0.02) -> dict[str, Any]:
+    """Cost-bearing resources with measured utilization below threshold.
+    Without utilization per resource the whole dimension is unresolved —
+    cost alone never proves idle."""
+    res = _costs(cost_facts)
+    if utilization is None:
+        return {"status": "unresolved",
+                "reason": "no utilization measurements supplied",
+                "unlock": "supply {resource: cpu/mem/utilization} measured "
+                          "over the billing window"}
+    idle = [{"resource": r, "cost": c, "utilization": utilization[r]}
+            for r, c, _ in res
+            if r in utilization and utilization[r] <= idle_threshold]
+    return {"status": "measured", "idle": sorted(idle,
+            key=lambda x: -x["cost"]),
+            "idle_cost_total": round(sum(i["cost"] for i in idle), 4),
+            "threshold": idle_threshold,
+            "resources_without_util": sorted(
+                {r for r, _, _ in res} - set(utilization))}
+
+
+def rightsizing(cost_facts: list[dict[str, Any]],
+                requested_vs_used: dict[str, dict[str, float]]
+                | None = None) -> dict[str, Any]:
+    """Resources where requested ≫ used. Needs measured request+usage —
+    without it the output is unresolved, never a guessed percentage."""
+    if not requested_vs_used:
+        return {"status": "unresolved",
+                "reason": "no requested-vs-used measurements supplied",
+                "unlock": "supply {resource: {requested: x, used: y}}"}
+    over = []
+    for r, m in requested_vs_used.items():
+        req, used = float(m.get("requested") or 0), float(m.get("used") or 0)
+        if req > 0 and used / req < 0.5:
+            over.append({"resource": r, "requested": req, "used": used,
+                         "headroom_ratio": round(1 - used / req, 3)})
+    cost_by_res = {r: c for r, c, _ in _costs(cost_facts)}
+    return {"status": "measured",
+            "oversized": sorted(over, key=lambda x: -cost_by_res.get(
+                x["resource"], 0)),
+            "note": "headroom is capacity signal; savings require the "
+                    "billed rate for the smaller shape — not asserted"}
+
+
+def anomalies(cost_facts: list[dict[str, Any]],
+              min_periods: int = 3,
+              z_threshold: float = 2.0) -> dict[str, Any]:
+    """Period-over-period anomalies per resource: |z| on the cost series.
+    Needs ≥ min_periods to compare; fewer → unresolved."""
+    series: dict[str, list[tuple[str, float]]] = {}
+    for r, c, p in _costs(cost_facts):
+        series.setdefault(r, []).append((p, c))
+    out, under_reported = [], []
+    for r, pts in sorted(series.items()):
+        pts.sort()
+        if len(pts) < min_periods:
+            under_reported.append(r)
+            continue
+        vals = [v for _, v in pts]
+        base, test = vals[:-1], vals[-1]
+        if len(base) < 2 or not statistics.stdev(base):
+            continue
+        z = (test - statistics.mean(base)) / statistics.stdev(base)
+        if abs(z) >= z_threshold:
+            out.append({"resource": r, "latest_period": pts[-1][0],
+                        "latest": test, "baseline_mean":
+                        round(statistics.mean(base), 4),
+                        "z": round(z, 2)})
+    return {"status": "measured" if out or not under_reported
+            else "partial",
+            "anomalies": out,
+            "series_too_short": under_reported,
+            "method": "z-score on own-period series, ≥3 periods",
+            "note": "anomaly = statistical outlier, not a cause"}
+
+
+def forecast(cost_facts: list[dict[str, Any]],
+             min_periods: int = 3) -> dict[str, Any]:
+    """Linear trend over period totals — labeled estimate, never a
+    commitment. Fewer periods → unresolved."""
+    totals: dict[str, float] = {}
+    for _, c, p in _costs(cost_facts):
+        totals[p] = totals.get(p, 0) + c
+    periods = sorted(totals)
+    if len(periods) < min_periods:
+        return {"status": "unresolved",
+                "reason": f"need ≥{min_periods} periods, have "
+                          f"{len(periods)}",
+                "periods": periods}
+    xs = list(range(len(periods)))
+    ys = [totals[p] for p in periods]
+    xm, ym = statistics.mean(xs), statistics.mean(ys)
+    var = sum((x - xm) ** 2 for x in xs) or 1
+    slope = sum((x - xm) * (y - ym) for x, y in zip(xs, ys)) / var
+    nxt = ym + slope * (len(periods) - xm)
+    return {"status": "measured",
+            "periods": {p: round(totals[p], 4) for p in periods},
+            "next_period_estimate": round(max(0.0, nxt), 4),
+            "slope": round(slope, 4),
+            "method": "OLS over period totals",
+            "note": "estimate only — seasonality and commitments are "
+                    "not modeled"}
+
+
+def commitments(cost_facts: list[dict[str, Any]],
+                committed: dict[str, float] | None = None) -> dict[str, Any]:
+    """RI/SP/CUD coverage: committed spend vs on-demand. Without declared
+    commitments → unresolved (a zero guess would be fabrication)."""
+    total = round(sum(c for _, c, _ in _costs(cost_facts)), 4)
+    if committed is None:
+        return {"status": "unresolved", "total_cost": total,
+                "reason": "no commitment instruments declared",
+                "unlock": "supply {resource|service: committed_amount}"}
+    covered = round(sum(committed.values()), 4)
+    return {"status": "measured", "total_cost": total,
+            "committed": covered,
+            "coverage_ratio": round(covered / total, 4) if total else None,
+            "on_demand_residual": round(max(0.0, total - covered), 4)}
+
+
+def shared_cost(cost_facts: list[dict[str, Any]],
+                split: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Shared-cost allocation: untagged/shared resources distributed by
+    declared policy. No declared split → listed, never silently spread."""
+    untagged = [{"resource": r, "cost": c}
+                for r, c, _ in _costs(cost_facts)
+                if not _tags_for(cost_facts, r)]
+    if split is None:
+        return {"status": "measured", "shared_unallocated": untagged,
+                "shared_cost_total": round(sum(u["cost"]
+                                               for u in untagged), 4),
+                "distributed": None,
+                "reason": "no split policy declared — amounts listed, "
+                          "not distributed",
+                "unlock": "supply {split: {tenant: weight}}"}
+    total_w = sum(split.values()) or 1
+    dist = {}
+    for u in untagged:
+        for tenant, w in split.items():
+            dist[tenant] = round(dist.get(tenant, 0) +
+                                 u["cost"] * w / total_w, 4)
+    return {"status": "measured", "shared_unallocated": untagged,
+            "distributed": dist, "policy": split}
+
+
+def _tags_for(cost_facts: list[dict[str, Any]], res: str) -> dict:
+    for f in cost_facts:
+        if f.get("kind") == "finops.cost" and \
+                f.get("attrs", {}).get("resource") == res:
+            return f["attrs"].get("tags") or {}
+    return {}
+
+
+def finops_report(cost_facts: list[dict[str, Any]],
+                  utilization: dict[str, float] | None = None,
+                  requested_vs_used: dict[str, dict[str, float]] | None
+                  = None,
+                  committed: dict[str, float] | None = None,
+                  split: dict[str, Any] | None = None) -> dict[str, Any]:
+    """§90 composite — every dimension independently measured/unresolved."""
+    return {"idle": idle_resources(cost_facts, utilization),
+            "rightsizing": rightsizing(cost_facts, requested_vs_used),
+            "anomalies": anomalies(cost_facts),
+            "forecast": forecast(cost_facts),
+            "commitments": commitments(cost_facts, committed),
+            "shared": shared_cost(cost_facts, split),
+            "note": "each dimension is independently evidence-bound; "
+                    "unresolved ≠ zero"}

platformforge/finops/unit.py

@@ -0,0 +1,36 @@
+"""§94 Unit economics — cost/request, cost/user, … — only with a real,
+measured denominator. Missing or zero denominators produce `unresolved`,
+never an interpolated number.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+DENOMINATORS = ("request", "transaction", "user", "tenant", "service",
+                "workload", "environment")
+
+
+def unit_economics(cost_facts: list[dict[str, Any]],
+                   denominators: dict[str, float]) -> dict[str, Any]:
+    """cost_facts: rows with `amount` + optional labels for split.
+    denominators: {unit: measured_count} — must be measured, >0."""
+    total = sum(float(f.get("attrs", {}).get("amount") or
+                    f.get("amount") or 0) for f in cost_facts)
+    out = {}
+    for unit in DENOMINATORS:
+        d = denominators.get(unit)
+        if d is None or d <= 0:
+            out[unit] = {"status": "unresolved",
+                         "reason": f"no measured denominator for '{unit}'",
+                         "cost_per": None}
+            continue
+        out[unit] = {"status": "measured", "denominator": d,
+                     "cost_per": round(total / d, 6)}
+    return {"total_cost": round(total, 4), "unit_economics": out,
+            "measured": [u for u, v in out.items()
+                         if v["status"] == "measured"],
+            "unresolved": [u for u, v in out.items()
+                           if v["status"] == "unresolved"],
+            "note": "denominators are caller-supplied measurements; "
+                    "a zero/missing one stays unresolved"}

platformforge/fleet/__init__.py

@@ -0,0 +1,5 @@
+"""Cycle 5 — Fleet Intelligence: organizational-scale models, org graph,
+fleet queries and snapshots. Core invariant: **coverage is part of every
+answer** — a fleet conclusion can never claim completeness its members
+didn't provide.
+"""

platformforge/fleet/loader.py

@@ -0,0 +1,73 @@
+"""Cycle 5 — fleet directory loader (shared by CLI + lab).
+
+A fleet directory is a bounded, offline input bundle:
+
+    fleet.yaml      members (Fleet.from_dict doc)
+    graph.yaml      nodes/edges (org + technical)
+    events.yaml     {source: [events]} for HistoryEngine
+    costs.yaml      cost facts + utilization + denominators
+    capacity.yaml   per-member capacity dimensions + observations
+    requests.yaml   golden-path requests/outcomes/escapes
+    policies.yaml   decisions/exceptions/overrides/outcomes
+
+All files optional — missing inputs keep their analytics `unknown`,
+never silently zero.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from platformforge.fleet.models import Fleet
+from platformforge.graph.model import Edge, Graph, Node
+
+FLEET_FILES = ("fleet", "graph", "events", "costs", "capacity",
+               "requests", "policies")
+
+
+def load_fleet_dir(path) -> dict[str, Any]:
+    """Load every present `<name>.yaml`; missing → None."""
+    fx = Path(path)
+    if not fx.is_dir():
+        raise FileNotFoundError(f"fleet dir not found: {fx}")
+    out: dict[str, Any] = {}
+    for name in FLEET_FILES:
+        p = fx / f"{name}.yaml"
+        out[name] = yaml.safe_load(p.read_text()) if p.exists() else None
+    return out
+
+
+def fleet_from(data: dict[str, Any]) -> Fleet:
+    doc = data.get("fleet") or {}
+    return Fleet.from_dict(doc) if doc.get("fleet_id") \
+        else Fleet(fleet_id=doc.get("fleet_id", "fleet"))
+
+
+def graph_from_doc(doc: dict[str, Any] | None) -> Graph:
+    """nodes/edges YAML → Graph; edge endpoints auto-materialize."""
+    g = Graph()
+    for n in (doc or {}).get("nodes", []):
+        g.add_node(Node.make(n["kind"], n["id"], attrs=n.get("attrs", {}),
+                             fact_ids=n.get("fact_ids", ())))
+    for e in (doc or {}).get("edges", []):
+        for nid in (e["src_id"], e["dst_id"]):
+            if nid not in g.nodes:
+                kind, _, label = nid.partition("/")
+                try:
+                    g.add_node(Node.make(kind, label or nid))
+                except ValueError:
+                    break
+        else:
+            g.add_edge(Edge(e["src_id"], e["dst_id"], e["kind"],
+                            provenance=e.get("provenance", "declared"),
+                            source_fact_ids=tuple(e.get("fact_ids", ()))))
+    return g
+
+
+def load_fleet(path) -> tuple[Fleet, Graph, dict[str, Any]]:
+    """Convenience: dir → (Fleet, Graph, raw docs)."""
+    data = load_fleet_dir(path)
+    return fleet_from(data), graph_from_doc(data.get("graph")), data

platformforge/fleet/models.py

@@ -0,0 +1,155 @@
+"""Cycle 5 Phase A — fleet contracts (§13–16, §23–24, §176).
+
+Invariants baked into the schema:
+- members identified by canonical IDs, never name alone (§15);
+- a FleetSnapshot stores *references/hashes* to member snapshots, not
+  duplicated resources (§24);
+- every member observation carries coverage + freshness — fleet
+  conclusions inherit the worst member coverage (§374);
+- data classification is mandatory on exports (§176).
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from platformforge.live.models import canonical_hash, now_iso
+
+SCHEMA = "platformforge/fleet/v1"
+SNAPSHOT_SCHEMA = "platformforge/fleet-snapshot/v1"
+
+MEMBER_KINDS = ("cluster", "cloud_account", "subscription", "project",
+                "repository", "service", "team", "environment", "region")
+CLASSIFICATIONS = ("public", "internal", "sensitive", "restricted")
+OBS_STATUSES = ("observed", "permission-limited", "unavailable",
+                "stale", "not-configured")
+
+
+@dataclass
+class FleetMember:
+    """§15 — canonical identity: kind + canonical_id (+ human name)."""
+    kind: str
+    canonical_id: str            # e.g. k8s:prod-1, aws:123456789012
+    name: str = ""
+    environment: str = ""
+    team: str = ""
+    region: str = ""
+    labels: dict[str, str] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class MemberObservation:
+    """Per-member observation envelope — coverage is first-class."""
+    member_id: str
+    status: str = "observed"           # OBS_STATUSES
+    coverage: float = 1.0              # 0..1 fraction of intended scope
+    freshness: str = "fresh"
+    observed_at: str = ""
+    snapshot_ref: str = ""             # hash/ref — not the payload
+    fact_count: int = 0
+    limitations: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class Fleet:
+    """§14 — fleet schema."""
+    fleet_id: str
+    organization: str = ""
+    environments: list[str] = field(default_factory=list)
+    members: list[FleetMember] = field(default_factory=list)
+    labels: dict[str, str] = field(default_factory=dict)
+    ownership: dict[str, str] = field(default_factory=dict)
+    policies: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": SCHEMA, "fleet_id": self.fleet_id,
+                "organization": self.organization,
+                "environments": self.environments,
+                "members": {"clusters": [m.to_dict() for m in self.members
+                                         if m.kind == "cluster"],
+                            "cloud_accounts": [m.to_dict() for m in self.members
+                                               if m.kind == "cloud_account"],
+                            "repositories": [m.to_dict() for m in self.members
+                                             if m.kind == "repository"],
+                            "services": [m.to_dict() for m in self.members
+                                         if m.kind == "service"],
+                            "teams": [m.to_dict() for m in self.members
+                                      if m.kind == "team"],
+                            "other": [m.to_dict() for m in self.members
+                                      if m.kind not in
+                                      ("cluster", "cloud_account",
+                                       "repository", "service", "team")]},
+                "labels": self.labels, "ownership": self.ownership,
+                "policies": self.policies}
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Fleet:
+        members = []
+        raw = d.get("members", {})
+        groups = raw.values() if isinstance(raw, dict) else [raw]
+        for group in groups:
+            for m in group:
+                members.append(FleetMember(**{
+                    k: v for k, v in m.items()
+                    if k in FleetMember.__dataclass_fields__}))
+        return cls(fleet_id=d["fleet_id"],
+                   organization=d.get("organization", ""),
+                   environments=d.get("environments", []),
+                   members=members, labels=d.get("labels", {}),
+                   ownership=d.get("ownership", {}),
+                   policies=d.get("policies", []))
+
+
+@dataclass
+class FleetSnapshot:
+    """§23–24 — references member snapshots by hash; coverage is the
+    *minimum* of member coverages (property test §296)."""
+    fleet_id: str
+    captured_at: str = ""
+    member_observations: list[MemberObservation] = field(
+        default_factory=list)
+    graph_ref: str = ""                # hash of merged fleet graph
+    fact_refs: list[str] = field(default_factory=list)
+
+    @property
+    def coverage(self) -> float:
+        obs = self.member_observations
+        if not obs:
+            return 0.0
+        return min(o.coverage for o in obs)
+
+    @property
+    def coverage_ratio(self) -> str:
+        obs = self.member_observations
+        ok = sum(1 for o in obs if o.status == "observed")
+        return f"{ok}/{len(obs)}"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": SNAPSHOT_SCHEMA, "fleet_id": self.fleet_id,
+                "captured_at": self.captured_at or now_iso(),
+                "coverage": {"ratio": self.coverage_ratio,
+                             "min_member": self.coverage},
+                "member_observations": [o.to_dict()
+                                        for o in self.member_observations],
+                "graph_ref": self.graph_ref, "fact_refs": self.fact_refs,
+                "hash": "sha256:" + canonical_hash(
+                    [o.to_dict() for o in self.member_observations]
+                    + self.fact_refs)}
+
+
+def member_key(kind: str, canonical_id: str) -> str:
+    """§15/§300 — names may collide across teams/envs; IDs never do."""
+    return f"{kind}:{canonical_id}"
+
+
+def classify(value: str | None, default: str = "internal") -> str:
+    """§176 — data classification with safe default (never leaks as
+    public by accident)."""
+    return value if value in CLASSIFICATIONS else default

platformforge/fleet/orggraph.py

@@ -0,0 +1,172 @@
+"""Cycle 5 Phase B — organizational graph projection (§17–22, §26).
+
+The org graph is a *layered* projection, never merged with the tech
+graph: each node belongs to exactly one layer (§20–21) and every
+federated node/edge preserves source member + fact ids (§26).
+
+Layers (§21): organization / platform-product / application /
+infrastructure / runtime / operations / cost / policy.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.fleet.models import Fleet, member_key
+from platformforge.graph.model import Edge, Graph, Node
+
+LAYERS = ("organization", "platform-product", "application",
+          "infrastructure", "runtime", "operations", "cost", "policy")
+
+# node kind → owning layer (§21). Kinds not listed default to the tech
+# graph's own layer — the org projection only materializes the org ones.
+KIND_LAYER = {
+    "organization": "organization", "business_unit": "organization",
+    "team": "organization", "domain": "organization",
+    "fleet": "organization", "environment": "organization",
+    "platform": "platform-product",
+    "platform_capability": "platform-product",
+    "golden_path": "platform-product", "product": "platform-product",
+    "operation_class": "platform-product",
+    "service": "application", "api": "application",
+    "repository": "application", "component": "application",
+    "workload": "application", "model": "application",
+    "inference_service": "application", "vector_store": "application",
+    "cluster": "infrastructure", "node_pool": "infrastructure",
+    "cloud_account": "infrastructure", "region": "infrastructure",
+    "database": "infrastructure", "gpu_pool": "infrastructure",
+    "accelerator": "infrastructure", "training_job": "infrastructure",
+    "model_endpoint": "infrastructure",
+    "pod": "runtime", "namespace": "runtime", "flow": "runtime",
+    "operation": "operations", "change_intent": "operations",
+    "approval": "operations", "rollback": "operations",
+    "runbook": "operations", "platform_request": "operations",
+    "cost_unit": "cost", "cost_center": "cost", "budget": "cost",
+    "billing_unit": "cost",
+    "policy": "policy", "security_policy": "policy",
+    "admission_policy": "policy", "policy_decision": "policy",
+}
+
+# org edge kinds that cross layers explicitly
+ORG_EDGES = ("owns", "consumes", "provides", "operates", "supports",
+             "funded_by", "depends_on", "governed_by", "uses_capability",
+             "uses_golden_path", "escapes_golden_path", "affected_by",
+             "shares_runtime_with")
+
+
+def layer_of(kind: str) -> str:
+    return KIND_LAYER.get(kind, "infrastructure")
+
+
+def project_fleet(fleet: Fleet,
+                  member_graphs: dict[str, Graph] | None = None,
+                  *,
+                  org_edges: list[dict[str, Any]] | None = None) -> Graph:
+    """Project a Fleet into an organizational graph (§17–19, §26).
+
+    - fleet/org/env/team/service members become org-layer nodes;
+    - member tech graphs merge in with `source_member` provenance;
+    - declared org edges (owns/uses_golden_path/…) attach by canonical id.
+    """
+    g = Graph()
+    g.meta["layer"] = "organizational"
+    g.meta["fleet_id"] = fleet.fleet_id
+    if fleet.organization:
+        g.add_node(Node.make("organization", fleet.organization))
+    g.add_node(Node.make("fleet", fleet.fleet_id))
+    for env in fleet.environments:
+        g.add_node(Node.make("environment", env))
+    for m in fleet.members:
+        kind = {"cluster": "cluster", "cloud_account": "cloud_account",
+                "repository": "repository", "service": "service",
+                "team": "team", "environment": "environment",
+                "subscription": "subscription", "project": "project",
+                "region": "region"}.get(m.kind, "component")
+        node = Node.make(kind, member_key(m.kind, m.canonical_id),
+                         attrs={"name": m.name or m.canonical_id,
+                                "environment": m.environment,
+                                "team": m.team, "region": m.region,
+                                "labels": m.labels})
+        g.add_node(node)
+        # fleet contains every member; environment scopes it
+        g.add_edge(Edge(g.nodes[f"fleet/{fleet.fleet_id}"].node_id,
+                        node.node_id, "contained_by",
+                        provenance="declared"))
+        if m.environment:
+            env_id = f"environment/{m.environment.lower()}"
+            if env_id in g.nodes:
+                g.add_edge(Edge(node.node_id, env_id, "contained_by",
+                                provenance="declared"))
+    # member tech graphs merge with per-member provenance (§26)
+    for member_id, mg in (member_graphs or {}).items():
+        for n in mg.nodes.values():
+            g.add_node(Node(n.node_id, n.kind, n.label,
+                            attrs={**n.attrs, "source_member": member_id},
+                            source_fact_ids=n.source_fact_ids))
+        for e in mg.edges.values():
+            if e.src in g.nodes and e.dst in g.nodes:
+                g.add_edge(Edge(e.src, e.dst, e.kind,
+                                provenance=e.provenance,
+                                confidence=e.confidence,
+                                source_fact_ids=e.source_fact_ids,
+                                attrs={**e.attrs,
+                                       "source_member": member_id}))
+    # declared org edges by canonical id: {src_kind, src_id, kind,
+    # dst_kind, dst_id, provenance}
+    for oe in org_edges or []:
+        src = Node.make(oe["src_kind"], oe["src_id"]).node_id
+        dst = Node.make(oe["dst_kind"], oe["dst_id"]).node_id
+        if src not in g.nodes:
+            g.add_node(Node.make(oe["src_kind"], oe["src_id"]))
+        if dst not in g.nodes:
+            g.add_node(Node.make(oe["dst_kind"], oe["dst_id"]))
+        g.add_edge(Edge(src, dst, oe["kind"],
+                        provenance=oe.get("provenance", "declared"),
+                        confidence=oe.get("confidence", 1.0),
+                        source_fact_ids=tuple(oe.get("fact_ids", ()))))
+    return g
+
+
+def layer_view(graph: Graph, layer: str) -> Graph:
+    """§20–21 — a single layer's nodes + intra-layer edges."""
+    out = Graph()
+    out.meta.update(graph.meta)
+    out.meta["layer"] = layer
+    keep = {nid for nid, n in graph.nodes.items()
+            if layer_of(n.kind) == layer}
+    for nid in keep:
+        out.nodes[nid] = graph.nodes[nid]
+    for e in graph.edges.values():
+        if e.src in keep and e.dst in keep:
+            out.edges[e.eid] = e
+    return out
+
+
+def cross_layer_path(graph: Graph, src: str, dst: str,
+                     max_depth: int = 8) -> list[dict[str, Any]]:
+    """§22 — cross-layer path query (e.g. team → service → cluster →
+    cost center). BFS over all edge kinds, direction-aware."""
+    from collections import deque
+    adj: dict[str, list[Edge]] = {}
+    for e in graph.edges.values():
+        adj.setdefault(e.src, []).append(e)
+        adj.setdefault(e.dst, []).append(e)   # undirected for tracing
+    seen = {src}
+    q = deque([(src, [])])
+    while q:
+        cur, path = q.popleft()
+        if cur == dst:
+            return path
+        if len(path) >= max_depth:
+            continue
+        for e in adj.get(cur, []):
+            nxt = e.dst if e.src == cur else e.src
+            if nxt in seen:
+                continue
+            seen.add(nxt)
+            q.append((nxt, path + [{
+                "node": nxt, "kind": e.kind,
+                "layer": layer_of(graph.nodes[nxt].kind),
+                "direction": "out" if e.src == cur else "in",
+                "provenance": e.provenance}]))
+    return []