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

tde_runtime/code_size.py

@@ -0,0 +1,49 @@
+"""Code Size capability adapter backed by an explicitly installed cloc executable."""
+from __future__ import annotations
+import json, re, shutil, subprocess
+from collections import defaultdict
+from hashlib import sha256
+from pathlib import Path
+from typing import Any
+
+CAPABILITY_ID = "code_size"
+CAPABILITY_VERSION = "0.1.0"
+ADAPTER_ID = "code_size.cloc"
+ADAPTER_VERSION = "0.1.0"
+MINIMUM_ANALYZER_VERSION = (2, 10)
+
+def classify(path: str) -> str:
+    value = path.replace("\\", "/").lower()
+    if value.startswith(("vendor/", "third_party/", "node_modules/")) or any(part in value for part in ("/vendor/", "/third_party/", "/node_modules/")): return "VENDOR"
+    if value.startswith(("generated/", "build/", "dist/")) or any(part in value for part in ("/generated/", "/build/", "/dist/")): return "GENERATED"
+    if value.startswith(("tests/", "test/", "spec/")) or "/tests/" in value: return "TEST"
+    if value.startswith(("docs/", "documentation/")) or value.endswith((".md", ".rst", ".txt")): return "DOCUMENTATION"
+    if value.endswith((".yml", ".yaml", ".json", ".toml", ".ini")): return "CONFIGURATION"
+    return "SOURCE"
+
+def analyze(root: Path, timeout: int = 60) -> dict[str, Any]:
+    executable = shutil.which("cloc")
+    if not executable:
+        return {"status":"BLOCKED", "limitations":[{"id":"analyzer.cloc.unavailable","description":"cloc is not on PATH; install cloc 2.10+.","cause":"analyzer unavailable"}]}
+    try:
+        version = subprocess.run([executable, "--version"], capture_output=True, text=True, timeout=timeout, check=True).stdout.strip()
+        match = re.search(r"(\d+)\.(\d+)", version)
+        if not match or tuple(map(int, match.groups())) < MINIMUM_ANALYZER_VERSION:
+            return {"status":"BLOCKED", "limitations":[{"id":"analyzer.cloc.unsupported_version","description":f"cloc {MINIMUM_ANALYZER_VERSION[0]}.{MINIMUM_ANALYZER_VERSION[1]}+ is required; found {version or 'unknown'}.","cause":"unsupported analyzer version"}]}
+        result = subprocess.run([executable, "--json", "--by-file", "--quiet", str(root)], capture_output=True, text=True, timeout=timeout, check=True)
+        raw = result.stdout
+        data = json.loads(raw)
+    except (subprocess.TimeoutExpired, subprocess.CalledProcessError, json.JSONDecodeError) as error:
+        return {"status":"BLOCKED", "limitations":[{"id":"analyzer.cloc.failed","description":str(error),"cause":"analyzer execution failed"}]}
+    files, languages = [], defaultdict(lambda: {"files":0,"code":0,"comment":0,"blank":0})
+    totals = defaultdict(int)
+    entries = ((name, item) for name, item in data.items() if name not in {"header", "SUM"})
+    for name, item in sorted(entries):
+        relative = Path(name).resolve().relative_to(root.resolve()).as_posix()
+        category, language = classify(relative), item.get("language", "Unknown")
+        record = {"path":relative,"classification":category,"language":language,"physical":item["blank"]+item["comment"]+item["code"],"code":item["code"],"comment":item["comment"],"blank":item["blank"]}
+        files.append(record); bucket = languages[language]; bucket["files"] += 1; bucket["code"] += item["code"]; bucket["comment"] += item["comment"]; bucket["blank"] += item["blank"]
+        for key in ("code","comment","blank"): totals[key] += item[key]
+        totals["files"] += 1; totals[category.lower()] += item["code"]
+    source = totals["source"]; ratio = totals["test"] / source if source else 0
+    return {"status":"VALID","adapter":{"id":ADAPTER_ID,"version":ADAPTER_VERSION},"analyzer":{"id":"cloc","version":version},"rawOutput":raw,"rawOutputHash":"sha256:"+sha256(raw.encode()).hexdigest(),"files":files,"languages":dict(sorted(languages.items())),"totals":dict(totals),"testToSourceRatio":ratio,"limitations":[{"id":"code_size.logical_lines.unavailable","description":"cloc does not provide logical line counts.","cause":"analyzer limitation"}]}

tde_runtime/complexity.py

@@ -0,0 +1,92 @@
+"""Python cyclomatic-complexity adapter backed by the installed Radon CLI."""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import re
+import shutil
+import subprocess
+from hashlib import sha256
+from pathlib import Path
+from typing import Any, Mapping
+
+CAPABILITY_ID = "complexity"
+CAPABILITY_VERSION = "0.1.0"
+ADAPTER_ID = "complexity.radon"
+ADAPTER_VERSION = "0.1.0"
+MINIMUM_ANALYZER_VERSION = (6, 0)
+
+def _items(value: object) -> tuple[str, ...]:
+    if isinstance(value, str):
+        return tuple(item.strip() for item in value.split(",") if item.strip())
+    if isinstance(value, (list, tuple)) and all(isinstance(item, str) for item in value):
+        return tuple(value)
+    return ()
+
+def _relative(root: Path, name: str) -> str:
+    path = Path(name)
+    if not path.is_absolute():
+        return path.as_posix()
+    try:
+        return path.resolve().relative_to(root.resolve()).as_posix()
+    except ValueError:
+        # Radon is expected to report files below the selected root.  Never
+        # preserve an absolute host path in evidence if an analyzer violates
+        # that expectation.
+        return path.name
+
+
+def _portable_native_output(root: Path, data: Mapping[str, Any]) -> tuple[str, dict[str, Any]]:
+    """Return a stable Radon projection without runner-specific paths."""
+    normalized = {_relative(root, path): symbols for path, symbols in data.items()}
+    ordered = {path: normalized[path] for path in sorted(normalized)}
+    return json.dumps(ordered, sort_keys=True, separators=(",", ":")), ordered
+
+def _thresholds(configuration: Mapping[str, Any]) -> dict[str, int]:
+    supplied = configuration.get("thresholds", {})
+    if not isinstance(supplied, Mapping): supplied = {}
+    values = {"high": 11, "veryHigh": 21, "critical": 41}
+    for key in values:
+        if key in supplied:
+            if not isinstance(supplied[key], int) or supplied[key] < 1:
+                raise ValueError(f"complexity threshold {key} must be a positive integer")
+            values[key] = supplied[key]
+    if not values["high"] < values["veryHigh"] < values["critical"]:
+        raise ValueError("complexity thresholds must satisfy high < veryHigh < critical")
+    return values
+
+def analyze(root: Path, timeout: int = 60, configuration: Mapping[str, Any] | None = None) -> dict[str, Any]:
+    """Execute Radon deterministically and retain native output for evidence."""
+    configuration = configuration or {}
+    executable = shutil.which("radon")
+    if not executable:
+        return {"status":"BLOCKED", "limitations":[{"id":"analyzer.radon.unavailable","description":"radon is not on PATH; install Radon 6.0+.","cause":"analyzer unavailable"}]}
+    try:
+        version = subprocess.run([executable, "--version"], capture_output=True, text=True, timeout=timeout, check=True).stdout.strip()
+        match = re.search(r"(\d+)\.(\d+)", version)
+        if not match or tuple(map(int, match.groups())) < MINIMUM_ANALYZER_VERSION:
+            return {"status":"BLOCKED", "limitations":[{"id":"analyzer.radon.unsupported_version","description":f"Radon 6.0+ is required; found {version or 'unknown'}.","cause":"unsupported analyzer version"}]}
+        completed = subprocess.run([executable, "cc", "--json", str(root)], capture_output=True, text=True, timeout=timeout, check=True)
+        raw, data = _portable_native_output(root, json.loads(completed.stdout))
+    except (FileNotFoundError, subprocess.TimeoutExpired, subprocess.CalledProcessError, json.JSONDecodeError) as error:
+        return {"status":"BLOCKED", "limitations":[{"id":"analyzer.radon.failed","description":str(error),"cause":"analyzer execution failed"}]}
+    try:
+        thresholds = _thresholds(configuration)
+    except ValueError as error:
+        return {"status":"BLOCKED", "limitations":[{"id":"complexity.configuration.invalid","description":str(error),"cause":"invalid configuration"}]}
+    defaults = (".git/**", ".tde/**", "build/**", "dist/**", "*.egg-info/**", ".venv/**", "venv/**", "__pycache__/**")
+    ignored_paths, ignored_symbols = defaults + _items(configuration.get("ignoredPaths")), set(_items(configuration.get("ignoredSymbols")))
+    symbols, skipped = [], 0
+    for native_path, native_symbols in sorted(data.items()):
+        path = _relative(root, native_path)
+        if any(fnmatch.fnmatch(path, pattern) or path.startswith(pattern.rstrip("/")+"/") for pattern in ignored_paths):
+            skipped += len(native_symbols); continue
+        for native in sorted(native_symbols, key=lambda item: (item.get("lineno", 0), item.get("name", ""))):
+            if native.get("name") in ignored_symbols:
+                skipped += 1; continue
+            symbols.append({"path":path,"language":"Python","name":native["name"],"type":native.get("type","symbol"),"line":native.get("lineno"),"endLine":native.get("endline"),"complexity":native["complexity"]})
+    limitations=[]
+    if skipped: limitations.append({"id":"complexity.configuration.ignored","description":f"{skipped} symbol(s) were excluded by Complexity configuration.","cause":"configured exclusion"})
+    if not symbols: limitations.append({"id":"complexity.python.no_symbols","description":"Radon found no supported Python symbols after exclusions.","cause":"analyzer capability limitation"})
+    return {"status":"VALID","adapter":{"id":ADAPTER_ID,"version":ADAPTER_VERSION},"analyzer":{"id":"radon","version":version},"rawOutput":raw,"rawOutputHash":"sha256:"+sha256(raw.encode()).hexdigest(),"symbols":symbols,"thresholds":thresholds,"limitations":limitations}

tde_runtime/configuration.py

@@ -0,0 +1,112 @@
+"""Canonical Runtime configuration loading and repository discovery."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from hashlib import sha256
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+
+def _scalar(value: str) -> Any:
+    value = value.strip()
+    if value in {"true", "True"}:
+        return True
+    if value in {"false", "False"}:
+        return False
+    if value in {"null", "Null", "~"}:
+        return None
+    if value.startswith(("\"", "'")) and value.endswith(("\"", "'")):
+        return value[1:-1]
+    try:
+        return int(value)
+    except ValueError:
+        return value
+
+
+def _parse_yaml(contents: str) -> dict[str, Any]:
+    """Parse the small mapping-only .tde.yml contract without a runtime dependency."""
+    root: dict[str, Any] = {}
+    stack: list[tuple[int, dict[str, Any]]] = [(-1, root)]
+    for raw in contents.splitlines():
+        if not raw.strip() or raw.lstrip().startswith("#"):
+            continue
+        indent = len(raw) - len(raw.lstrip(" "))
+        key, separator, value = raw.strip().partition(":")
+        if not separator or not key:
+            raise ValueError(".tde.yml supports mappings only")
+        while stack[-1][0] >= indent:
+            stack.pop()
+        parent = stack[-1][1]
+        if value.strip():
+            parent[key] = _scalar(value)
+        else:
+            nested: dict[str, Any] = {}
+            parent[key] = nested
+            stack.append((indent, nested))
+    return root
+
+
+@dataclass(frozen=True)
+class RuntimeConfiguration:
+    schema_version: str = "1.0.0"
+    execution_options: dict[str, Any] | None = None
+
+    @classmethod
+    def load(cls, values: Mapping[str, Any] | None = None) -> "RuntimeConfiguration":
+        values = {} if values is None else dict(values)
+        allowed = {"schemaVersion", "executionOptions", "capabilities", "policy", "baseline", "trend"}
+        unknown = set(values) - allowed
+        if unknown:
+            raise ValueError(f"unsupported runtime configuration: {sorted(unknown)}")
+        schema_version = values.get("schemaVersion", "1.0.0")
+        if schema_version != "1.0.0":
+            raise ValueError("unsupported configuration schema version")
+        options = values.get("executionOptions", {})
+        if not isinstance(options, dict):
+            raise ValueError("executionOptions must be an object")
+        resolved: dict[str, Any] = dict(options)
+        for key in ("capabilities", "policy", "baseline", "trend"):
+            value = values.get(key, resolved.get(key, {}))
+            if not isinstance(value, dict):
+                raise ValueError(f"{key} must be an object")
+            resolved[key] = value
+        return cls(schema_version=schema_version, execution_options=resolved)
+
+    @classmethod
+    def discover(cls, repository_root: str | Path, explicit_path: str | Path | None = None) -> "RuntimeConfiguration":
+        path = Path(explicit_path) if explicit_path else Path(repository_root) / ".tde.yml"
+        if not path.is_file():
+            if explicit_path:
+                raise ValueError(f"configuration file does not exist: {path}")
+            return cls.load()
+        try:
+            contents = path.read_text(encoding="utf-8")
+            try:
+                values = json.loads(contents)
+            except json.JSONDecodeError:
+                values = _parse_yaml(contents)
+        except (OSError, ValueError) as error:
+            raise ValueError(f"invalid configuration {path}: {error}") from error
+        if not isinstance(values, dict):
+            raise ValueError("configuration root must be an object")
+        return cls.load(values)
+
+    def with_capability(self, identifier: str, enabled: bool = True) -> "RuntimeConfiguration":
+        values = self.as_dict()
+        capabilities = dict(values["executionOptions"].get("capabilities", {}))
+        existing = capabilities.get(identifier, {})
+        if not isinstance(existing, dict):
+            raise ValueError(f"capability configuration for {identifier} must be an object")
+        capabilities[identifier] = {**existing, "enabled": enabled}
+        values["capabilities"] = capabilities
+        values["executionOptions"].pop("capabilities", None)
+        return self.load(values)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {"schemaVersion": self.schema_version, "executionOptions": self.execution_options or {}}
+
+    def digest(self) -> str:
+        canonical = json.dumps(self.as_dict(), sort_keys=True, separators=(",", ":"))
+        return f"sha256:{sha256(canonical.encode()).hexdigest()}"

tde_runtime/dependency_health.py

@@ -0,0 +1,23 @@
+"""Declarative dependency inventory adapter; does not execute package managers."""
+from __future__ import annotations
+import json, tomllib
+from pathlib import Path
+from typing import Any
+CAPABILITY_ID="dependency_health"; CAPABILITY_VERSION="0.1.0"
+def discover(root: Path) -> dict[str, Any]:
+    inventory=[]
+    requirements=root/"requirements.txt"
+    if requirements.exists():
+        for line in requirements.read_text().splitlines():
+            name=line.split("==")[0].strip()
+            if name and not name.startswith("#"): inventory.append({"identifier":f"pypi:{name}","displayName":name,"ecosystem":"Python","packageManager":"requirements.txt","declaredVersion":line.partition("==")[2] or None,"lockState":"DECLARED"})
+    pyproject=root/"pyproject.toml"
+    if pyproject.exists():
+        data=tomllib.loads(pyproject.read_text()); deps=data.get("project",{}).get("dependencies",[])
+        for dep in deps:
+            name=dep.split()[0].split(">")[0].split("=")[0]; inventory.append({"identifier":f"pypi:{name}","displayName":name,"ecosystem":"Python","packageManager":"pyproject.toml","declaredVersion":dep,"lockState":"DECLARED"})
+    package=root/"package.json"
+    if package.exists():
+        data=json.loads(package.read_text())
+        for name,version in data.get("dependencies",{}).items(): inventory.append({"identifier":f"npm:{name}","displayName":name,"ecosystem":"JavaScript","packageManager":"package.json","declaredVersion":version,"lockState":"DECLARED"})
+    return {"status":"VALID","inventory":inventory,"measurements":[{"measurementId":"dependency_health.repository.count","capabilityId":CAPABILITY_ID,"metricKey":"dependency.count","value":len(inventory),"unit":"packages","scope":"repository","targetEntityId":"repository","aggregation":"count","sourceAdapterId":"dependency_health.declarative","sourceToolId":"filesystem"}],"findings":[],"limitations":[]}

tde_runtime/docker_artifact.py

@@ -0,0 +1,47 @@
+"""Fail-closed validation for a preserved candidate-bound OCI archive."""
+from __future__ import annotations
+
+from hashlib import sha256
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+
+def digest(path: str | Path) -> str:
+    value = Path(path)
+    hasher = sha256()
+    with value.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 validate(directory: str | Path, candidate_sha: str) -> dict[str, Any]:
+    """Return a Docker artifact record only when archive and provenance bind."""
+    root = Path(directory).resolve()
+    archive = root / "tde-oci.tar"
+    provenance_path = root / "docker-provenance.json"
+    try:
+        provenance = json.loads(provenance_path.read_text(encoding="utf-8"))
+        archive_digest = digest(archive)
+        platforms = provenance["platforms"]
+        valid = (
+            provenance.get("schemaId") == "tde.docker-provenance"
+            and provenance.get("schemaVersion") == "1.0.0"
+            and provenance.get("candidateSha") == candidate_sha
+            and provenance.get("ociArchive", {}).get("digest") == archive_digest
+            and provenance.get("baseImage", {}).get("digest", "").startswith("sha256:")
+            and provenance.get("wheel", {}).get("digest", "").startswith("sha256:")
+            and provenance.get("dockerfile", {}).get("digest", "").startswith("sha256:")
+            and isinstance(platforms, list) and {item.get("platform") for item in platforms} >= {"linux/amd64", "linux/arm64"}
+            and all(str(item.get("digest", "")).startswith("sha256:") for item in platforms)
+            and str(provenance.get("ociIndex", {}).get("digest", "")).startswith("sha256:")
+        )
+    except (OSError, ValueError, KeyError, TypeError, json.JSONDecodeError):
+        provenance, archive_digest, valid = {}, None, False
+    return {"filename": archive.name, "digest": archive_digest, "kind": "oci_archive",
+            "candidateSha": candidate_sha, "provenance": provenance, "verified": valid}

tde_runtime/evidence_store.py

@@ -0,0 +1,69 @@
+"""Storage-technology-independent immutable canonical evidence repository."""
+from __future__ import annotations
+from hashlib import sha256
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+class EvidenceStore:
+    def __init__(self, location: str | Path) -> None: self.location = Path(location)
+
+    @staticmethod
+    def _identity(evidence: Mapping[str, Any]) -> str:
+        digest = evidence.get("integrity", {}).get("contentDigest", "")
+        if not isinstance(digest, str) or not digest.startswith("sha256:"):
+            raise ValueError("evidence integrity digest is missing")
+        return digest.removeprefix("sha256:")
+
+    @staticmethod
+    def _calculated_identity(evidence: Mapping[str, Any]) -> str:
+        stable_results = [{key: value for key, value in result.items() if key != "executionTiming"}
+                          for result in evidence.get("capabilityResults", [])]
+        seed = json.dumps({"repository": evidence.get("repository", {}).get("id"),
+                           "candidate": evidence.get("candidate"),
+                           "configuration": evidence.get("configurationDigest"),
+                           "capabilityResults": stable_results,
+                           "measurements": evidence.get("measurements", []),
+                           "findings": evidence.get("findings", []),
+                           "policy": evidence.get("policyEvidence", {})},
+                          sort_keys=True, separators=(",", ":"), default=str)
+        return sha256(seed.encode()).hexdigest()
+
+    @classmethod
+    def _validate(cls, evidence: Mapping[str, Any], identity: str | None = None) -> str:
+        if evidence.get("schemaId") != "tde.evidence" or evidence.get("validation", {}).get("status") != "VALID":
+            raise ValueError("store requires validated canonical evidence")
+        actual = cls._identity(evidence)
+        if identity and identity != actual:
+            raise ValueError("persisted evidence identity does not match its record")
+        if cls._calculated_identity(evidence) != actual:
+            raise ValueError("persisted evidence integrity check failed")
+        return actual
+
+    def persist(self, evidence: Mapping[str, Any], kind: str = "evidence") -> dict[str, Any]:
+        identity = self._validate(evidence)
+        path = self.location / kind / f"{identity}.json"
+        if path.exists(): return {"id": identity, "kind": kind, "path": str(path), "immutable": True, "existing": True}
+        path.parent.mkdir(parents=True, exist_ok=True)
+        record = {"kind": kind, "repository": evidence["repository"]["id"], "candidate": evidence["candidate"]["id"], "runtime": evidence["runtime"]["version"], "schema": evidence["schemaVersion"], "timestamp": evidence["timestamps"]["generatedAt"], "qualification": evidence.get("policyEvidence", {}).get("decision"), "evidence": evidence}
+        path.write_text(json.dumps(record, sort_keys=True, indent=2) + "\n", encoding="utf-8")
+        return {"id": identity, "kind": kind, "path": str(path), "immutable": True, "existing": False}
+
+    def retrieve(self, identity: str, kind: str = "evidence") -> dict[str, Any]:
+        path = self.location / kind / f"{identity}.json"
+        try:
+            record = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise ValueError(f"persisted evidence is unavailable: {identity}") from error
+        if record.get("kind") != kind or not isinstance(record.get("evidence"), dict):
+            raise ValueError("persisted evidence record is malformed")
+        self._validate(record["evidence"], identity)
+        return record
+
+    def history(self, kind: str = "evidence") -> list[dict[str, Any]]:
+        directory = self.location / kind
+        records=[]
+        for path in sorted(directory.glob("*.json")) if directory.is_dir() else []:
+            identity = path.stem
+            records.append(self.retrieve(identity, kind))
+        return sorted(records, key=lambda item: item["timestamp"])

tde_runtime/execution.py

@@ -0,0 +1,213 @@
+"""Sequential, registry-driven coordinator for registered capability execution."""
+
+from __future__ import annotations
+
+from time import perf_counter
+from typing import Any
+from hashlib import sha256
+
+from .code_size import ADAPTER_ID, CAPABILITY_ID, CAPABILITY_VERSION, analyze
+from .complexity import ADAPTER_ID as COMPLEXITY_ADAPTER_ID, CAPABILITY_ID as COMPLEXITY_CAPABILITY_ID, CAPABILITY_VERSION as COMPLEXITY_CAPABILITY_VERSION, analyze as analyze_complexity
+from .dependency_health import CAPABILITY_ID as DEPENDENCY_CAPABILITY_ID, CAPABILITY_VERSION as DEPENDENCY_CAPABILITY_VERSION, discover as discover_dependencies
+from .maintainability import CAPABILITY_ID as MAINTAINABILITY_CAPABILITY_ID, CAPABILITY_VERSION as MAINTAINABILITY_CAPABILITY_VERSION, derive as derive_maintainability
+from .registries import AdapterRegistry, CapabilityRegistry
+
+
+class CapabilityExecutionEngine:
+    """Plans and records capability work; Runtime only consumes its canonical output."""
+
+    states = ("PLANNED", "READY", "RUNNING", "COMPLETED", "FAILED", "BLOCKED", "SKIPPED", "NOT_SUPPORTED")
+
+    def __init__(self, capability_registry: CapabilityRegistry | None = None,
+                 adapter_registry: AdapterRegistry | None = None) -> None:
+        self._capability_registry = capability_registry or CapabilityRegistry()
+        self._adapter_registry = adapter_registry or AdapterRegistry()
+
+    def plan(self, context: Any) -> dict[str, Any]:
+        requested = context.execution_options.get("capabilities", {})
+        available = {item["id"]: item for item in self._capability_registry.discover()}
+        enabled = [identifier for identifier, settings in requested.items() if settings.get("enabled")]
+        requested_plan = [identifier for identifier in enabled if identifier in available]
+        planned = [identifier for identifier in (CAPABILITY_ID, COMPLEXITY_CAPABILITY_ID, MAINTAINABILITY_CAPABILITY_ID, DEPENDENCY_CAPABILITY_ID)
+                   if identifier in requested_plan or (identifier in {CAPABILITY_ID, COMPLEXITY_CAPABILITY_ID} and MAINTAINABILITY_CAPABILITY_ID in requested_plan)]
+        unsupported = [identifier for identifier in enabled if identifier not in available]
+        adapters = {item["id"] for item in self._adapter_registry.discover()}
+        planned_adapters = [adapter for identifier, adapter in ((CAPABILITY_ID, ADAPTER_ID), (COMPLEXITY_CAPABILITY_ID, COMPLEXITY_ADAPTER_ID))
+                            if identifier in planned and adapter in adapters]
+        return {
+            "state": "PLANNED",
+            "capabilities": planned,
+            "unsupportedCapabilities": unsupported,
+            "plannedAdapters": planned_adapters,
+            "parallelReady": True,
+            "retries": "NONE",
+        }
+
+    def execute(self, context: Any) -> dict[str, Any]:
+        started = perf_counter()
+        plan = self.plan(context)
+        evidence = self._execution_evidence(context, plan)
+        measurements: list[dict[str, Any]] = []
+        findings: list[dict[str, Any]] = []
+        capability_results: list[dict[str, Any]] = []
+        adapter_results: list[dict[str, Any]] = []
+
+        for identifier in plan["capabilities"]:
+            normalized = self._dispatch(identifier, context, measurements)
+            measurements.extend(normalized["measurements"])
+            findings.extend(normalized["findings"])
+            capability_results.extend(normalized["capabilityResults"])
+            adapter_results.extend(normalized.get("adapterResults", []))
+            result = normalized["capabilityResults"][-1]
+            adapter_ids = result.get("adapterIds", [])
+            state = "COMPLETED" if result["status"] == "VALID" else "BLOCKED"
+            if state == "COMPLETED":
+                evidence["executedCapabilities"].append(identifier)
+                evidence["executedAdapters"].extend(adapter_ids)
+            else:
+                evidence["blockedCapabilities"].append(identifier)
+                evidence["limitations"].extend(result.get("limitations", []))
+            evidence["workItems"].append({"capabilityId": identifier, "adapterId": adapter_ids[0] if adapter_ids else None,
+                                            "state": state, "durationMs": result["executionTiming"]["durationMs"]})
+
+        evidence["unsupportedCapabilities"].extend(plan["unsupportedCapabilities"])
+        evidence["durationMs"] = int((perf_counter() - started) * 1000)
+        evidence["state"] = "COMPLETED" if evidence["executedCapabilities"] else "BLOCKED"
+        return {
+            "executedWorkItems": len(evidence["workItems"]),
+            "measurements": measurements,
+            "findings": findings,
+            "capabilityResults": capability_results,
+            "adapterResults": adapter_results,
+            "executionEvidence": evidence,
+        }
+
+    def _dispatch(self, identifier: str, context: Any, measurements: list[dict[str, Any]]) -> dict[str, Any]:
+        started = perf_counter()
+        timeout = int(context.execution_options.get("timeout", 60))
+        if identifier == CAPABILITY_ID:
+            result = analyze(context.repository_root, timeout)
+            duration = int((perf_counter() - started) * 1000)
+            return self._code_size_result(context, result, duration) if result["status"] == "VALID" else self._blocked(CAPABILITY_ID, CAPABILITY_VERSION, [ADAPTER_ID], result["limitations"], duration)
+        if identifier == COMPLEXITY_CAPABILITY_ID:
+            settings = context.execution_options.get("capabilities", {}).get(COMPLEXITY_CAPABILITY_ID, {})
+            result = analyze_complexity(context.repository_root, timeout, settings)
+            duration = int((perf_counter() - started) * 1000)
+            if result["status"] != "VALID":
+                return self._blocked(COMPLEXITY_CAPABILITY_ID, COMPLEXITY_CAPABILITY_VERSION, [COMPLEXITY_ADAPTER_ID], result["limitations"], duration)
+            return self._complexity_result(context, result, duration)
+        if identifier == DEPENDENCY_CAPABILITY_ID:
+            result = discover_dependencies(context.repository_root)
+            duration = int((perf_counter() - started) * 1000)
+            capability = {"capabilityId": DEPENDENCY_CAPABILITY_ID, "capabilityVersion": DEPENDENCY_CAPABILITY_VERSION,
+                          "status": "VALID", "adapterIds": [], "completeness": 1, "qualificationApplicable": True,
+                          "executionTiming": {"durationMs": duration}}
+            return {"measurements": result["measurements"], "findings": result["findings"], "capabilityResults": [capability]}
+        code = {"measurements": measurements}
+        complexity = {"measurements": [item for item in measurements if item.get("capabilityId") == COMPLEXITY_CAPABILITY_ID]}
+        result = derive_maintainability(code, complexity)
+        duration = int((perf_counter() - started) * 1000)
+        if result["status"] != "VALID":
+            return self._blocked(MAINTAINABILITY_CAPABILITY_ID, MAINTAINABILITY_CAPABILITY_VERSION, [], result["limitations"], duration)
+        capability = {"capabilityId": MAINTAINABILITY_CAPABILITY_ID, "capabilityVersion": MAINTAINABILITY_CAPABILITY_VERSION,
+                      "status": "VALID", "adapterIds": [], "completeness": 1, "qualificationApplicable": True,
+                      "executionTiming": {"durationMs": duration}}
+        return {"measurements": result["measurements"], "findings": result["findings"], "capabilityResults": [capability]}
+
+    @staticmethod
+    def _blocked(identifier: str, version: str, adapter_ids: list[str], limitations: list[dict[str, Any]], duration: int) -> dict[str, Any]:
+        return {"measurements": [], "findings": [], "capabilityResults": [{"capabilityId": identifier, "capabilityVersion": version,
+                "status": "BLOCKED", "adapterIds": adapter_ids, "completeness": 0, "qualificationApplicable": False,
+                "limitations": limitations, "executionTiming": {"durationMs": duration}}]}
+
+    @staticmethod
+    def _execution_evidence(context: Any, plan: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "executionId": context.execution_id,
+            "plannedCapabilities": plan["capabilities"],
+            "executedCapabilities": [],
+            "skippedCapabilities": [],
+            "blockedCapabilities": [],
+            "unsupportedCapabilities": [],
+            "plannedAdapters": plan["plannedAdapters"],
+            "executedAdapters": [],
+            "workItems": [],
+            "executionGraph": {"nodes": plan["capabilities"], "edges": []},
+            "durationMs": 0,
+            "state": "PLANNED",
+            "limitations": [],
+        }
+
+    @staticmethod
+    def _code_size_result(context: Any, result: dict[str, Any], duration: int) -> dict[str, Any]:
+        names = {"files": "file_count", "code": "code_lines", "comment": "comment_lines", "blank": "blank_lines",
+                 "source": "source_lines", "test": "test_lines", "generated": "generated_lines",
+                 "vendor": "vendor_lines", "documentation": "documentation_lines"}
+        measurements = [
+            {"measurementId": f"code_size.repository.{key}", "capabilityId": CAPABILITY_ID,
+             "metricKey": f"code_size.{names[key]}", "value": value, "unit": "files" if key == "files" else "lines",
+             "scope": "repository", "targetEntityId": context.repository_id, "aggregation": "sum",
+             "sourceAdapterId": result["adapter"]["id"], "sourceToolId": "cloc"}
+            for key, value in result["totals"].items() if key in names
+        ]
+        measurements.append({"measurementId": "code_size.repository.test_ratio", "capabilityId": CAPABILITY_ID,
+                             "metricKey": "code_size.test_to_source_ratio", "value": result["testToSourceRatio"],
+                             "unit": "ratio", "scope": "repository", "targetEntityId": context.repository_id,
+                             "aggregation": "ratio", "sourceAdapterId": result["adapter"]["id"], "sourceToolId": "cloc"})
+        for language, totals in result["languages"].items():
+            language_id = f"language.{language.lower().replace(' ', '_')}"
+            for key in ("files", "code", "comment", "blank"):
+                measurements.append({"measurementId": f"code_size.{language_id}.{key}", "capabilityId": CAPABILITY_ID,
+                                     "metricKey": f"code_size.language_{key}", "value": totals[key],
+                                     "unit": "files" if key == "files" else "lines", "scope": "language",
+                                     "targetEntityId": language_id, "aggregation": "sum",
+                                     "sourceAdapterId": result["adapter"]["id"], "sourceToolId": "cloc"})
+        for file in result["files"]:
+            file_id = "file." + sha256(file["path"].encode()).hexdigest()[:16]
+            for key in ("code", "comment", "blank"):
+                measurements.append({"measurementId": f"code_size.{file_id}.{key}", "capabilityId": CAPABILITY_ID,
+                                     "metricKey": f"code_size.file_{key}_lines", "value": file[key], "unit": "lines",
+                                     "scope": "file", "targetEntityId": file_id, "aggregation": "sum",
+                                     "sourceAdapterId": result["adapter"]["id"], "sourceToolId": "cloc"})
+        adapter_result = {"adapter": result["adapter"], "analyzer": result["analyzer"], "execution": "SUCCESS",
+                          "rawOutputHash": result["rawOutputHash"], "rawOutput": result["rawOutput"],
+                          "measuredScope": ["repository", "language", "file"], "completeness": 1,
+                          "draftMeasurements": measurements, "draftFindings": [], "warnings": [], "errors": [],
+                          "limitations": result["limitations"], "executionTiming": {"durationMs": duration}}
+        return {"measurements": measurements, "findings": [], "adapterResults": [adapter_result], "capabilityResults": [
+            {"capabilityId": CAPABILITY_ID, "capabilityVersion": CAPABILITY_VERSION, "status": "VALID",
+             "adapterIds": [result["adapter"]["id"]], "completeness": 1, "qualificationApplicable": True,
+             "limitations": result["limitations"], "executionTiming": {"durationMs": duration}}
+        ]}
+
+    @staticmethod
+    def _complexity_result(context: Any, result: dict[str, Any], duration: int) -> dict[str, Any]:
+        symbols, measurements, findings = result["symbols"], [], []
+        def measurement_id(scope: str, entity: str, metric: str) -> str:
+            return f"complexity.{scope}.{sha256(entity.encode()).hexdigest()[:16]}.{metric}"
+        def add_summary(scope: str, entity: str, values: list[int]) -> None:
+            if not values: return
+            for metric, value, aggregation in (("average", sum(values)/len(values), "mean"), ("maximum", max(values), "maximum")):
+                measurements.append({"measurementId":measurement_id(scope,entity,metric),"capabilityId":COMPLEXITY_CAPABILITY_ID,"metricKey":f"complexity.cyclomatic.{metric}","value":value,"unit":"score","scope":scope,"targetEntityId":entity,"aggregation":aggregation,"sourceAdapterId":COMPLEXITY_ADAPTER_ID,"sourceToolId":"radon"})
+            for lower, upper, band in ((1,10,"low"),(11,20,"high"),(21,40,"very_high"),(41,None,"critical")):
+                measurements.append({"measurementId":measurement_id(scope,entity,f"distribution.{band}"),"capabilityId":COMPLEXITY_CAPABILITY_ID,"metricKey":"complexity.cyclomatic.distribution","value":sum(1 for value in values if value >= lower and (upper is None or value <= upper)),"unit":"symbols","scope":scope,"targetEntityId":f"{entity}.distribution.{band}","aggregation":"count","sourceAdapterId":COMPLEXITY_ADAPTER_ID,"sourceToolId":"radon"})
+        add_summary("repository", context.repository_id, [symbol["complexity"] for symbol in symbols])
+        by_language, by_file = {}, {}
+        for symbol in symbols:
+            by_language.setdefault(symbol["language"], []).append(symbol); by_file.setdefault(symbol["path"], []).append(symbol)
+            entity = "symbol." + sha256(f"{symbol['path']}:{symbol['name']}:{symbol['line']}".encode()).hexdigest()[:16]
+            evidence = measurement_id("symbol", entity, "value")
+            measurements.append({"measurementId":evidence,"capabilityId":COMPLEXITY_CAPABILITY_ID,"metricKey":"complexity.cyclomatic.value","value":symbol["complexity"],"unit":"score","scope":"symbol","targetEntityId":entity,"aggregation":"value","sourceAdapterId":COMPLEXITY_ADAPTER_ID,"sourceToolId":"radon"})
+            thresholds = result["thresholds"]
+            if symbol["complexity"] >= thresholds["critical"]: rule, severity, title, threshold = "complexity.critical", "CRITICAL", "Critical Complexity", thresholds["critical"]
+            elif symbol["complexity"] >= thresholds["veryHigh"]: rule, severity, title, threshold = "complexity.very_high", "HIGH", "Very High Complexity", thresholds["veryHigh"]
+            elif symbol["complexity"] >= thresholds["high"]: rule, severity, title, threshold = "complexity.high", "HIGH", "High Complexity", thresholds["high"]
+            else: continue
+            findings.append({"findingId":f"{rule}.{entity}","capabilityId":COMPLEXITY_CAPABILITY_ID,"ruleId":rule,"severity":severity,"category":"COMPLEXITY","title":title,"description":f"Cyclomatic complexity is {symbol['complexity']} (threshold: {threshold}).","affectedEntityId":entity,"location":{"path":symbol["path"],"line":symbol["line"],"endLine":symbol["endLine"]},"evidenceReferences":[evidence],"state":"OPEN","regression":"UNKNOWN","confidence":1,"suppressible":True})
+        for language, values in sorted(by_language.items()): add_summary("language", f"language.{language.lower()}", [item["complexity"] for item in values])
+        for path, values in sorted(by_file.items()): add_summary("file", "file."+sha256(path.encode()).hexdigest()[:16], [item["complexity"] for item in values])
+        if not symbols:
+            findings.append({"findingId":"complexity.missing.repository","capabilityId":COMPLEXITY_CAPABILITY_ID,"ruleId":"complexity.missing","severity":"INFO","category":"COMPLEXITY","title":"Missing Complexity","description":"No supported symbols were measured.","affectedEntityId":context.repository_id,"evidenceReferences":[],"state":"OPEN","regression":"UNKNOWN","confidence":1,"suppressible":False})
+        adapter = {"adapter":result["adapter"],"analyzer":result["analyzer"],"execution":"SUCCESS","rawOutputHash":result["rawOutputHash"],"rawOutput":result["rawOutput"],"measuredScope":["repository","language","file","symbol"],"completeness":1,"draftMeasurements":measurements,"draftFindings":findings,"warnings":[],"errors":[],"limitations":result["limitations"],"executionTiming":{"durationMs":duration}}
+        capability = {"capabilityId":COMPLEXITY_CAPABILITY_ID,"capabilityVersion":COMPLEXITY_CAPABILITY_VERSION,"status":"VALID","adapterIds":[COMPLEXITY_ADAPTER_ID],"completeness":1,"qualificationApplicable":True,"limitations":result["limitations"],"executionTiming":{"durationMs":duration}}
+        return {"measurements":measurements,"findings":findings,"adapterResults":[adapter],"capabilityResults":[capability]}

tde_runtime/maintainability.py

@@ -0,0 +1,11 @@
+"""Derived Maintainability capability; consumes canonical Code Size and Complexity observations only."""
+from __future__ import annotations
+from typing import Any
+CAPABILITY_ID="maintainability"; CAPABILITY_VERSION="0.1.0"
+def derive(code_size: dict[str, Any], complexity: dict[str, Any]) -> dict[str, Any]:
+    code=next((m["value"] for m in code_size.get("measurements",[]) if m["metricKey"]=="code_size.code_lines"),None)
+    complexity_value=next((m["value"] for m in complexity.get("measurements",[]) if m["metricKey"]=="complexity.cyclomatic.average"),None)
+    if code is None or complexity_value is None: return {"status":"BLOCKED","limitations":[{"id":"maintainability.dependencies","description":"Validated Code Size and Complexity evidence is required.","cause":"missing dependency evidence"}]}
+    index=max(0.0, min(100.0, 100.0 - complexity_value * 3.0 - (code / 1000.0)))
+    metric={"measurementId":"maintainability.repository.index","capabilityId":CAPABILITY_ID,"metricKey":"maintainability.index","value":index,"unit":"index","scope":"repository","targetEntityId":"repository","aggregation":"mean","sourceAdapterId":"derived.maintainability","sourceToolId":"canonical_evidence"}
+    return {"status":"VALID","measurements":[metric],"findings":[],"limitations":[]}