platformforge 0.1.0__py3-none-any.whl

platformforge/product/golden_paths/library.yaml

@@ -0,0 +1,198 @@
+# §75 Golden Path seed library — seven starter paths covering the common
+# platform shapes. Each declares the full §74 contract incl. its escape
+# hatch (§77). Paths are declared knowledge (T5), not observed state.
+schema: platformforge/golden-paths/v1
+paths:
+  - id: rest-service
+    name: REST Service
+    version: "1.0.0"
+    use_case: "HTTP API deployed to the cluster with CI, scanning, SLO"
+    inputs:
+      - {name: service_name, required: true}
+      - {name: language, required: true, enum: [python, go, java, node]}
+      - {name: team, required: true}
+    outputs: [repository, pipeline, manifests, slo_contract, runbook]
+    steps:
+      - {id: scaffold, produces: repository}
+      - {id: ci, produces: pipeline}
+      - {id: secure, produces: sbom}
+      - {id: deploy, produces: manifests}
+      - {id: observe, produces: slo_contract}
+    policies: [pf-sec-baseline, pf-slo-required, pf-cost-tagging]
+    ownership: {owner_field: team, reviewer: platform-team}
+    observability: {metrics: required, traces: required, logs: required,
+                    dashboards: generated}
+    security: {sbom: required, image_signing: required,
+               network_policy: default-deny}
+    cost: {tag_required: [team, service], budget_alert: true}
+    slo: {availability: 99.9, latency_p99_ms: 500}
+    escape_hatches:
+      happy_path: "scaffold → CI green → deploy to dev → promote"
+      supported_customizations: [replicas, resources, ingress_host,
+                                 autoscaling]
+      escape_hatch: "file a platform.ticket with category path-escape;
+                     platform team reviews within SLA"
+      unsupported_state: "custom controllers, host mounts, privileged
+                          containers without exception record"
+    supported_variants: [public-api, internal-api]
+
+  - id: worker
+    name: Background Worker
+    version: "1.0.0"
+    use_case: "queue/topic consumer with retries, DLQ, autoscaling"
+    inputs:
+      - {name: worker_name, required: true}
+      - {name: source, required: true, enum: [sqs, kafka, pubsub]}
+      - {name: team, required: true}
+    outputs: [repository, pipeline, manifests, dlq, slo_contract]
+    steps:
+      - {id: scaffold, produces: repository}
+      - {id: ci, produces: pipeline}
+      - {id: secure, produces: sbom}
+      - {id: deploy, produces: manifests}
+      - {id: observe, produces: slo_contract}
+    policies: [pf-sec-baseline, pf-dlq-required, pf-cost-tagging]
+    ownership: {owner_field: team, reviewer: platform-team}
+    observability: {metrics: required, traces: recommended,
+                    logs: required}
+    security: {sbom: required, image_signing: required}
+    cost: {tag_required: [team, service]}
+    slo: {processing_lag_seconds: 60, success_rate: 99.5}
+    escape_hatches:
+      happy_path: "scaffold → wire trigger → deploy"
+      supported_customizations: [concurrency, batch_size, dlq_policy]
+      escape_hatch: "platform.ticket category path-escape"
+      unsupported_state: "custom brokers without platform review"
+    supported_variants: [fifo, at-least-once]
+
+  - id: scheduled-job
+    name: Scheduled Job
+    version: "1.0.0"
+    use_case: "cron workload with timeout, retries, alert on failure"
+    inputs:
+      - {name: job_name, required: true}
+      - {name: schedule, required: true}
+      - {name: team, required: true}
+    outputs: [repository, pipeline, cronjob_manifest, alert_rules]
+    steps:
+      - {id: scaffold, produces: repository}
+      - {id: ci, produces: pipeline}
+      - {id: deploy, produces: cronjob_manifest}
+    policies: [pf-sec-baseline, pf-cost-tagging]
+    ownership: {owner_field: team, reviewer: platform-team}
+    observability: {metrics: required, logs: required,
+                    alert_on_failure: true}
+    security: {sbom: required}
+    cost: {tag_required: [team, job]}
+    slo: {completion_rate: 99.0}
+    escape_hatches:
+      happy_path: "scaffold → schedule → alert wired"
+      supported_customizations: [schedule, timeout, retries]
+      escape_hatch: "platform.ticket category path-escape"
+      unsupported_state: "jobs needing state beyond idempotent retries"
+    supported_variants: [daily, hourly]
+
+  - id: kubernetes-service
+    name: Kubernetes Service
+    version: "1.0.0"
+    use_case: "containerized workload with HPA, PDB, netpol, GitOps"
+    inputs:
+      - {name: service_name, required: true}
+      - {name: image, required: true}
+      - {name: team, required: true}
+    outputs: [manifests, gitops_application, slo_contract]
+    steps:
+      - {id: generate, produces: manifests}
+      - {id: gitops, produces: gitops_application}
+      - {id: observe, produces: slo_contract}
+    policies: [pf-k8s-baseline, pf-netpol-default-deny, pf-pdb-multi-replica]
+    ownership: {owner_field: team, reviewer: platform-team}
+    observability: {metrics: required, dashboards: generated}
+    security: {network_policy: default-deny, pod_security: restricted}
+    cost: {tag_required: [team, service]}
+    slo: {availability: 99.9}
+    escape_hatches:
+      happy_path: "generate manifests → argocd app → deploys"
+      supported_customizations: [hpa_bounds, pdb, env_vars]
+      escape_hatch: "platform.ticket category path-escape"
+      unsupported_state: "privileged pods, host networking"
+    supported_variants: [stateless, stateful-rwo]
+
+  - id: terraform-workload
+    name: Terraform Workload
+    version: "1.0.0"
+    use_case: "IaC-managed infra with plan-gate, drift watch, cost tags"
+    inputs:
+      - {name: module_name, required: true}
+      - {name: provider, required: true, enum: [aws, azurerm, google]}
+      - {name: team, required: true}
+    outputs: [module_repo, ci_plan_gate, drift_monitor]
+    steps:
+      - {id: scaffold, produces: module_repo}
+      - {id: ci, produces: ci_plan_gate}
+      - {id: drift, produces: drift_monitor}
+    policies: [pf-iac-review, pf-cost-tagging]
+    ownership: {owner_field: team, reviewer: platform-team}
+    observability: {plan_artifacts: retained, drift_alerts: true}
+    security: {policy_check: required, state_backend: remote}
+    cost: {tag_required: [team], estimate_in_pr: true}
+    slo: {}
+    escape_hatches:
+      happy_path: "module → plan PR → review → apply by CI"
+      supported_customizations: [variables, outputs]
+      escape_hatch: "manual apply only via break-glass with receipt"
+      unsupported_state: "local state, console changes outside IaC"
+    supported_variants: [module, stack]
+
+  - id: database-request
+    name: Database Request
+    version: "1.0.0"
+    use_case: "managed datastore with backup, access policy, cost center"
+    inputs:
+      - {name: db_name, required: true}
+      - {name: engine, required: true,
+         enum: [postgres, mysql, dynamodb, redis]}
+      - {name: team, required: true}
+      - {name: data_classification, required: true}
+    outputs: [iac_module, access_policy, backup_policy]
+    steps:
+      - {id: request, produces: ticket}
+      - {id: provision, produces: iac_module}
+      - {id: secure, produces: access_policy}
+    policies: [pf-data-classification, pf-backup-required]
+    ownership: {owner_field: team, reviewer: dba-team}
+    observability: {metrics: required, slow_query_alerts: true}
+    security: {encryption: required, network: private-only}
+    cost: {tag_required: [team, db_name], budget_alert: true}
+    slo: {backup_rpo_hours: 24}
+    escape_hatches:
+      happy_path: "request → module PR → provisioned"
+      supported_customizations: [size, replicas, engine_version]
+      escape_hatch: "platform.ticket category database-exception"
+      unsupported_state: "public endpoints, unencrypted storage"
+    supported_variants: [dev, prod]
+
+  - id: queue-topic
+    name: Queue/Topic Request
+    version: "1.0.0"
+    use_case: "messaging resource with DLQ, retention, consumer wiring"
+    inputs:
+      - {name: resource_name, required: true}
+      - {name: kind, required: true, enum: [queue, topic]}
+      - {name: team, required: true}
+    outputs: [iac_module, dlq, consumer_contract]
+    steps:
+      - {id: request, produces: ticket}
+      - {id: provision, produces: iac_module}
+    policies: [pf-dlq-required, pf-cost-tagging]
+    ownership: {owner_field: team, reviewer: platform-team}
+    observability: {metrics: required, lag_alerts: true}
+    security: {encryption: required, access: scoped}
+    cost: {tag_required: [team]}
+    slo: {delivery_lag_seconds: 30}
+    escape_hatches:
+      happy_path: "request → module → wired"
+      supported_customizations: [retention, max_message_size]
+      escape_hatch: "platform.ticket category messaging-exception"
+      unsupported_state: "public topics, no DLQ"
+    supported_variants: [standard, fifo]

platformforge/product/golden_paths/model.py

@@ -0,0 +1,84 @@
+"""§74 Golden Path contract — a path is a governed capability, not a
+template. The model binds repo+CI+security+artifact+deployment+runtime+
+observability+SLO+ownership+cost (§76) and every path documents its
+escape hatch (§77): happy path, supported customizations, the escape
+route, and what is explicitly unsupported.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+REQUIRED_FIELDS = ("id", "name", "version", "use_case", "inputs",
+                   "outputs", "steps", "policies", "ownership",
+                   "observability", "security", "cost", "slo",
+                   "escape_hatches", "supported_variants")
+
+
+@dataclass
+class GoldenPath:
+    id: str
+    name: str
+    version: str
+    use_case: str
+    inputs: list[dict[str, Any]] = field(default_factory=list)
+    outputs: list[str] = field(default_factory=list)
+    steps: list[dict[str, Any]] = field(default_factory=list)
+    policies: list[str] = field(default_factory=list)
+    ownership: dict[str, Any] = field(default_factory=dict)
+    observability: dict[str, Any] = field(default_factory=dict)
+    security: dict[str, Any] = field(default_factory=dict)
+    cost: dict[str, Any] = field(default_factory=dict)
+    slo: dict[str, Any] = field(default_factory=dict)
+    escape_hatches: dict[str, Any] = field(default_factory=dict)
+    supported_variants: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, doc: dict[str, Any]) -> GoldenPath:
+        pid = doc.get("id", "?")
+        missing = [f for f in REQUIRED_FIELDS if f not in doc]
+        if missing:
+            raise ValueError(f"golden path {pid} missing "
+                             f"required fields: {missing}")
+        # §96 — structural validation, not just presence.
+        for i in doc["inputs"]:
+            if not isinstance(i, dict) or not i.get("name"):
+                raise ValueError(f"golden path {pid}: input without name")
+        for s in doc["steps"]:
+            if not isinstance(s, dict) or not s.get("id") \
+                    or not s.get("produces"):
+                raise ValueError(f"golden path {pid}: step without "
+                                 "id/produces")
+        if not doc["ownership"].get("owner_field"):
+            raise ValueError(f"golden path {pid}: ownership lacks "
+                             "owner_field")
+        for f in ("observability", "security", "cost"):
+            if not isinstance(doc[f], dict) or not doc[f]:
+                raise ValueError(f"golden path {pid}: {f} must be a "
+                                 "non-empty mapping")
+        # slo is required as a key but may be {} — infra paths produce no
+        # service-level SLO; empty is an honest "not applicable".
+        if not isinstance(doc["slo"], dict):
+            raise TypeError(f"golden path {pid}: slo must be a mapping")
+        for f in ("happy_path", "escape_hatch"):
+            if not doc["escape_hatches"].get(f):
+                raise ValueError(f"golden path {pid}: escape_hatches "
+                                 f"lacks {f}")
+        return cls(**{f: doc[f] for f in REQUIRED_FIELDS})
+
+    def capability(self) -> dict[str, Any]:
+        """§79 — machine-readable self-service contract. approval_required
+        stays True: paths propose changes, they never auto-mutate."""
+        return {
+            "capability": f"platform.path.{self.id}",
+            "version": self.version,
+            "use_case": self.use_case,
+            "inputs": self.inputs,
+            "policy": {"policies": self.policies,
+                       "escape_hatches": self.escape_hatches},
+            "risk": {"severity": "medium",
+                     "boundaries": ["scaffold", "pr"]},
+            "approval_required": True,
+            "mutates": False,
+        }

platformforge/product/maturity.py

@@ -0,0 +1,107 @@
+"""CNCF Platform Engineering Maturity Model scoring — 5 aspects × 4 levels.
+
+Evidence-driven: each aspect scores against declared signals (facts). A
+level is claimed only when its signals are observed — the model never
+asserts maturity without evidence ids.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+ASPECTS = ("investment", "adoption", "interfaces", "operations",
+           "measurement")
+LEVELS = ("provisional", "operational", "scalable", "optimizing")
+
+# aspect → level → signals (fact kinds/attrs observed). Conservative defaults.
+SIGNALS = {
+    "investment": {
+        "operational": ["dedicated_team", "funded"],
+        "scalable": ["platform_team", "product_manager"],
+        "optimizing": ["measured_dora_impact", "continual_funding_review"],
+    },
+    "adoption": {
+        "operational": ["some_self_service", "documented_onboarding"],
+        "scalable": ["default_paths_adopted", "adoption_tracked"],
+        "optimizing": ["platform_is_default", "feedback_loops"],
+    },
+    "interfaces": {
+        "operational": ["catalog", "templates"],
+        "scalable": ["golden_paths", "self_service_api"],
+        "optimizing": ["composable_products", "versioned_interfaces"],
+    },
+    "operations": {
+        "operational": ["runbooks", "oncall"],
+        "scalable": ["slo_defined", "error_budgets", "gitops"],
+        "optimizing": ["policy_as_code", "automated_remediation"],
+    },
+    "measurement": {
+        "operational": ["metrics_collected"],
+        "scalable": ["dora_tracked", "slo_reported"],
+        "optimizing": ["outcome_metrics", "adoption_metrics", "finops"],
+    },
+}
+
+_ORDER = {"provisional": 0, "operational": 1, "scalable": 2, "optimizing": 3}
+
+
+def _signal_provenance(v: Any) -> str:
+    """§80 — signals carry provenance: observed > declared > inferred.
+    A bare string is *declared*; {"signal": x, "provenance": p} carries it."""
+    if isinstance(v, dict):
+        return v.get("provenance", "declared")
+    return "declared"
+
+
+def maturity(signals: dict[str, list[Any]],
+             evidence: dict[str, list[str]] | None = None) -> dict[str, Any]:
+    """§80 — Level = highest level whose signals are *observed*. Declared
+    signals produce a `declared_level` claim; the gap between observed and
+    declared is surfaced, never collapsed. Unknown stays unknown."""
+    aspects = {}
+    for aspect in ASPECTS:
+        raw = signals.get(aspect, [])
+        names = {(_signal_name(s)): _signal_provenance(s) for s in raw}
+        obs = {n for n, p in names.items() if p == "observed"}
+        dec = set(names)  # declared ⊇ observed for level purposes
+        observed_level = _level_for(aspect, obs)
+        declared_level = _level_for(aspect, dec)
+        aspects[aspect] = {
+            "level": observed_level,              # the evidence-backed claim
+            "declared_level": declared_level,     # what configs/papers say
+            "overclaimed": _ORDER[declared_level] > _ORDER[observed_level],
+            "signals_observed": sorted(obs),
+            "signals_declared_only": sorted(dec - obs),
+            "evidence": (evidence or {}).get(aspect, [])}
+    return {"aspects": aspects, "schema": "platformforge/maturity/v2"}
+
+
+def _signal_name(s: Any) -> str:
+    return s.get("signal", "") if isinstance(s, dict) else str(s)
+
+
+def _level_for(aspect: str, have: set[str]) -> str:
+    level = "provisional"
+    for lv in ("operational", "scalable", "optimizing"):
+        want = SIGNALS[aspect].get(lv, [])
+        if all(s in have for s in want):
+            level = lv
+        else:
+            break  # maturity compounds — stop at first unmet level
+    return level
+
+
+def maturity_report(signals: dict[str, list[Any]],
+                    evidence: dict[str, list[str]] | None = None
+                    ) -> dict[str, Any]:
+    """Full v2 report: per-aspect + overall, with overclaim flags."""
+    out = maturity(signals, evidence)
+    overall = min(_ORDER[a["level"]] for a in out["aspects"].values())
+    out["overall_level"] = LEVELS[overall]
+    out["model"] = "CNCF Platform Engineering Maturity Model"
+    out["overclaimed_aspects"] = [a for a, v in out["aspects"].items()
+                                  if v["overclaimed"]]
+    out["note"] = ("level = highest fully-observed level; "
+                   "declared_level may exceed it — that gap is the "
+                   "missing evidence, not an error")
+    return out

platformforge/product/scorecards.py

@@ -0,0 +1,84 @@
+"""Scorecards v2 — §81 nine axes per entity. An axis with no evidence is
+`unknown`, never zero: zero would mean "checked and failed", unknown means
+"we don't know". Scores are evidence: each grade lists driving findings.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any
+
+_WEIGHT = {"info": 0, "low": 1, "medium": 3, "high": 7, "critical": 15}
+
+# §81 axes — rule_id prefix/domain → axes the finding speaks to
+AXES = ("ownership", "security", "reliability", "observability",
+        "supply_chain", "cost", "documentation", "deployment",
+        "operational_readiness")
+
+_DOMAIN_AXES: dict[str, tuple[str, ...]] = {
+    "k8s": ("deployment", "reliability", "operational_readiness"),
+    "gitops": ("deployment", "operational_readiness"),
+    "cicd": ("deployment", "supply_chain"),
+    "security": ("security", "supply_chain"),
+    "iam": ("security",),
+    "secrets": ("security",),
+    "sbom": ("supply_chain",),
+    "supply": ("supply_chain",),
+    "finops": ("cost",),
+    "sre": ("reliability", "observability", "operational_readiness"),
+    "slo": ("reliability", "observability"),
+    "otel": ("observability",),
+    "iac": ("deployment", "security"),
+    "product": ("ownership", "documentation"),
+    "catalog": ("ownership", "documentation"),
+}
+
+
+def scorecard(findings: list[dict[str, Any]],
+              evidence_domains: set[str] | None = None) -> dict[str, Any]:
+    """§81 — per-entity, per-axis. `evidence_domains` names the domains
+    that produced facts (a domain with no findings but which *was*
+    measured is measurably clean, not unknown)."""
+    per: dict[str, dict[str, list[dict]]] = defaultdict(
+        lambda: defaultdict(list))
+    seen_domains: set[str] = set(evidence_domains or ())
+    for f in findings:
+        if f.get("status") != "violated":
+            continue
+        dom = (f.get("rule_id") or "").split("-")[1].lower() \
+            if "-" in (f.get("rule_id") or "") else ""
+        loc = f.get("location") or "unknown"
+        seen_domains.add(dom)
+        for axis in _DOMAIN_AXES.get(dom, ("operational_readiness",)):
+            per[loc][axis].append(f)
+
+    cards = {}
+    for loc, axes in sorted(per.items()):
+        ax = {}
+        for axis in AXES:
+            fs = axes.get(axis, [])
+            if not fs:
+                # unknown ≠ zero: report which domains could have produced
+                # evidence for this axis, and whether any was measured
+                producers = [d for d, a in _DOMAIN_AXES.items()
+                             if axis in a]
+                ax[axis] = {
+                    "status": "clean" if any(p in seen_domains
+                                             for p in producers)
+                              else "unknown",
+                    "score": None if not any(p in seen_domains
+                                             for p in producers) else 100}
+                continue
+            penalty = sum(_WEIGHT.get(f.get("severity", "info"), 0)
+                          for f in fs)
+            score = max(0, 100 - penalty)
+            ax[axis] = {"status": "measured", "score": score,
+                        "driving_findings": [f.get("rule_id") for f in fs]}
+        known = [a["score"] for a in ax.values() if a["score"] is not None]
+        overall = round(sum(known) / len(known)) if known else None
+        cards[loc] = {"axes": ax, "overall": overall,
+                      "unknown_axes": [a for a in AXES
+                                       if ax[a]["status"] == "unknown"],
+                      "total_violations": sum(len(v) for v in axes.values())}
+    return {"scorecards": cards, "count": len(cards), "axes": list(AXES),
+            "note": "unknown axis = no measured evidence, not a zero score"}

platformforge/resources.py

@@ -0,0 +1,36 @@
+"""Bundled data resolution — one contract for checkout and installed wheel.
+
+Data directories (`rules/`, `knowledge/`, `contracts/`, `evals/`, `lab/`) live
+at the repository root in development. In the wheel they are force-included
+under ``platformforge/data/`` (see pyproject.toml), so an installed package is
+self-contained: every loader resolves through :func:`data_path` and never
+depends on the checkout being present.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+
+def data_path(*parts: str) -> Path:
+    """Resolve a bundled data path.
+
+    Order: ``platformforge/data/<parts>`` inside an installed wheel first,
+    then the repository root (development checkout / editable install where
+    no bundled ``data/`` tree exists inside the package).
+
+    ``platformforge/data/`` also exists in a checkout — it ships
+    ``portable_skills`` as regular package content — so the wheel probe
+    checks a force-included sentinel (``data/rules``) rather than ``data``
+    itself.
+    """
+    probe = parts if parts else ("rules",)
+    try:
+        pkg = resources.files("platformforge")
+        installed = pkg.joinpath("data", *probe)
+        if installed.is_dir() or installed.is_file():
+            return Path(str(pkg.joinpath("data", *parts)))
+    except (ModuleNotFoundError, TypeError, FileNotFoundError):
+        pass
+    return Path(__file__).resolve().parents[1].joinpath(*parts)

platformforge/risk/__init__.py

@@ -0,0 +1,5 @@
+"""Risk engine + criticality (prompt §130–131)."""
+
+from platformforge.risk.engine import assess_change
+
+__all__ = ["assess_change"]

platformforge/risk/engine.py

@@ -0,0 +1,95 @@
+"""Change-risk assessment — §130.
+
+Inputs are signals, each scored 0-3 and weighted. Output is a level with a
+full decomposition — never a bare number. Criticality is taken from
+*declared* signals (labels, owning findings, graph exposure); business
+criticality is never inferred from technology alone (§131).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+LEVELS = ("low", "medium", "high", "critical")
+
+# signal → (weight, scorer description)
+SIGNALS = {
+    "blast_radius": 3,        # # of impacted nodes per impact class
+    "criticality": 3,         # declared criticality of touched nodes
+    "production": 2,          # environment == production
+    "security_impact": 3,     # security findings in blast radius
+    "identity_impact": 3,     # IAM/principal changes
+    "network_exposure": 2,    # new public/exposed surface
+    "data_persistence": 2,    # touches db/bucket/volume
+    "availability_impact": 2, # touches workload/slo-bearing nodes
+    "cost_impact": 1,         # billed delta detected
+    "reversibility": 2,       # destructive/replacing change → 0
+    "test_coverage": 1,       # tests/verification present → lowers
+}
+
+_THRESHOLDS = [(8, "low"), (16, "medium"), (26, "high"), (10**9, "critical")]
+
+
+def _level(score: int) -> str:
+    for cap, name in _THRESHOLDS:
+        if score <= cap:
+            return name
+    return "critical"
+
+
+def assess_change(signals: dict[str, Any]) -> dict[str, Any]:
+    """signals: dict of declared values; unknown signals are *unresolved*,
+    scored 0 and listed — never silently assumed safe."""
+    unknown = {k for k in signals if k not in SIGNALS}
+    decomposition: dict[str, dict[str, Any]] = {}
+    total = 0
+    for sig, weight in SIGNALS.items():
+        v = signals.get(sig)
+        if v is None:
+            decomposition[sig] = {"value": "unresolved", "score": 0,
+                                  "weight": weight}
+            continue
+        if isinstance(v, bool):
+            # True = protective for reversibility/test_coverage; risk for rest
+            raw = (0 if v else 3) if sig in ("reversibility", "test_coverage") \
+                else (3 if v else 0)
+        elif isinstance(v, (int, float)):
+            raw = min(3, max(0, int(v)))
+        else:
+            raw = {"none": 0, "low": 1, "medium": 2, "high": 3,
+                   "critical": 3}.get(str(v).lower(), 0)
+        decomposition[sig] = {"value": v, "score": raw, "weight": weight}
+        total += raw * weight
+    unresolved = [s for s, d in decomposition.items()
+                  if d["value"] == "unresolved"]
+    # §103 — unknown ≠ low risk: unresolved signals don't zero the level,
+    # they flag confidence and can only raise the reported level, never
+    # lower it. A "low" with unresolved signals is a claim, not a fact.
+    confidence = round(1.0 - len(unresolved) / len(SIGNALS), 3)
+    if unresolved and _level(total) in ("low", "medium"):
+        note = ("risk is underreported: unresolved signals could "
+                "raise the level")
+    else:
+        note = ("criticality is taken from declared signals only; "
+                "absence of a signal lowers confidence, not safety")
+    return {
+        "level": _level(total),
+        "score": total,
+        "confidence": confidence,
+        "underreported": bool(unresolved and _level(total) != "critical"),
+        "decomposition": decomposition,
+        "unknown_signals": sorted(unknown),
+        "unresolved": unresolved,
+        "note": note,
+    }
+
+
+def criticality(node_attrs: dict[str, Any]) -> str:
+    """Declared criticality only — tier labels, never tech-inferred."""
+    for k in ("criticality", "tier", "criticality_tier"):
+        v = str(node_attrs.get(k) or "").lower()
+        if v in ("critical", "high", "medium", "low", "tier0", "tier1",
+                 "tier2", "tier3"):
+            return {"tier0": "critical", "tier1": "high",
+                    "tier2": "medium", "tier3": "low"}.get(v, v)
+    return "unresolved"

platformforge/risk/signals.py

@@ -0,0 +1,49 @@
+"""Derive §130 risk signals from facts + graph — declared inputs only.
+
+Every signal names its evidence. When evidence is absent the signal is
+left unresolved rather than assumed safe."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from platformforge.risk.engine import criticality
+
+_DATA_KINDS = {"database", "bucket", "volume", "cache", "queue"}
+_AVAIL_KINDS = {"workload", "slo", "load_balancer", "ingress"}
+_ID_KINDS = {"iam_principal", "role", "policy", "workload_identity",
+             "service_account"}
+_NET_KINDS = {"load_balancer", "ingress", "dns", "gateway", "route"}
+
+
+def signals_from_graph(graph: Any, node_ids: list[str],
+                       blast: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Map a blast-radius result + node attrs onto §130 signals."""
+    nodes = set(node_ids)
+    if blast:
+        for cls_nodes in blast.get("by_class", {}).values():
+            nodes.update(cls_nodes)
+    impacted = [graph.nodes[n] for n in nodes if n in graph.nodes] \
+        if hasattr(graph, "nodes") else []
+    crit = [criticality(n.attrs) for n in impacted]
+    kinds = {n.kind for n in impacted}
+    total = blast.get("impacted_total", 0) if blast else 0
+    sig: dict[str, Any] = {
+        "blast_radius": min(3, total // 3),
+        "criticality": ({"critical": 3, "high": 3, "medium": 2, "low": 1}
+                        .get(next((c for c in crit if c != "unresolved"),
+                                  "unresolved"))
+                        if impacted else None),
+        "security_impact": (bool(kinds & {"security_policy",
+                                         "admission_policy"})
+                            if impacted else None),
+        "identity_impact": bool(kinds & _ID_KINDS) if impacted else None,
+        "network_exposure": bool(kinds & _NET_KINDS) if impacted else None,
+        "data_persistence": bool(kinds & _DATA_KINDS) if impacted else None,
+        "availability_impact": bool(kinds & _AVAIL_KINDS)
+                           if impacted else None,
+    }
+    prod = [n for n in impacted
+            if str(n.attrs.get("env", "")).lower() in ("prod", "production")]
+    sig["production"] = bool(prod) if impacted else None
+    return sig