platformforge 0.1.0__py3-none-any.whl

platformforge/aiplat/models.py

@@ -0,0 +1,175 @@
+"""Cycle 5 Phase K — AI platform awareness (§187–201).
+
+Platform-level contracts only — this is not an AI Forge (§188, §201):
+GPU/accelerator detection, capacity dims, serving SLO, unit economics
+with real denominators, optimization *recommendations* — nothing is
+terminated, downsized or purchased here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+GPU_DIMENSIONS = ("model", "memory", "count", "utilization",
+                  "allocation", "node_pool", "availability_zone")
+AI_NODE_KINDS = ("accelerator", "gpu_pool", "model", "model_endpoint",
+                 "inference_service", "training_job", "vector_store")
+
+# §199 — kubernetes AI workload signals
+K8S_GPU_RESOURCES = ("nvidia.com/gpu", "amd.com/gpu",
+                     "intel.com/gpu", "google.com/tpu")
+ACCELERATOR_LABELS = ("accelerator", "gpu", "nvidia.com/gpu.product",
+                      "node.kubernetes.io/instance-type")
+
+
+@dataclass
+class GPUCapacity:
+    """§192 — per-dimension GPU capacity; unknown dims stay unknown."""
+    pool_id: str
+    model: str = ""
+    count: int | None = None
+    memory_gb: float | None = None
+    utilization: float | None = None      # 0..100
+    allocated: int | None = None
+    node_pool: str = ""
+    availability_zone: str = ""
+    fractional: bool | None = None        # §193 — MIG/slice awareness
+    evidence: list[str] = field(default_factory=list)
+
+    @property
+    def headroom(self) -> float | None:
+        if self.count is None or self.allocated is None or not self.count:
+            return None
+        return round((self.count - self.allocated) / self.count, 3)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": "platformforge/gpu-capacity/v1", **asdict(self),
+                "headroom": self.headroom}
+
+
+@dataclass
+class ServingSLO:
+    """§196 — model serving SLO; missing inputs → unknown."""
+    endpoint_id: str
+    latency_p95_ms: float | None = None
+    availability: float | None = None
+    throughput_rps: float | None = None
+    error_rate: float | None = None
+    targets: dict[str, float] = field(default_factory=dict)
+
+    def verdict(self) -> str:
+        if self.latency_p95_ms is None and self.error_rate is None:
+            return "unknown"
+        bad = []
+        if self.targets.get("latency_p95_ms") and \
+           self.latency_p95_ms and \
+           self.latency_p95_ms > self.targets["latency_p95_ms"]:
+            bad.append("latency")
+        if self.targets.get("error_rate") and \
+           self.error_rate is not None and \
+           self.error_rate > self.targets["error_rate"]:
+            bad.append("errors")
+        return "violating" if bad else "healthy"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": "platformforge/serving-slo/v1", **asdict(self),
+                "verdict": self.verdict()}
+
+
+def ai_unit_economics(cost: float | None, tokens: float | None = None,
+                      inferences: float | None = None,
+                      gpu_hours: float | None = None) -> dict[str, Any]:
+    """§195/§361 — denominators required; no cost/token metric without
+    observed tokens."""
+    out: dict[str, Any] = {"schema": "platformforge/ai-unit-economics/v1"}
+    if cost is None:
+        return {**out, "cost": "unknown",
+                "reason": "no cost data", "confidence": "low"}
+    out["cost"] = cost
+    for name, den in (("tokens", tokens), ("inferences", inferences),
+                      ("gpu_hours", gpu_hours)):
+        if den:
+            key = {"tokens": "cost_per_1m_tokens",
+                   "inferences": "cost_per_inference",
+                   "gpu_hours": "cost_per_gpu_hour"}[name]
+            scale = 1_000_000 if name == "tokens" else 1
+            out[key] = round(cost / den * scale, 4)
+        else:
+            out[f"{name}_metric"] = "unknown"   # §295 — never fabricate
+    out["confidence"] = "medium" if (tokens or inferences) else "low"
+    return out
+
+
+def ai_capacity_risk(pools: list[GPUCapacity],
+                     queue_depth: float | None = None,
+                     cold_start_rate: float | None = None) -> dict[str, Any]:
+    """§197 — GPU saturation / queue / cold start / memory pressure."""
+    risks = []
+    for p in pools:
+        if p.utilization is not None and p.utilization >= 90:
+            risks.append({"pool": p.pool_id, "risk": "gpu-saturation",
+                          "utilization": p.utilization})
+        if p.headroom is not None and p.headroom < 0.1:
+            risks.append({"pool": p.pool_id, "risk": "low-headroom",
+                          "headroom": p.headroom})
+    if queue_depth is not None and queue_depth > 100:
+        risks.append({"risk": "queue-depth", "value": queue_depth})
+    if cold_start_rate is not None and cold_start_rate > 0.2:
+        risks.append({"risk": "cold-start", "rate": cold_start_rate})
+    return {"schema": "platformforge/ai-capacity-risk/v1",
+            "risks": risks, "pools_evaluated": len(pools),
+            "confidence": "medium" if risks else "low"}
+
+
+def ai_optimizations(pools: list[GPUCapacity],
+                     endpoints: list[dict[str, Any]],
+                     costs: dict[str, float] | None = None
+                     ) -> list[dict[str, Any]]:
+    """§198 — candidate optimizations with evidence; never prescriptive
+    without data, never executes."""
+    recs = []
+    for p in pools:
+        if p.utilization is not None and p.utilization < 15 and \
+           p.allocated:
+            recs.append({"type": "idle-gpu-pool", "pool": p.pool_id,
+                         "action": "evaluate rightsizing or scale-down",
+                         "evidence": {"utilization": p.utilization,
+                                      "allocated": p.allocated},
+                         "estimated_savings":
+                         (costs or {}).get(p.pool_id),
+                         "confidence": "low", "executes": False})
+    for e in endpoints:
+        if e.get("traffic_rps") is not None and e["traffic_rps"] < 0.1:
+            recs.append({"type": "idle-endpoint",
+                         "endpoint": e.get("id", "unknown"),
+                         "action": "evaluate scale-to-zero or spot",
+                         "evidence": {"traffic_rps": e["traffic_rps"]},
+                         "estimated_savings": e.get("cost_monthly"),
+                         "confidence": "low", "executes": False})
+    return recs
+
+
+def detect_ai_workloads(k8s_resources: list[dict[str, Any]]
+                        ) -> list[dict[str, Any]]:
+    """§199 — detect GPU workloads from k8s resource requests/labels."""
+    out = []
+    for r in k8s_resources:
+        res = r.get("resources", {}) or {}
+        limits = res.get("limits", {}) or {}
+        labels = r.get("labels", {}) or {}
+        gpu_kind = next((g for g in K8S_GPU_RESOURCES if g in limits), None)
+        accel = labels.get("accelerator") or labels.get(
+            "nvidia.com/gpu.product")
+        if gpu_kind or accel:
+            out.append({"workload": r.get("id") or r.get("name", ""),
+                        "gpu_resource": gpu_kind,
+                        "gpu_count": limits.get(gpu_kind) if gpu_kind
+                        else None,
+                        "accelerator_model": accel,
+                        "fractional": bool(gpu_kind and
+                                           float(limits.get(gpu_kind,
+                                                            1)) < 1),
+                        "evidence": ["k8s.resource.limits",
+                                     "k8s.labels"]})
+    return out

platformforge/analytics/__init__.py

@@ -0,0 +1,6 @@
+"""Cycle 5 — Platform Analytics: history, measurement, policy, golden
+path, capacity, reliability, finops, ops analytics. Invariants:
+deterministic aggregates only (no fake ML), every metric carries
+source/evidence/confidence, `unknown` never collapses to zero,
+recommendations never execute.
+"""

platformforge/analytics/capacity.py

@@ -0,0 +1,109 @@
+"""Cycle 5 Phase H (1/2) — capacity intelligence (§104–114).
+
+`CapacitySnapshot` per member with dimension-level detail (§107);
+headroom only from valid data (§109); forecasts are honest levels —
+trend/seasonal/external with capped confidence, never fake ML
+(§110–112); `insufficient-history` instead of invented trends (§246).
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+DIMENSIONS = ("cpu", "memory", "storage", "pods", "network", "gpu",
+              "accelerators", "quota", "api_rate_limits")
+SOURCES = ("requested", "limits", "observed", "historical",
+           "provider_quota")
+
+
+@dataclass
+class CapacityDimension:
+    name: str
+    used: float | None = None
+    capacity: float | None = None
+    source: str = "observed"
+
+    @property
+    def headroom(self) -> float | None:
+        """§109 — only with valid data; never invented."""
+        if self.used is None or not self.capacity:
+            return None
+        return round((self.capacity - self.used) / self.capacity, 3)
+
+
+@dataclass
+class CapacitySnapshot:
+    """§106."""
+    member_id: str
+    captured_at: str = ""
+    dimensions: list[CapacityDimension] = field(default_factory=list)
+    source: str = "observed"
+    completeness: float | None = None
+
+    def saturation(self, threshold: float = 0.85) -> dict[str, Any]:
+        hot = [d.name for d in self.dimensions
+               if d.headroom is not None and d.headroom < (1 - threshold)]
+        unknown = [d.name for d in self.dimensions if d.headroom is None]
+        return {"member_id": self.member_id,
+                "saturated_dimensions": hot,
+                "unknown_dimensions": unknown,
+                "at_risk": bool(hot)}
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": "platformforge/capacity/v1",
+                **asdict(self), "saturation": self.saturation()}
+
+
+def forecast(points: list[dict[str, Any]],
+             min_observations: int = 14) -> dict[str, Any]:
+    """§110–112 — honest forecast levels. `trend` = simple linear
+    extrapolation from ≥min points; `seasonal` only when ≥2 full
+    seasons of history; otherwise `insufficient-history`."""
+    vals = [float(p["used"]) for p in points if "used" in p]
+    if len(vals) < 3:
+        return {"level": "insufficient-history",
+                "minimum_observations": 3, "sample_size": len(vals),
+                "confidence": "low"}
+    if len(vals) < min_observations:
+        # trend only, capped confidence — honest label (§112)
+        slope = (vals[-1] - vals[0]) / (len(vals) - 1)
+        return {"level": "trend", "slope_per_step": round(slope, 4),
+                "method": "linear-extrapolation",
+                "sample_size": len(vals), "confidence": "low",
+                "limitations": [
+                    "no seasonal component",
+                    "extrapolation past data is indicative only"]}
+    slope = (vals[-1] - vals[0]) / (len(vals) - 1)
+    return {"level": "trend", "slope_per_step": round(slope, 4),
+            "method": "linear-extrapolation",
+            "sample_size": len(vals), "confidence": "medium",
+            "limitations": ["no external signals",
+                            "reproducible method, not a prediction model"]}
+
+
+def capacity_risk(snap: CapacitySnapshot,
+                  criticality: str | None = None,
+                  autoscaling: bool | None = None,
+                  failure_domains: int | None = None) -> dict[str, Any]:
+    """§113–114 — headroom + criticality + autoscaling + failure
+    domains. Decomposed dimensions, never a bare number."""
+    sat = snap.saturation()
+    factors = {"saturated_dimensions": sat["saturated_dimensions"],
+               "criticality": criticality or "unknown",
+               "autoscaling": autoscaling,
+               "failure_domains": failure_domains}
+    level = "low"
+    if sat["saturated_dimensions"] and criticality in ("critical", "high"):
+        level = "high"
+    elif sat["saturated_dimensions"] or failure_domains == 1:
+        level = "medium"
+    if autoscaling and level == "medium":
+        level = "low"
+    if failure_domains == 1 and sat["saturated_dimensions"]:
+        level = "high"                      # SPOF + saturation
+    return {"member_id": snap.member_id, "risk": level,
+            "factors": factors,
+            "unknown_dimensions": sat["unknown_dimensions"],
+            "confidence": "medium" if not sat["unknown_dimensions"]
+            else "low"}

platformforge/analytics/debt.py

@@ -0,0 +1,92 @@
+"""Cycle 5 — platform/security debt + portfolio (§129–141).
+
+Debt items are evidence records, never a collapsed score (§137). Age
+matters (§136). Nothing is auto-retired (§141) — recommendations only.
+Capability health stays decomposable (§84).
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+DEBT_TYPES = ("unsupported-version", "manual-path", "missing-ownership",
+              "missing-slo", "policy-exception", "unallocated-cost",
+              "repeated-drift", "manual-runbook",
+              "non-standard-deployment", "security-exposure")
+
+
+@dataclass
+class DebtItem:
+    """§134–136."""
+    type: str
+    scope: dict[str, str]
+    evidence: list[str] = field(default_factory=list)
+    age_days: int | None = None
+    impact: str = "unknown"
+    owner: str = ""
+    recommended_path: str = ""
+    confidence: str = "low"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema": "platformforge/debt-item/v1", **asdict(self)}
+
+
+def debt_portfolio(items: list[DebtItem]) -> dict[str, Any]:
+    """Decomposed — never one 'tech debt score' (§137)."""
+    by_type: dict[str, int] = {}
+    aged = []
+    for i in items:
+        by_type[i.type] = by_type.get(i.type, 0) + 1
+        if i.age_days and i.age_days >= 30:
+            aged.append({"type": i.type, "scope": i.scope,
+                         "age_days": i.age_days,
+                         "evidence": i.evidence})
+    aged.sort(key=lambda a: -a["age_days"])
+    return {"schema": "platformforge/debt-portfolio/v1",
+            "total_items": len(items), "by_type": by_type,
+            "aged_30d_plus": aged,
+            "collapsed_score": None,
+            "note": "decomposed items — read dimensions, not a score"}
+
+
+def capability_health(cap: str, signals: dict[str, Any]) -> dict[str, Any]:
+    """§82–84 — capability dimensions, decomposable."""
+    dims = {"availability": signals.get("availability"),
+            "success_rate": signals.get("success_rate"),
+            "latency": signals.get("latency"),
+            "cost": signals.get("cost"),
+            "adoption": signals.get("adoption"),
+            "policy_friction": signals.get("policy_friction"),
+            "support_burden": signals.get("support_burden")}
+    return {"schema": "platformforge/capability-health/v1",
+            "capability": cap,
+            "dimensions": {k: (v if v is not None else "unknown")
+                           for k, v in dims.items()},
+            "aggregate": None,
+            "note": "decomposable — no opaque score"}
+
+
+def portfolio_quadrant(capabilities: dict[str, dict[str, Any]]
+                       ) -> dict[str, Any]:
+    """§138–141 — value-vs-cost quadrant; recommendations only."""
+    out = {"high_adoption_low_support": [], "high_adoption_high_support": [],
+           "low_adoption_high_cost": [], "low_adoption_low_cost": [],
+           "unclassified": []}
+    for cap, s in capabilities.items():
+        ad = s.get("adoption")
+        sup = s.get("support_burden")
+        cost = s.get("cost_monthly")
+        if ad is None:
+            out["unclassified"].append(cap)
+            continue
+        high_ad = ad >= 0.5
+        high_sup = (sup or 0) >= 3 or (cost or 0) >= 1000
+        key = ("high_adoption_high_support" if high_ad and high_sup else
+               "high_adoption_low_support" if high_ad else
+               "low_adoption_high_cost" if high_sup else
+               "low_adoption_low_cost")
+        out[key].append(cap)
+    out["auto_retire"] = False                # §141
+    out["note"] = "quadrant informs review — nothing is retired here"
+    return out

platformforge/analytics/dx.py

@@ -0,0 +1,69 @@
+"""Cycle 5 — developer experience intelligence (§142–149).
+
+Measures *platform friction* at team level — never individual
+productivity (§144–145, §305). Individual names are never required
+and never surfaced (§149); aggregation is the default (§148).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# hard guard — fields that would turn this into surveillance
+FORBIDDEN_METRICS = ("per_person", "individual", "developer_score",
+                     "productivity_score", "person_id")
+
+
+def dx_metrics(events: list[dict[str, Any]]) -> dict[str, Any]:
+    """§147 — team/platform-level friction metrics only."""
+    prov, failed, approvals, manual, retries, escapes = 0, 0, 0, 0, 0, 0
+    waits = []
+    for e in events:
+        t = e.get("type")
+        if t == "provision":
+            prov += 1
+            if e.get("wait_s"):
+                waits.append(e["wait_s"])
+        elif t == "request-failed":
+            failed += 1
+        elif t == "approval-required":
+            approvals += 1
+            if e.get("wait_s"):
+                waits.append(e["wait_s"])
+        elif t == "manual-handoff":
+            manual += 1
+        elif t == "retry":
+            retries += 1
+        elif t == "escape":
+            escapes += 1
+    total = prov + failed
+    waits.sort()
+    return {"schema": "platformforge/dx-metrics/v1",
+            "median_provision_wait_s": waits[len(waits) // 2]
+            if waits else "unknown",
+            "failed_request_rate": round(failed / total, 3)
+            if total else "unknown",
+            "manual_intervention_rate":
+            round(manual / max(total, 1), 3),
+            "approval_events": approvals, "retry_events": retries,
+            "escape_events": escapes,
+            "scope": "team/platform — no individual metrics",
+            "sample_size": len(events)}
+
+
+def guard_no_person_metrics(metrics: dict[str, Any]) -> list[str]:
+    """§305 property — scan a metric dict for surveillance-shaped keys."""
+    bad = []
+
+    def walk(o: Any, path: str = ""):
+        if isinstance(o, dict):
+            for k, v in o.items():
+                kl = str(k).lower()
+                if any(f in kl for f in FORBIDDEN_METRICS):
+                    bad.append(f"{path}.{k}" if path else str(k))
+                walk(v, f"{path}.{k}" if path else str(k))
+        elif isinstance(o, list):
+            for i, v in enumerate(o):
+                walk(v, f"{path}[{i}]")
+    walk(metrics)
+    return bad

platformforge/analytics/finops_v4.py

@@ -0,0 +1,171 @@
+"""Cycle 5 Phase G — FinOps V4 portfolio optimization (§85–103).
+
+Honesty contracts:
+- unallocated stays first-class, never hidden (§89);
+- missing cost data → `unknown`, never zero (§64, §355);
+- rightsizing uses multi-signal evidence — never CPU alone (§96);
+- `idle ≠ safe to delete` (§101);
+- commitments produce recommendations, never purchases (§103);
+- anomalies use deterministic baselines with capped confidence (§92–94).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.analytics.models import confidence_for_support
+
+ALLOC_CONFIDENCE = ("direct", "tag-based", "usage-based", "shared",
+                    "estimated", "unallocated")
+HIERARCHY = ("organization", "business_unit", "team", "product",
+             "service", "environment", "cluster", "workload")
+
+
+def cost_hierarchy(allocations: list[dict[str, Any]]) -> dict[str, Any]:
+    """§86–89 — aggregate cost by org→BU→team→…→workload; unallocated
+    is a first-class bucket."""
+    tree: dict[str, Any] = {"organization": {}, "unallocated": 0.0,
+                            "by_level": {k: {} for k in HIERARCHY}}
+    for a in allocations:
+        amount = float(a.get("amount", 0))
+        conf = a.get("allocation_confidence", "unallocated")
+        if conf == "unallocated" or a.get("unallocated"):
+            tree["unallocated"] += amount
+            continue
+        for level in HIERARCHY:
+            key = str(a.get(level) or "")
+            if not key:
+                continue
+            d = tree["by_level"][level].setdefault(
+                key, {"amount": 0.0, "confidence": conf,
+                      "items": 0})
+            d["amount"] += amount
+            d["items"] += 1
+            if ALLOC_CONFIDENCE.index(conf) > \
+               ALLOC_CONFIDENCE.index(d["confidence"]):
+                d["confidence"] = conf
+    total = sum(v["amount"] for lvl in tree["by_level"].values()
+                for v in lvl.values()) + tree["unallocated"]
+    tree["total"] = total
+    tree["unallocated_ratio"] = (round(tree["unallocated"] / total, 3)
+                                 if total else None)   # §64 None→unknown
+    return tree
+
+
+def unit_economics(cost: float | None,
+                   denominator: float | None,
+                   unit: str) -> dict[str, Any]:
+    """§90/§295 — only with a real business denominator."""
+    if cost is None or not denominator:
+        return {"metric": f"cost/{unit}", "value": "unknown",
+                "reason": "missing denominator or cost",
+                "confidence": "low"}
+    return {"metric": f"cost/{unit}", "value": round(cost / denominator, 6),
+            "confidence": "medium"}
+
+
+def cost_trend(points: list[dict[str, Any]],
+               window: int = 7) -> dict[str, Any]:
+    """§91–94 — deterministic baseline: moving average + pct change.
+    `insufficient-history` when below minimum (§246–247)."""
+    vals = [float(p["amount"]) for p in points if "amount" in p]
+    if len(vals) < 3:
+        return {"trend": "insufficient-history",
+                "minimum_observations": 3, "sample_size": len(vals),
+                "confidence": "low"}
+    ma = sum(vals[-window:]) / min(len(vals), window)
+    prev = sum(vals[:window]) / min(len(vals), window)
+    pct = ((ma - prev) / prev * 100) if prev else None
+    direction = ("up" if pct and pct > 5 else
+                 "down" if pct and pct < -5 else "flat")
+    return {"trend": direction, "moving_average": round(ma, 2),
+            "pct_change": round(pct, 2) if pct is not None else None,
+            "method": "moving-average+percent-change",
+            "sample_size": len(vals), "confidence": "low"}
+
+
+def anomalies(points: list[dict[str, Any]],
+              pct_threshold: float = 50.0) -> list[dict[str, Any]]:
+    """§92–94 — deterministic anomaly detection; confidence always
+    capped (no 'smart anomaly' claims)."""
+    vals = [float(p["amount"]) for p in points if "amount" in p]
+    if len(vals) < 4:
+        return []
+    base = sum(vals[:-1]) / (len(vals) - 1)
+    out = []
+    for p in points:
+        v = float(p.get("amount", 0))
+        if base and abs(v - base) / base * 100 >= pct_threshold:
+            out.append({"ts": p.get("ts", ""), "amount": v,
+                        "baseline": round(base, 2),
+                        "pct_deviation": round((v - base) / base * 100, 2),
+                        "confidence": "low",
+                        "method": "deterministic-baseline"})
+    return out
+
+
+def rightsizing(workload: dict[str, Any]) -> dict[str, Any] | None:
+    """§95–97 — multi-signal rightsizing. Requires ≥2 evidence signals;
+    CPU alone never suffices (§96)."""
+    sig = {"cpu_util": workload.get("cpu_util"),
+           "memory_util": workload.get("memory_util"),
+           "latency_p95": workload.get("latency_p95"),
+           "queue_depth": workload.get("queue_depth"),
+           "burst_events": workload.get("burst_events"),
+           "slo_headroom": workload.get("slo_headroom")}
+    observed = {k: v for k, v in sig.items() if v is not None}
+    if len(observed) < 2:
+        return None                        # not enough evidence (§96)
+    cpu = float(observed.get("cpu_util", 0) or 0)
+    mem = float(observed.get("memory_util", 0) or 0)
+    headroom = float(observed.get("slo_headroom", 0) or 0)
+    oversized = cpu < 20 and mem < 30 and headroom > 0.5
+    undersized = cpu > 85 or mem > 90 or headroom < 0
+    if not (oversized or undersized):
+        return None
+    return {"workload": workload.get("id", "unknown"),
+            "type": "downsize" if oversized else "upsize",
+            "current": workload.get("requests"),
+            "evidence": observed,
+            "signals_used": len(observed),
+            "performance_risk": "medium" if undersized else "low",
+            "reliability_risk": "low" if headroom > 0.3 else "medium",
+            "confidence": confidence_for_support(len(observed)),
+            "verification": "post-change SLO + utilization window",
+            "auto_apply": False}           # §99
+
+
+def idle_resources(resources: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """§100–101 — detect idle with evidence; never mark deletable."""
+    out = []
+    for r in resources:
+        signals = [s for s in ("cpu_util", "network_bytes", "attached",
+                             "requests_30d", "orphaned")
+                   if r.get(s) is not None]
+        idle = (r.get("requests_30d") == 0
+                or r.get("orphaned") is True
+                or (r.get("attached") is False
+                    and r.get("cpu_util", 1) < 5))
+        if idle and len(signals) >= 2:
+            out.append({"resource": r.get("id", "unknown"),
+                        "classification": "idle",
+                        "evidence": {s: r.get(s) for s in signals},
+                        "deletable": False,      # §101 — never
+                        "note": "idle ≠ safe to delete",
+                        "confidence": confidence_for_support(len(signals))})
+    return out
+
+
+def commitment_recommendation(usage: dict[str, Any]) -> dict[str, Any]:
+    """§102–103 — foundation: analyze steady-state usage, recommend
+    only. Never purchases."""
+    hours = usage.get("steady_hours_30d")
+    if not hours:
+        return {"recommendation": "insufficient-history",
+                "minimum": "30d steady usage", "executes": False}
+    return {"type": "commitment-candidate",
+            "evidence": {"steady_hours_30d": hours,
+                         "coverage_ratio": usage.get("coverage")},
+            "recommendation": "evaluate-savings-plan-or-RI",
+            "confidence": "low", "executes": False,
+            "note": "recommendation only — never a purchase"}