technical-debt-engine-runtime 0.1.0__py3-none-any.whl

tde_runtime/models.py

@@ -0,0 +1,70 @@
+"""Runtime-owned value objects. No capability or adapter behavior belongs here."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+
+class StageStatus(StrEnum):
+    SUCCESS = "SUCCESS"
+    FAILED = "FAILED"
+    BLOCKED = "BLOCKED"
+
+
+class RuntimeQualification(StrEnum):
+    READY = "RUNTIME_READY"
+    FAILED = "RUNTIME_FAILED"
+
+
+@dataclass(frozen=True)
+class RuntimeContext:
+    repository_root: Path
+    repository_id: str
+    candidate: dict[str, str]
+    configuration: dict[str, Any]
+    runtime_version: str
+    schema_version: str
+    execution_id: str
+    working_directory: Path
+    temporary_directory: Path
+    execution_options: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class StageResult:
+    identifier: str
+    inputs: dict[str, Any]
+    outputs: dict[str, Any]
+    status: StageStatus
+    result: str
+    started_at: str
+    finished_at: str
+
+    @property
+    def duration_ms(self) -> int:
+        start = datetime.fromisoformat(self.started_at)
+        finish = datetime.fromisoformat(self.finished_at)
+        return int((finish - start).total_seconds() * 1000)
+
+
+@dataclass(frozen=True)
+class RuntimeResult:
+    context: RuntimeContext
+    stages: tuple[StageResult, ...]
+    evidence: dict[str, Any]
+    validation: dict[str, Any]
+    qualification: RuntimeQualification
+    report: dict[str, Any]
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def serialise_context(context: RuntimeContext) -> dict[str, Any]:
+    data = asdict(context)
+    return {key: str(value) if isinstance(value, Path) else value for key, value in data.items()}

tde_runtime/policies/__init__.py

@@ -0,0 +1 @@
+"""Bundled, versioned Technical Debt Engine policies."""

tde_runtime/policies/generation-1.json

@@ -0,0 +1,18 @@
+{
+  "identifier": "tde.generation-1.default",
+  "version": "1.0.0",
+  "scope": "repository",
+  "owner": "TDE policy governance",
+  "description": "Default, language-independent Generation 1 qualification policy.",
+  "supportedCapabilities": ["code_size", "complexity", "maintainability", "dependency_health"],
+  "supportedSchemas": ["1.0.0"],
+  "supportedRuntimeVersions": ["0.1.0"],
+  "rules": [
+    {"id": "code_size.repository_lines", "type": "threshold", "metricKey": "code_size.code_lines", "direction": "greater_than", "warning": 10000, "blocking": 25000},
+    {"id": "complexity.maximum", "type": "threshold", "metricKey": "complexity.cyclomatic.maximum", "direction": "greater_than", "warning": 15, "blocking": 25},
+    {"id": "maintainability.minimum", "type": "threshold", "metricKey": "maintainability.index", "direction": "less_than", "warning": 50, "blocking": 30},
+    {"id": "dependency.count", "type": "threshold", "metricKey": "dependency.count", "direction": "greater_than", "warning": 100, "blocking": 250},
+    {"id": "critical.finding", "type": "finding_severity", "severity": "CRITICAL", "outcome": "FAIL"},
+    {"id": "comparison.regression", "type": "comparison_regression", "outcome": "FAIL"}
+  ]
+}

tde_runtime/policy.py

@@ -0,0 +1,202 @@
+"""Configuration-driven, versioned policy evaluation for qualification."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+import json
+from pathlib import Path
+from typing import Any, Iterable, Mapping
+
+
+POLICY_SCHEMA_VERSION = "1.0.0"
+POLICY_DECISIONS = ("PASS", "PASS_WITH_WARNINGS", "FAIL", "BLOCKED", "NOT_APPLICABLE")
+
+
+class PolicyError(ValueError):
+    """Raised when a policy cannot be loaded or is incompatible."""
+
+
+class PolicyEngine:
+    """Loads and evaluates policies without knowledge of Runtime stages or adapters."""
+
+    def __init__(self, policy_directories: Iterable[Path] | None = None) -> None:
+        bundled = Path(__file__).with_name("policies")
+        self._policy_directories = tuple(policy_directories) if policy_directories is not None else (bundled,)
+
+    def discover(self, additional_directories: Iterable[Path] = ()) -> tuple[dict[str, str], ...]:
+        entries: list[dict[str, str]] = []
+        for path in self._policy_files((*self._policy_directories, *additional_directories)):
+            policy = self._read(path)
+            self.validate(policy)
+            entries.append({"id": policy["identifier"], "version": policy["version"], "path": str(path)})
+        return tuple(entries)
+
+    def load(self, configuration: Mapping[str, Any], repository_root: Path,
+             runtime_version: str, schema_version: str) -> dict[str, Any]:
+        settings = dict(configuration.get("executionOptions", {}).get("policy", configuration.get("policy", {})))
+        directories = list(self._policy_directories)
+        # Later directories have higher precedence: bundled < workspace < repository.
+        for setting in (settings.get("workspace"), settings.get("repository")):
+            if setting:
+                candidate = Path(setting)
+                directories.append(candidate if candidate.is_absolute() else repository_root / candidate)
+        policies = [self._read(path) for path in self._policy_files(directories)]
+        for candidate in policies:
+            self.validate(candidate)
+        if not policies:
+            raise PolicyError("no policy is available")
+        policy_id = settings.get("id")
+        candidates = [item for item in policies if not policy_id or item["identifier"] == policy_id]
+        if not candidates:
+            raise PolicyError(f"requested policy is not available: {policy_id}")
+        policy = candidates[-1]
+        self.validate(policy)
+        self._validate_compatibility(policy, runtime_version, schema_version)
+        resolved = deepcopy(policy)
+        overrides = settings.get("overrides", {})
+        if not isinstance(overrides, dict):
+            raise PolicyError("policy.overrides must be an object")
+        for rule in resolved["rules"]:
+            configured = overrides.get(rule["id"], {})
+            if not isinstance(configured, dict):
+                raise PolicyError(f"override for {rule['id']} must be an object")
+            rule.update({key: value for key, value in configured.items() if key in {"enabled", "warning", "blocking", "outcome"}})
+        return resolved
+
+    def evaluate(self, policy: Mapping[str, Any], normalized: Mapping[str, Any],
+                 configuration: Mapping[str, Any]) -> dict[str, Any]:
+        measurements = list(normalized.get("measurements", []))
+        findings = list(normalized.get("findings", []))
+        results = list(normalized.get("capabilityResults", []))
+        limitations = [limitation for result in results for limitation in result.get("limitations", [])]
+        triggered: list[dict[str, Any]] = []
+        for rule in policy["rules"]:
+            if not rule.get("enabled", True):
+                continue
+            if rule["type"] == "threshold":
+                triggered.extend(self._threshold_matches(rule, measurements))
+            elif rule["type"] == "finding_severity":
+                triggered.extend(self._finding_matches(rule, findings))
+            elif rule["type"] == "capability":
+                triggered.extend(self._capability_matches(rule, results, configuration))
+            elif rule["type"] == "comparison_regression":
+                triggered.extend({"ruleId": rule["id"], "outcome": self._outcome(rule.get("outcome", "FAIL")),
+                                  "comparisonId": normalized.get("comparison", {}).get("comparisonId"),
+                                  "findingId": item, "affectedEvidence": {"comparisonId": normalized.get("comparison", {}).get("comparisonId")}}
+                                 for item in normalized.get("comparison", {}).get("regressions", []))
+        if any(item.get("blocking") is True for item in limitations):
+            triggered.append({"ruleId": "limitation.blocking", "outcome": "BLOCKED", "reason": "blocking limitation"})
+        decision = self._decision(triggered, measurements, findings, results)
+        return {
+            "policy": {key: policy[key] for key in ("identifier", "version", "scope", "owner")},
+            "decision": decision,
+            "decisionReason": self._decision_reason(decision, triggered),
+            "triggeredRules": triggered,
+            "thresholds": {rule["id"]: {key: rule[key] for key in ("warning", "blocking", "direction") if key in rule}
+                           for rule in policy["rules"] if rule["type"] == "threshold"},
+            "affectedCapabilities": sorted({item["capabilityId"] for item in triggered if item.get("capabilityId")} | {item["affectedCapability"] for item in triggered if item.get("affectedCapability")} ),
+            "qualificationReference": {"measurementIds": sorted(str(item.get("measurementId")) for item in measurements),
+                                         "findingIds": sorted(str(item.get("findingId")) for item in findings)},
+            "qualificationInputs": {"measurementCount": len(measurements), "findingCount": len(findings),
+                                     "capabilityResultCount": len(results), "limitationCount": len(limitations),
+                                     "configuration": dict(configuration)},
+        }
+
+    @staticmethod
+    def validate(policy: Mapping[str, Any]) -> None:
+        required = {"identifier", "version", "scope", "owner", "description", "supportedCapabilities",
+                    "supportedSchemas", "supportedRuntimeVersions", "rules"}
+        missing = required - set(policy)
+        if missing:
+            raise PolicyError(f"policy is missing required fields: {sorted(missing)}")
+        if not all(isinstance(policy[key], str) and policy[key] for key in ("identifier", "version", "scope", "owner", "description")):
+            raise PolicyError("policy identity fields must be non-empty strings")
+        if not all(isinstance(policy[key], list) and all(isinstance(item, str) for item in policy[key])
+                   for key in ("supportedCapabilities", "supportedSchemas", "supportedRuntimeVersions")):
+            raise PolicyError("policy compatibility fields must be string arrays")
+        if not isinstance(policy["rules"], list):
+            raise PolicyError("policy.rules must be an array")
+        identifiers: set[str] = set()
+        for rule in policy["rules"]:
+            if not isinstance(rule, dict) or not isinstance(rule.get("id"), str) or rule.get("type") not in {"threshold", "finding_severity", "capability", "comparison_regression"}:
+                raise PolicyError("every policy rule needs an id and supported type")
+            if rule["id"] in identifiers:
+                raise PolicyError(f"policy rule identifiers must be unique: {rule['id']}")
+            identifiers.add(rule["id"])
+
+    @staticmethod
+    def _policy_files(directories: Iterable[Path]) -> tuple[Path, ...]:
+        return tuple(path for directory in directories if directory.is_dir() for path in sorted(directory.glob("*.json")))
+
+    @staticmethod
+    def _read(path: Path) -> dict[str, Any]:
+        try:
+            value = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise PolicyError(f"invalid policy {path}: {error}") from error
+        if not isinstance(value, dict):
+            raise PolicyError(f"policy {path} must be an object")
+        return value
+
+    @staticmethod
+    def _validate_compatibility(policy: Mapping[str, Any], runtime_version: str, schema_version: str) -> None:
+        if runtime_version not in policy["supportedRuntimeVersions"]:
+            raise PolicyError("policy is incompatible with this runtime version")
+        if schema_version not in policy["supportedSchemas"]:
+            raise PolicyError("policy is incompatible with this schema version")
+
+    @staticmethod
+    def _outcome(value: str) -> str:
+        aliases = {"WARNING": "PASS_WITH_WARNINGS", "BLOCKING": "FAIL"}
+        outcome = aliases.get(value, value)
+        if outcome not in POLICY_DECISIONS:
+            raise PolicyError(f"unsupported policy outcome: {value}")
+        return outcome
+
+    def _threshold_matches(self, rule: Mapping[str, Any], measurements: list[Mapping[str, Any]]) -> list[dict[str, Any]]:
+        matches: list[dict[str, Any]] = []
+        for measurement in measurements:
+            if measurement.get("metricKey") != rule.get("metricKey") or not isinstance(measurement.get("value"), (int, float)):
+                continue
+            value, direction = measurement["value"], rule.get("direction", "greater_than")
+            def reached(threshold: Any) -> bool:
+                return threshold is not None and ((direction == "greater_than" and value >= threshold) or (direction == "less_than" and value <= threshold))
+            threshold, outcome = (rule.get("blocking"), "FAIL") if reached(rule.get("blocking")) else (rule.get("warning"), "PASS_WITH_WARNINGS") if reached(rule.get("warning")) else (None, None)
+            if outcome:
+                matches.append({"ruleId": rule["id"], "outcome": outcome, "metricKey": rule["metricKey"], "measuredValue": value,
+                                "threshold": threshold, "affectedCapability": measurement.get("capabilityId"),
+                                "affectedEvidence": {"measurementId": measurement.get("measurementId"), "targetEntityId": measurement.get("targetEntityId")}})
+        return matches
+
+    def _finding_matches(self, rule: Mapping[str, Any], findings: list[Mapping[str, Any]]) -> list[dict[str, Any]]:
+        outcome = self._outcome(rule.get("outcome", "PASS_WITH_WARNINGS"))
+        return [{"ruleId": rule["id"], "outcome": outcome, "findingId": finding.get("findingId"), "severity": rule.get("severity"),
+                 "affectedCapability": finding.get("capabilityId"), "affectedEvidence": {"findingId": finding.get("findingId")}}
+                for finding in findings if finding.get("severity") == rule.get("severity")]
+
+    def _capability_matches(self, rule: Mapping[str, Any], results: list[Mapping[str, Any]], configuration: Mapping[str, Any]) -> list[dict[str, Any]]:
+        capability_id = rule.get("capabilityId")
+        configured = configuration.get("executionOptions", {}).get("capabilities", {}).get(capability_id, {})
+        present = any(result.get("capabilityId") == capability_id for result in results)
+        required = rule.get("required", rule.get("enabled") is True)
+        if not required or present:
+            return []
+        return [{"ruleId": rule["id"], "outcome": self._outcome(rule.get("outcome", "BLOCKED")), "capabilityId": capability_id,
+                 "reason": "required capability evidence is missing", "affectedEvidence": {"capabilityId": capability_id, "configured": configured}}]
+
+    @staticmethod
+    def _decision(triggered: list[Mapping[str, Any]], measurements: list[Mapping[str, Any]], findings: list[Mapping[str, Any]], results: list[Mapping[str, Any]]) -> str:
+        outcomes = {item["outcome"] for item in triggered}
+        if "BLOCKED" in outcomes:
+            return "BLOCKED"
+        if "FAIL" in outcomes:
+            return "FAIL"
+        if "PASS_WITH_WARNINGS" in outcomes:
+            return "PASS_WITH_WARNINGS"
+        return "PASS" if measurements or findings or results else "NOT_APPLICABLE"
+
+    @staticmethod
+    def _decision_reason(decision: str, triggered: list[Mapping[str, Any]]) -> str:
+        if not triggered:
+            return "no policy rule was triggered" if decision == "PASS" else "no applicable capability evidence is available"
+        return f"{len(triggered)} policy rule(s) triggered; highest outcome is {decision}"

tde_runtime/query.py

@@ -0,0 +1,36 @@
+"""Versioned, read-only query layer over canonical evidence."""
+from __future__ import annotations
+from hashlib import sha256
+from time import perf_counter
+from typing import Any, Mapping
+
+QUERY_LANGUAGE_VERSION = "1.0.0"
+
+class QueryEngine:
+    def execute(self, evidence: Mapping[str, Any], query: Mapping[str, Any]) -> dict[str, Any]:
+        started = perf_counter()
+        resource = query.get("resource", "repositories")
+        comparisons = list(query.get("comparisons", []))
+        comparison_findings = [
+            {"comparisonId": item.get("comparisonId"), **transition}
+            for item in comparisons for transition in item.get("comparison", {}).get("findingTransitions", [])
+        ]
+        collections = {"repositories": [evidence.get("repository", {})], "capabilities": evidence.get("capabilityResults", []), "metrics": evidence.get("measurements", []), "findings": evidence.get("findings", []), "policies": [evidence.get("policyEvidence", {})], "qualification": [evidence.get("policyEvidence", {})], "baselines": query.get("baselines", []), "comparisons": comparisons, "comparison_findings": comparison_findings, "trends": query.get("trends", [])}
+        if resource not in collections: raise ValueError(f"unsupported query resource: {resource}")
+        rows = list(collections[resource])
+        for key, expected in query.get("filter", {}).items(): rows = [row for row in rows if str(row.get(key)) == str(expected)]
+        sort = query.get("sort")
+        if sort: rows.sort(key=lambda row: str(row.get(sort, "")), reverse=query.get("descending", False))
+        aggregate = query.get("aggregate")
+        if aggregate == "count": rows = [{"count": len(rows)}]
+        group = query.get("groupBy")
+        if group:
+            grouped: dict[str, int] = {}
+            for row in rows: grouped[str(row.get(group, ""))] = grouped.get(str(row.get(group, "")), 0) + 1
+            rows = [{group: key, "count": value} for key, value in sorted(grouped.items())]
+        projection = query.get("projection")
+        if projection: rows = [{key: row.get(key) for key in projection} for row in rows]
+        offset, limit = int(query.get("offset", 0)), query.get("limit")
+        rows = rows[offset: offset + int(limit) if limit is not None else None]
+        identity = sha256(str(sorted(query.items())).encode()).hexdigest()[:16]
+        return {"queryEvidence": {"queryId": f"query.{identity}", "languageVersion": QUERY_LANGUAGE_VERSION, "resource": resource, "execution": "READ_ONLY", "durationMs": int((perf_counter()-started)*1000), "resultCount": len(rows), "limitations": []}, "results": rows}

tde_runtime/registries.py

@@ -0,0 +1,21 @@
+"""Registry boundaries. Entries arrive only in later capability/adapter increments."""
+
+from __future__ import annotations
+
+
+class CapabilityRegistry:
+    def discover(self) -> tuple[object, ...]:
+        return ({"id": "code_size", "version": "0.1.0", "status": "VALIDATED"},{"id":"complexity","version":"0.1.0","status":"VALIDATED"},{"id":"maintainability","version":"0.1.0","status":"VALIDATED"},{"id":"dependency_health","version":"0.1.0","status":"VALIDATED"})
+
+
+class AdapterRegistry:
+    def discover(self) -> tuple[object, ...]:
+        return ({"id": "code_size.cloc", "version": "0.1.0", "analyzer": "cloc"},{"id":"complexity.radon","version":"0.1.0","analyzer":"radon"})
+
+
+class PolicyRegistry:
+    """Discovery boundary for configuration-driven policy files."""
+
+    def discover(self) -> tuple[object, ...]:
+        from .policy import PolicyEngine
+        return PolicyEngine().discover()

tde_runtime/release_bundle.py

@@ -0,0 +1,34 @@
+"""Immutable manifest and integrity checks for a certified release bundle."""
+from __future__ import annotations
+
+from hashlib import sha256
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+
+def digest(path: Path) -> str:
+    hasher = sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            hasher.update(chunk)
+    return "sha256:" + hasher.hexdigest()
+
+
+def canonical(value: Mapping[str, Any]) -> bytes:
+    return (json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True) + "\n").encode("utf-8")
+
+
+def verify(root: str | Path) -> dict[str, Any]:
+    directory = Path(root)
+    try:
+        manifest = json.loads((directory / "bundle-manifest.json").read_text(encoding="utf-8"))
+        sums = (directory / "SHA256SUMS").read_bytes()
+        expected = {line.split(maxsplit=1)[1]: "sha256:" + line.split(maxsplit=1)[0] for line in sums.decode().splitlines() if line}
+        valid_files = bool(expected) and all((directory / name).is_file() and digest(directory / name) == value for name, value in expected.items())
+        complete = {"wheel", "source_distribution", "oci_archive", "release_manifest", "release_qualification", "release_certification", "docker_provenance"}.issubset({item["kind"] for item in manifest["contents"]})
+        valid = (manifest.get("schemaId") == "tde.certified-release-bundle" and valid_files and complete
+                 and manifest.get("bundleChecksum") == "sha256:" + sha256(sums).hexdigest())
+    except (OSError, ValueError, KeyError, IndexError, json.JSONDecodeError):
+        manifest, valid, complete = {}, False, False
+    return {"bundle": manifest, "integrity": valid, "complete": complete}

tde_runtime/release_candidate.py

@@ -0,0 +1,75 @@
+"""Fail-closed validation for immutable mainline release-candidate snapshots."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import re
+import subprocess
+from pathlib import Path
+from typing import Any
+
+
+SHA = re.compile(r"^[0-9a-f]{40}$")
+VERSION = re.compile(r"^\d+\.\d+\.\d+(?:[A-Za-z0-9.+-]+)?$")
+
+
+def _git(root: Path, *arguments: str) -> tuple[bool, str]:
+    result = subprocess.run(["git", "-C", str(root), *arguments], text=True,
+                            stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False)
+    return result.returncode == 0, result.stdout.strip()
+
+
+def validate_snapshot(root: str | Path, candidate_sha: str, version: str, profile: str,
+                      main_ref: str = "main") -> dict[str, Any]:
+    """Return an independently-verifiable candidate record or fail closed.
+
+    A candidate is a reference only: it creates neither a tag nor source changes.
+    """
+    repository = Path(root).resolve()
+    if not SHA.fullmatch(candidate_sha):
+        raise ValueError("candidate SHA must be an exact lowercase 40-character Git SHA")
+    if not VERSION.fullmatch(version):
+        raise ValueError("candidate version is invalid")
+    if not profile:
+        raise ValueError("candidate release profile is required")
+    exists, object_type = _git(repository, "cat-file", "-t", candidate_sha)
+    if not exists or object_type != "commit":
+        raise ValueError("candidate SHA does not identify a commit")
+    main_exists, _ = _git(repository, "rev-parse", "--verify", f"{main_ref}^{{commit}}")
+    if not main_exists:
+        raise ValueError(f"mainline reference {main_ref!r} is unavailable")
+    ancestor, _ = _git(repository, "merge-base", "--is-ancestor", candidate_sha, main_ref)
+    if not ancestor:
+        raise ValueError("candidate SHA is not an ancestor of main; sibling and unmerged candidates are prohibited")
+    clean, status = _git(repository, "status", "--porcelain")
+    if not clean or status:
+        raise ValueError("candidate repository must be clean")
+    main_sha_ok, main_sha = _git(repository, "rev-parse", f"{main_ref}^{{commit}}")
+    source_ref_ok, source_ref = _git(repository, "branch", "--show-current")
+    actor_ok, actor = _git(repository, "config", "user.email")
+    return {
+        "schemaId": "tde.mainline-candidate-snapshot",
+        "schemaVersion": "1.0.0",
+        "candidateSha": candidate_sha,
+        "version": version,
+        "profile": profile,
+        "sourceBranch": source_ref if source_ref_ok and source_ref else main_ref,
+        "mainlineSha": main_sha if main_sha_ok else None,
+        "actor": actor if actor_ok and actor else "github-actions",
+        "createdAt": datetime.now(timezone.utc).replace(microsecond=0).isoformat(),
+        "ancestryVerified": True,
+        "immutable": True,
+        "publicationSource": "exact candidate SHA only",
+    }
+
+
+def candidate_superseded(candidate_sha: str, changed_paths: list[str]) -> bool:
+    """Classify later intended-release changes without changing candidate identity."""
+    if not SHA.fullmatch(candidate_sha):
+        raise ValueError("candidate SHA must be exact")
+    administrative_prefixes = ("docs/history/prompts/",)
+    administrative_files = {
+        "ENGINEERING_STATUS.md", "REPOSITORY_STATUS.md", "MANAGEMENT_SUMMARY.md",
+        "PROMPT_INDEX.md", "RELEASE_PUBLICATION.md",
+    }
+    return any(path not in administrative_files and not path.startswith(administrative_prefixes)
+               for path in changed_paths)

tde_runtime/release_certification.py

@@ -0,0 +1,87 @@
+"""Canonical, evidence-only Internal Release certification."""
+from __future__ import annotations
+
+from hashlib import sha256
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+
+def _canonical(value: object) -> bytes:
+    return (json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True) + "\n").encode("utf-8")
+
+
+def _read(path: str | Path) -> tuple[dict[str, Any] | None, str | None]:
+    try:
+        raw = Path(path).read_bytes()
+        value = json.loads(raw)
+        return (value if isinstance(value, dict) else None), "sha256:" + sha256(raw).hexdigest()
+    except (OSError, ValueError, json.JSONDecodeError):
+        return None, None
+
+
+class ReleaseCertification:
+    """Certify a qualified candidate by validating, never regenerating, evidence."""
+
+    def certify(self, qualification_path: str | Path, report_output: str | Path) -> dict[str, Any]:
+        qualification, digest = _read(qualification_path)
+        limitations: list[str] = []
+        if qualification is None:
+            limitations.append("release qualification evidence is missing or invalid JSON")
+            qualification = {}
+        elif isinstance(qualification.get("releaseQualificationEvidence"), dict):
+            qualification = qualification["releaseQualificationEvidence"]
+
+        candidate = qualification.get("releaseCandidate", {})
+        artifacts = qualification.get("artifacts", [])
+        manifest = qualification.get("manifest", {})
+        runtime = qualification.get("runtimeEvidence", {})
+        checks = qualification.get("checks", {})
+        release_evidence_reference, release_evidence_digest, release_evidence_integrity = _release_evidence_check(qualification, candidate, checks)
+        evidence_checks = {
+            "candidateIdentity": isinstance(candidate.get("sha"), str) and len(candidate["sha"]) == 40,
+            "artifactIdentity": isinstance(artifacts, list) and bool(artifacts) and all(item.get("digest", "").startswith("sha256:") for item in artifacts if isinstance(item, dict)),
+            "artifactIntegrity": bool(checks.get("artifactIntegrity")),
+            "artifactReproducibility": bool(checks.get("buildReproducibility")),
+            "workflowIntegrity": qualification.get("trustedDelivery", {}).get("decision") == "PASS",
+            "softwareAssurance": qualification.get("softwareAssurance", {}).get("decision") == "PASS",
+            "trustedDelivery": qualification.get("trustedDelivery", {}).get("decision") == "PASS",
+            "releaseQualification": qualification.get("decision") == "RELEASE_QUALIFIED" and qualification.get("releaseDecision") == "READY",
+            "buildProvenance": bool(checks.get("buildReproducibility")),
+            "canonicalEvidence": bool(digest) and bool(manifest.get("integrity")),
+            "releaseEvidence": release_evidence_integrity,
+            "runtimeQualification": (runtime.get("validation", {}).get("status") == "VALID"
+                                     and runtime.get("runtimeQualification") == "QUALIFIED"),
+            "policyEvidence": runtime.get("policyDecision") in {"PASS", "PASS_WITH_WARNINGS"},
+            "dockerArtifact": bool(checks.get("dockerArtifact", True)),
+        }
+        for name, valid in evidence_checks.items():
+            if not valid:
+                limitations.append(f"required {name} evidence is unavailable, invalid, or did not pass")
+        decision = "RELEASE_CERTIFIED" if all(evidence_checks.values()) else "RELEASE_NOT_CERTIFIED"
+        report = {
+            "schemaId": "tde.release-certification", "schemaVersion": "1.0.0",
+            "candidate": candidate, "repository": candidate.get("repository"),
+            "certificationInputs": {"releaseQualification": {"path": str(qualification_path), "digest": digest},
+                                    "softwareAssuranceId": qualification.get("softwareAssurance", {}).get("assuranceId"),
+                                    "trustedDeliveryId": qualification.get("trustedDelivery", {}).get("trustedDeliveryId"),
+                                    "manifest": manifest, "artifacts": artifacts, "runtimeEvidence": runtime,
+                                    "releaseEvidence": {"reference": release_evidence_reference, "digest": release_evidence_digest}},
+            "checks": evidence_checks, "decision": decision, "limitations": limitations,
+            "decisionRationale": "All required canonical evidence passed." if decision == "RELEASE_CERTIFIED" else "Certification is fail-closed because required canonical evidence did not pass.",
+        }
+        report["certificationId"] = "release-certification.sha256." + sha256(_canonical(report)).hexdigest()
+        output = Path(report_output).resolve(); output.parent.mkdir(parents=True, exist_ok=True); output.write_bytes(_canonical(report))
+        return {**report, "report": {"path": str(output), "digest": "sha256:" + sha256(output.read_bytes()).hexdigest(), "integrity": True}}
+
+
+def _release_evidence_check(qualification: Mapping[str, Any], candidate: Mapping[str, Any], checks: Mapping[str, Any]) -> tuple[dict[str, Any], str | None, bool]:
+    reference = qualification.get("releaseEvidence", {})
+    if not isinstance(reference, dict): return {}, None, False
+    evidence, digest = _read(reference.get("path", ""))
+    if not evidence: return reference, digest, False
+    unsigned = {key: value for key, value in evidence.items() if key != "releaseEvidenceId"}
+    expected = "release-evidence.sha256." + sha256(_canonical(unsigned)).hexdigest()
+    valid = digest == reference.get("digest") and evidence.get("releaseEvidenceId") == reference.get("id")
+    valid = valid and evidence.get("releaseEvidenceId") == expected and evidence.get("candidate") == candidate
+    return reference, digest, valid and evidence.get("releaseQualification", {}).get("checks") == checks