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

tde_cli/__init__.py

@@ -0,0 +1,5 @@
+"""Thin command-line presentation layer for the TDE runtime."""
+
+from .main import main
+
+__all__ = ["main"]

tde_cli/main.py

@@ -0,0 +1,400 @@
+"""CLI framework that consumes only the public Runtime API."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+from pathlib import Path
+import sys
+from typing import Any, Sequence, TextIO
+
+from tde_runtime import Runtime, RuntimeConfiguration
+from tde_runtime.baseline import BaselineError, BaselineRepository, ComparisonEngine, ComparisonRepository
+from tde_runtime.policy import PolicyEngine, PolicyError
+from tde_runtime.trend import TrendEngine
+from tde_runtime.evidence_store import EvidenceStore
+from tde_runtime.runtime_qualification import RuntimeQualificationEngine
+from tde_runtime.software_assurance import SoftwareAssurance
+from tde_runtime.trusted_delivery import TrustedDelivery
+from tde_runtime.release_qualification import ReleaseQualification
+from tde_runtime.release_certification import ReleaseCertification
+from tde_runtime.runtime import EVIDENCE_SCHEMA_VERSION, RUNTIME_VERSION
+
+
+CLI_VERSION = "0.1.0"
+GENERATION = "1"
+
+
+class ExitCode:
+    SUCCESS = 0
+    WARNING = 1
+    FAILED = 2
+    BLOCKED = 3
+    NOT_SUPPORTED = 4
+
+
+def _policy_exit_code(decision: str) -> int:
+    """The CLI maps canonical Policy decisions; it never re-evaluates policy."""
+    return {"PASS": ExitCode.SUCCESS, "PASS_WITH_WARNINGS": ExitCode.WARNING,
+            "FAIL": ExitCode.FAILED, "BLOCKED": ExitCode.BLOCKED,
+            "NOT_APPLICABLE": ExitCode.NOT_SUPPORTED}.get(decision, ExitCode.BLOCKED)
+
+
+COMMANDS: dict[str, dict[str, str]] = {
+    "help": {"purpose": "Show generated CLI help."},
+    "validate": {"purpose": "Validate runtime configuration and context."},
+    "inspect": {"purpose": "Inspect a target and planned Code Size execution."},
+    "assess": {"purpose": "Assess a target through selected capabilities."},
+    "baseline": {"purpose": "Create an immutable baseline from persisted canonical evidence."},
+    "compare": {"purpose": "Persist and qualify a canonical comparison against a baseline."},
+    "trend": {"purpose": "Aggregate canonical evidence history into trends."},
+    "query": {"purpose": "Query canonical engineering evidence."},
+    "store": {"purpose": "Persist canonical Runtime evidence."},
+    "history": {"purpose": "List persisted canonical evidence."},
+    "run": {"purpose": "Execute registered capabilities through the Execution Engine."},
+    "qualify": {"purpose": "Qualify canonical Runtime evidence."},
+    "assure": {"purpose": "Assure repository and artifact integrity."},
+    "trusted-delivery": {"purpose": "Validate immutable candidate and delivery evidence."},
+    "release-qualify": {"purpose": "Qualify a release candidate without publication."},
+    "certify": {"purpose": "Certify a qualified Internal Release candidate without publication."},
+    "report": {"purpose": "Render a Code Size evidence projection."},
+    "explain": {"purpose": "Explain a result (not implemented)."},
+}
+
+
+def _global_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--verbose", action="store_true", help="Enable INFO logging.")
+    parser.add_argument("--quiet", action="store_true", help="Suppress non-error logging.")
+    parser.add_argument("--config", help="Path to repository .tde.yml configuration.")
+    parser.add_argument("--output", help="Output destination (reserved; console is used now).")
+    parser.add_argument("--format", choices=("human", "json", "markdown"), default="human", help="Output format.")
+    parser.add_argument("--log-level", choices=("ERROR", "WARNING", "INFO", "DEBUG", "TRACE"), help="Logging level.")
+    parser.add_argument("--policy", help="Repository or workspace policy directory.")
+    parser.add_argument("--policy-override", action="append", default=[], metavar="RULE=JSON", help="Override a policy rule with a JSON object.")
+    parser.add_argument("--baseline-location", help="Directory used for immutable baselines.")
+    parser.add_argument("--history-depth", type=int, help="Maximum baseline history depth for trends.")
+    parser.add_argument("--store-location", help="Directory used for canonical evidence storage.")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="tde", description="Technical Debt Engine CLI foundation.")
+    parser.add_argument("--version", action="store_true", help="Show CLI, runtime, schema, and generation versions.")
+    _global_options(parser)
+    subcommands = parser.add_subparsers(dest="command", title="commands")
+    for identifier, metadata in COMMANDS.items():
+        command = subcommands.add_parser(identifier, help=metadata["purpose"], description=metadata["purpose"])
+        command.add_argument("target", nargs="?", default=".", help="Repository target (default: current directory).")
+        command.add_argument("--capability", action="append", default=[], help="Enable a registered capability.")
+        if identifier == "baseline":
+            command.add_argument("--name", help="Immutable baseline name.")
+        if identifier == "compare":
+            command.add_argument("--baseline", help="Baseline name or JSON path.")
+        if identifier == "query":
+            command.add_argument("--resource", default="repositories", help="Evidence resource.")
+            command.add_argument("--filter", action="append", default=[], metavar="KEY=VALUE")
+            command.add_argument("--aggregate", choices=("count",))
+        if identifier == "assure":
+            command.add_argument("--artifact-directory", action="append", default=[], metavar="DIRECTORY",
+                                 help="Candidate build directory; repeat for independent reproducibility verification.")
+        if identifier == "trusted-delivery":
+            command.add_argument("--artifact-directory", action="append", default=[], metavar="DIRECTORY",
+                                 help="Candidate build directory; repeat for independent reproducibility verification.")
+            command.add_argument("--manifest", metavar="PATH", help="Canonical JSON delivery manifest for this candidate.")
+        if identifier == "release-qualify":
+            command.add_argument("--artifact-directory", action="append", default=[], metavar="DIRECTORY")
+            command.add_argument("--docker-artifact-directory", metavar="DIRECTORY")
+            command.add_argument("--manifest-output", required=True, metavar="PATH")
+            command.add_argument("--release-capability", action="append", default=[], metavar="CAPABILITY",
+                                 help="Required release capability; repeat for every selected capability.")
+        if identifier == "certify":
+            command.add_argument("--qualification-evidence", required=True, metavar="PATH")
+            command.add_argument("--report-output", required=True, metavar="PATH")
+    return parser
+
+
+def _load_configuration(path: str | None, target: str) -> RuntimeConfiguration:
+    return RuntimeConfiguration.discover(target, path)
+
+
+def _configure_logging(arguments: argparse.Namespace) -> None:
+    level = arguments.log_level or ("INFO" if arguments.verbose else "ERROR" if arguments.quiet else "WARNING")
+    logging.basicConfig(level=logging.DEBUG if level == "TRACE" else getattr(logging, level), format="%(levelname)s %(message)s")
+
+
+def _render(value: dict[str, Any], output_format: str, stream: TextIO) -> None:
+    if output_format == "json":
+        print(json.dumps(value, sort_keys=True), file=stream)
+        return
+    if output_format == "markdown":
+        for key, item in value.items():
+            print(f"- **{key}:** `{item}`", file=stream)
+        return
+    for key, item in value.items():
+        print(f"{key}: {item}", file=stream)
+
+
+def _store_location(arguments: argparse.Namespace, target: str) -> Path:
+    location = Path(arguments.store_location or ".tde/evidence")
+    return location if location.is_absolute() else Path(target) / location
+
+
+def _runtime_result(command: str, target: str, configuration: RuntimeConfiguration,
+                    store: EvidenceStore | None = None) -> tuple[int, dict[str, Any]]:
+    result = Runtime().execute(target, configuration)
+    payload = {"command": command, "runtime": result.report["runtimeSummary"],
+               "execution": result.report["executionSummary"], "environment": result.report["environment"], "qualification": result.report["qualification"],
+               "runtimeQualification": result.evidence["runtimeQualification"], "validation": result.validation,
+               "evidence": result.evidence, "evidenceId": result.evidence["integrity"]["contentDigest"]}
+    if store is not None:
+        payload["evidenceStore"] = store.persist(result.evidence)
+    decision = result.evidence["policyEvidence"]["decision"]
+    if decision == "BLOCKED":
+        return ExitCode.BLOCKED, payload
+    if command in {"assess", "run"} and result.evidence["runtimeQualification"]["level"] != "QUALIFIED":
+        return ExitCode.BLOCKED, payload
+    return (_policy_exit_code(decision) if command in {"assess", "run"} else ExitCode.SUCCESS), payload
+
+
+def _render_capability_report(evidence: dict[str, Any], capability: str, output_format: str, stream: TextIO) -> None:
+    metrics = {item["metricKey"]: item["value"] for item in evidence.get("measurements", []) if item.get("scope") == "repository" and item.get("capabilityId") == capability}
+    title = "Code Size" if capability == "code_size" else "Complexity"
+    payload = {"schemaId": "tde.report", "schemaVersion": evidence["schemaVersion"], "evidenceId": evidence["integrity"]["contentDigest"],
+               "format": output_format, "content": {"capability": capability, "metrics": metrics,
+               "qualification": evidence["runtimeQualification"]["level"]}}
+    if output_format == "markdown":
+        print(f"# {title} Report", file=stream)
+        print("", file=stream)
+        for key, value in sorted(metrics.items()):
+            print(f"- **{key}:** {value}", file=stream)
+        print(f"- **qualification:** {payload['content']['qualification']}", file=stream)
+        return
+    _render(payload, output_format, stream)
+
+
+def main(argv: Sequence[str] | None = None, stdout: TextIO | None = None) -> int:
+    stream = stdout or sys.stdout
+    parser = build_parser()
+    arguments = parser.parse_args(argv)
+    prepared = _prepare_command(arguments, parser, stream)
+    if isinstance(prepared, int): return prepared
+    configuration = prepared
+    if arguments.command in {"store", "history"}:
+        store = EvidenceStore(_store_location(arguments, arguments.target))
+        try:
+            if arguments.command == "history":
+                _render({"command": "history", "records": store.history()}, arguments.format, stream)
+                return ExitCode.SUCCESS
+            record = Runtime().execute(arguments.target, configuration)
+            _render({"command": "store", "record": store.persist(record.evidence)}, arguments.format, stream)
+            return ExitCode.SUCCESS
+        except (ValueError, OSError, json.JSONDecodeError) as error:
+            _render({"command": arguments.command, "status": "BLOCKED", "reason": str(error)}, arguments.format, stream)
+            return ExitCode.BLOCKED
+    return _execute_command(arguments, configuration, stream)
+
+
+def _prepare_command(arguments: argparse.Namespace, parser: argparse.ArgumentParser, stream: TextIO) -> RuntimeConfiguration | int:
+    if arguments.version:
+        _render({"cliVersion": CLI_VERSION, "runtimeVersion": RUNTIME_VERSION,
+                 "schemaVersion": EVIDENCE_SCHEMA_VERSION, "generation": GENERATION}, arguments.format, stream)
+        return ExitCode.SUCCESS
+    if not arguments.command:
+        parser.print_help(stream)
+        return ExitCode.SUCCESS
+    if arguments.command == "help":
+        parser.print_help(stream)
+        return ExitCode.SUCCESS
+    _configure_logging(arguments)
+    try:
+        configuration = _load_configuration(arguments.config, arguments.target)
+    except ValueError as error:
+        _render({"status": "BLOCKED", "reason": str(error)}, arguments.format, stream)
+        return ExitCode.BLOCKED
+    if arguments.policy or arguments.policy_override:
+        values = configuration.as_dict()
+        policy = dict(values["executionOptions"].get("policy", {}))
+        if arguments.policy:
+            policy["repository"] = arguments.policy
+        overrides = dict(policy.get("overrides", {}))
+        try:
+            for item in arguments.policy_override:
+                rule, raw_value = item.split("=", 1)
+                overrides[rule] = json.loads(raw_value)
+                if not isinstance(overrides[rule], dict):
+                    raise ValueError("override must be a JSON object")
+        except (ValueError, json.JSONDecodeError) as error:
+            _render({"status": "BLOCKED", "reason": f"invalid policy override: {error}"}, arguments.format, stream)
+            return ExitCode.BLOCKED
+        policy["overrides"] = overrides
+        values["policy"] = policy
+        values["executionOptions"].pop("policy", None)
+        configuration = RuntimeConfiguration.load(values)
+    if arguments.baseline_location:
+        values = configuration.as_dict()
+        values["baseline"] = {"location": arguments.baseline_location}
+        values["executionOptions"].pop("baseline", None)
+        configuration = RuntimeConfiguration.load(values)
+    if arguments.history_depth is not None:
+        if arguments.history_depth < 0:
+            _render({"status": "BLOCKED", "reason": "history depth must not be negative"}, arguments.format, stream)
+            return ExitCode.BLOCKED
+        values = configuration.as_dict()
+        values["trend"] = {"historyDepth": arguments.history_depth}
+        values["executionOptions"].pop("trend", None)
+        configuration = RuntimeConfiguration.load(values)
+    if arguments.command in {"assess", "baseline", "compare", "run", "store", "inspect", "validate", "qualify", "report"} and arguments.capability:
+        supported = {"code-size": "code_size", "complexity": "complexity"}
+        if len(arguments.capability) != 1 or arguments.capability[0] not in supported:
+            _render({"command": arguments.command, "status": "NOT_SUPPORTED", "reason": "This vertical slice supports code-size and complexity."}, arguments.format, stream)
+            return ExitCode.NOT_SUPPORTED
+        configuration = configuration.with_capability(supported[arguments.capability[0]])
+    if arguments.command == "release-qualify":
+        supported = {"code-size": "code_size", "complexity": "complexity"}
+        if not arguments.release_capability or any(item not in supported for item in arguments.release_capability):
+            _render({"command": "release-qualify", "status": "BLOCKED",
+                     "reason": "release-qualify requires one or more supported --release-capability values"}, arguments.format, stream)
+            return ExitCode.BLOCKED
+        for capability in sorted(set(arguments.release_capability)):
+            configuration = configuration.with_capability(supported[capability])
+    return configuration
+
+
+def _execute_command(arguments: argparse.Namespace, configuration: RuntimeConfiguration, stream: TextIO) -> int:
+    if arguments.command in {"baseline", "compare"}:
+        return _baseline_command(arguments, configuration, stream)
+    if arguments.command == "trend":
+        return _trend_command(arguments, configuration, stream)
+    if arguments.command == "query":
+        return _query_command(arguments, configuration, stream)
+    if arguments.command == "qualify":
+        try:
+            result=Runtime().execute(arguments.target,configuration)
+            capability=arguments.capability[0].replace("-","_") if arguments.capability else None
+            qualification=RuntimeQualificationEngine().qualify(result.evidence,capability)
+            _render({"command":"qualify","runtimeQualification":qualification},arguments.format,stream)
+            return ExitCode.SUCCESS if qualification["level"]!="BLOCKED" else ExitCode.BLOCKED
+        except ValueError as error:
+            _render({"command":"qualify","status":"BLOCKED","reason":str(error)},arguments.format,stream); return ExitCode.BLOCKED
+    if arguments.command == "report":
+        return _report_command(arguments, stream)
+    if arguments.command == "assure":
+        evidence=SoftwareAssurance().assure(arguments.target,arguments.artifact_directory)
+        _render({"command":"assure","assuranceEvidence":evidence},arguments.format,stream)
+        return _policy_exit_code(evidence["decision"])
+    if arguments.command == "trusted-delivery":
+        result=Runtime().execute(arguments.target,configuration)
+        assurance=SoftwareAssurance().assure(arguments.target,arguments.artifact_directory)
+        evidence=TrustedDelivery().validate(arguments.target,result.evidence,assurance,arguments.manifest)
+        _render({"command":"trusted-delivery","trustedDeliveryEvidence":evidence,"softwareAssurance":assurance},arguments.format,stream)
+        return _policy_exit_code(evidence["qualification"])
+    if arguments.command == "release-qualify":
+        result=Runtime().execute(arguments.target,configuration)
+        evidence=ReleaseQualification().qualify(arguments.target,result.evidence,arguments.artifact_directory,arguments.manifest_output,
+                                                 [item.replace("-", "_") for item in arguments.release_capability], arguments.docker_artifact_directory)
+        _render({"command":"release-qualify","releaseQualificationEvidence":evidence},arguments.format,stream)
+        return ExitCode.SUCCESS if evidence["decision"] == "RELEASE_QUALIFIED" else ExitCode.FAILED
+    if arguments.command == "certify":
+        evidence = ReleaseCertification().certify(arguments.qualification_evidence, arguments.report_output)
+        _render({"command": "certify", "releaseCertificationEvidence": evidence}, arguments.format, stream)
+        return ExitCode.SUCCESS if evidence["decision"] == "RELEASE_CERTIFIED" else ExitCode.BLOCKED
+    if arguments.command in {"validate", "inspect", "assess", "run"}:
+        if arguments.command in {"assess", "run"}:
+            if not arguments.capability:
+                _render({"command": "assess", "status": "NOT_IMPLEMENTED", "reason": "Only code-size and complexity are delivered."}, arguments.format, stream)
+                return ExitCode.NOT_SUPPORTED
+        try:
+            store = EvidenceStore(_store_location(arguments, arguments.target)) if arguments.command in {"assess", "run"} else None
+            code, payload = _runtime_result(arguments.command, arguments.target, configuration, store)
+        except (ValueError, OSError, json.JSONDecodeError) as error:
+            _render({"status": "BLOCKED", "reason": str(error)}, arguments.format, stream)
+            return ExitCode.BLOCKED
+        _render(payload, arguments.format, stream)
+        return code
+    _render({"command": arguments.command, "status": "NOT_IMPLEMENTED",
+             "reason": "This command framework is present; its capability behavior is not delivered."}, arguments.format, stream)
+    return ExitCode.NOT_SUPPORTED
+
+
+def _baseline_command(arguments: argparse.Namespace, configuration: RuntimeConfiguration, stream: TextIO) -> int:
+    location = configuration.execution_options.get("baseline", {}).get("location", ".tde/baselines")
+    repository = BaselineRepository(Path(arguments.target) / location if not Path(location).is_absolute() else location)
+    evidence_store = EvidenceStore(_store_location(arguments, arguments.target))
+    try:
+        current = Runtime().execute(arguments.target, configuration)
+        persisted = evidence_store.persist(current.evidence)
+        evidence = evidence_store.retrieve(persisted["id"])["evidence"]
+        if arguments.command == "baseline": return _create_baseline(arguments, repository, evidence, persisted, stream)
+        return _compare_baseline(arguments, repository, current, evidence, persisted, stream)
+    except (BaselineError, PolicyError, ValueError) as error:
+        _render({"command": arguments.command, "status": "BLOCKED", "reason": str(error)}, arguments.format, stream)
+        return ExitCode.BLOCKED
+
+
+def _create_baseline(arguments, repository, evidence, persisted, stream):
+    baseline = repository.create(evidence, arguments.name)
+    _render({"command": "baseline", "status": "VALID", "evidenceStore": persisted, "baseline": baseline}, arguments.format, stream)
+    return ExitCode.SUCCESS
+
+
+def _compare_baseline(arguments, repository, current, evidence, persisted, stream):
+    if not arguments.baseline: raise BaselineError("compare requires --baseline")
+    baseline = repository.load(arguments.baseline)
+    comparison = ComparisonEngine().compare(evidence, baseline)
+    policy = PolicyEngine().load(current.context.configuration, current.context.repository_root, current.context.runtime_version, current.context.schema_version)
+    normalized = {"measurements": evidence["measurements"], "findings": evidence["findings"], "capabilityResults": evidence["capabilityResults"], "comparison": comparison}
+    policy_evidence = PolicyEngine().evaluate(policy, normalized, current.context.configuration)
+    persisted_comparison = ComparisonRepository(repository.location.parent / "comparisons").persist(comparison, policy_evidence, baseline)
+    _render({"command": "compare", "evidenceStore": persisted, "comparison": comparison, "comparisonStore": persisted_comparison, "policyEvidence": policy_evidence, "qualificationDelta": persisted_comparison["qualificationDelta"]}, arguments.format, stream)
+    return ExitCode.BLOCKED if policy_evidence["decision"] == "BLOCKED" else ExitCode.SUCCESS
+
+
+def _trend_command(arguments, configuration, stream):
+    location = configuration.execution_options.get("baseline", {}).get("location", ".tde/baselines")
+    location = Path(arguments.target) / location if not Path(location).is_absolute() else Path(location)
+    try:
+        current = Runtime().execute(arguments.target, configuration)
+        trend = TrendEngine().build(current.evidence, location, configuration.execution_options.get("trend", {}).get("historyDepth"))
+        policy = PolicyEngine().load(current.context.configuration, current.context.repository_root, current.context.runtime_version, current.context.schema_version)
+        inputs = {"measurements": current.evidence["measurements"], "findings": current.evidence["findings"], "capabilityResults": current.evidence["capabilityResults"], "trend": trend}
+        evidence = PolicyEngine().evaluate(policy, inputs, current.context.configuration)
+        _render({"command": "trend", "trendEvidence": trend, "policyEvidence": evidence}, arguments.format, stream)
+        return ExitCode.BLOCKED if evidence["decision"] == "BLOCKED" else ExitCode.SUCCESS
+    except (ValueError, PolicyError) as error:
+        _render({"command": "trend", "status": "BLOCKED", "reason": str(error)}, arguments.format, stream); return ExitCode.BLOCKED
+
+
+def _query_command(arguments, configuration, stream):
+    try:
+        filters = dict(item.split("=", 1) for item in arguments.filter)
+        records = EvidenceStore(_store_location(arguments, arguments.target)).history()
+        if not records: raise ValueError("no persisted evidence is available; run assess first")
+        evidence = records[-1]["evidence"]
+        location = configuration.execution_options.get("baseline", {}).get("location", ".tde/baselines")
+        baseline_path = Path(arguments.target) / location if not Path(location).is_absolute() else Path(location)
+        comparisons = ComparisonRepository(baseline_path.parent / "comparisons").history()
+        baselines = [BaselineRepository(baseline_path).load(path) for path in sorted(baseline_path.glob("*.json"))] if baseline_path.is_dir() else []
+        response = Runtime().query(evidence, {"resource": arguments.resource, "filter": filters, "aggregate": arguments.aggregate, "baselines": baselines, "comparisons": comparisons})
+        _render({"command": "query", "evidenceId": evidence["integrity"]["contentDigest"], **response}, arguments.format, stream); return ExitCode.SUCCESS
+    except (ValueError, PolicyError) as error:
+        _render({"command": "query", "status": "BLOCKED", "reason": str(error)}, arguments.format, stream); return ExitCode.BLOCKED
+
+
+def _report_command(arguments, stream):
+    supported = {"code-size": "code_size", "complexity": "complexity"}
+    if len(arguments.capability) != 1 or arguments.capability[0] not in supported:
+        _render({"command": "report", "status": "NOT_SUPPORTED", "reason": "report requires --capability code-size or --capability complexity"}, arguments.format, stream); return ExitCode.NOT_SUPPORTED
+    try:
+        capability = supported[arguments.capability[0]]
+        records = EvidenceStore(_store_location(arguments, arguments.target)).history()
+        evidence = next((record["evidence"] for record in reversed(records) if any(item.get("capabilityId") == capability for item in record["evidence"].get("capabilityResults", []))), None)
+        if evidence is None: raise ValueError("no persisted evidence is available for this capability; run assess first")
+    except ValueError as error:
+        _render({"command": "report", "status": "BLOCKED", "reason": str(error)}, arguments.format, stream); return ExitCode.BLOCKED
+    if evidence["runtimeQualification"]["level"] != "QUALIFIED":
+        _render({"command": "report", "status": "BLOCKED", "reason": "capability evidence is not qualified"}, arguments.format, stream); return ExitCode.BLOCKED
+    _render_capability_report(evidence, capability, arguments.format, stream); return ExitCode.SUCCESS
+
+
+def console_main() -> None:
+    raise SystemExit(main())

tde_runtime/__init__.py

@@ -0,0 +1,6 @@
+"""Public, CLI-independent API for the Technical Debt Engine runtime foundation."""
+
+from .configuration import RuntimeConfiguration
+from .runtime import Runtime
+
+__all__ = ["Runtime", "RuntimeConfiguration"]

tde_runtime/baseline.py

@@ -0,0 +1,196 @@
+"""Immutable canonical-evidence baselines and deterministic comparisons."""
+
+from __future__ import annotations
+
+from hashlib import sha256
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+from .models import utc_now
+
+
+class BaselineError(ValueError):
+    """Raised when a baseline cannot be created, loaded, or compared."""
+
+
+class BaselineRepository:
+    def __init__(self, location: str | Path) -> None:
+        self.location = Path(location)
+
+    def create(self, evidence: Mapping[str, Any], name: str | None = None) -> dict[str, Any]:
+        self._validate_evidence(evidence)
+        created_at = utc_now()
+        digest = evidence["integrity"]["contentDigest"]
+        identity = sha256(f"{digest}:{created_at}".encode()).hexdigest()[:16]
+        baseline_id = name or f"baseline.{identity}"
+        destination = self.location / f"{baseline_id}.json"
+        if destination.exists():
+            raise BaselineError(f"baseline already exists and is immutable: {baseline_id}")
+        record = {"baselineId": baseline_id, "sourceEvidenceId": digest,
+                  "repositoryId": evidence["repository"]["id"], "candidateId": evidence["candidate"]["id"],
+                  "schemaVersion": evidence["schemaVersion"], "runtimeVersion": evidence["runtime"]["version"],
+                  "createdAt": created_at,
+                  "capabilityVersions": {item["capabilityId"]: item.get("capabilityVersion")
+                                         for item in evidence.get("capabilityResults", [])},
+                  "policyVersion": evidence.get("policyEvidence", {}).get("policy", {}).get("version"),
+                  "integrityDigest": f"sha256:{sha256(json.dumps(evidence, sort_keys=True).encode()).hexdigest()}",
+                  "evidence": evidence}
+        self.location.mkdir(parents=True, exist_ok=True)
+        destination.write_text(json.dumps(record, sort_keys=True, indent=2) + "\n", encoding="utf-8")
+        return record
+
+    def load(self, reference: str | Path) -> dict[str, Any]:
+        path = Path(reference)
+        path = path if path.is_absolute() or path.exists() else self.location / f"{reference}.json"
+        try:
+            value = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise BaselineError(f"cannot load baseline {reference}: {error}") from error
+        if not isinstance(value, dict) or "evidence" not in value:
+            raise BaselineError("baseline does not contain canonical evidence")
+        self._validate_evidence(value["evidence"])
+        return value
+
+    @staticmethod
+    def _validate_evidence(evidence: Mapping[str, Any]) -> None:
+        if evidence.get("schemaId") != "tde.evidence" or evidence.get("validation", {}).get("status") != "VALID":
+            raise BaselineError("baseline requires validated canonical evidence")
+
+
+class ComparisonEngine:
+    """Compares canonical evidence; it never produces a qualification decision."""
+
+    def compare(self, current: Mapping[str, Any], baseline: Mapping[str, Any]) -> dict[str, Any]:
+        BaselineRepository._validate_evidence(current)
+        previous = baseline["evidence"]
+        compatible = self._compatible(current, previous)
+        baseline_id = baseline["baselineId"]
+        if not compatible:
+            return self._blocked(current, baseline_id, "schema, runtime, or repository compatibility failed")
+        metric_deltas, metric_limitations = self._metrics(current.get("measurements", []), previous.get("measurements", []))
+        finding_transitions, regressions, improvements = self._findings(current.get("findings", []), previous.get("findings", []))
+        return {"comparisonId": self._identity(current, baseline_id),
+                "currentEvidenceId": current["integrity"]["contentDigest"], "baselineEvidenceId": previous["integrity"]["contentDigest"],
+                "baselineId": baseline_id, "schemaCompatibility": "COMPATIBLE", "metricDeltas": metric_deltas,
+                "findingTransitions": finding_transitions, "regressions": regressions, "improvements": improvements,
+                "unchangedFindings": [item["findingId"] for item in finding_transitions if item["transition"] == "UNCHANGED"],
+                "capabilityComparison": self._capabilities(current, previous), "limitations": metric_limitations, "status": "VALID"}
+
+    @staticmethod
+    def _compatible(current: Mapping[str, Any], baseline: Mapping[str, Any]) -> bool:
+        return (current.get("schemaVersion") == baseline.get("schemaVersion") and
+                current.get("runtime", {}).get("version") == baseline.get("runtime", {}).get("version") and
+                current.get("repository", {}).get("id") == baseline.get("repository", {}).get("id"))
+
+    def _blocked(self, current: Mapping[str, Any], baseline_id: str, reason: str) -> dict[str, Any]:
+        return {"comparisonId": self._identity(current, baseline_id), "currentEvidenceId": current["integrity"]["contentDigest"],
+                "baselineEvidenceId": "unknown", "baselineId": baseline_id, "schemaCompatibility": "INCOMPATIBLE",
+                "metricDeltas": [], "findingTransitions": [], "regressions": [], "improvements": [], "unchangedFindings": [], "capabilityComparison": [],
+                "limitations": [{"reason": reason, "blocking": True}], "status": "BLOCKED"}
+
+    @staticmethod
+    def _metrics(current: list[Mapping[str, Any]], baseline: list[Mapping[str, Any]]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+        key = lambda item: (item.get("metricKey"), item.get("scope"), item.get("targetEntityId"))
+        old = {key(item): item for item in baseline if isinstance(item.get("value"), (int, float))}
+        deltas: list[dict[str, Any]] = []
+        limitations: list[dict[str, Any]] = []
+        for item in current:
+            if key(item) not in old or not isinstance(item.get("value"), (int, float)):
+                continue
+            previous = old[key(item)]["value"]
+            value = item["value"]
+            delta = value - previous
+            percentage = None if previous == 0 else delta / previous
+            if previous == 0:
+                limitations.append({"reason": f"percentage delta unavailable for {item.get('metricKey')}", "blocking": False})
+            deltas.append({"metricKey": item.get("metricKey"), "scope": item.get("scope"), "baseline": previous,
+                           "current": value, "numericDelta": delta, "percentageDelta": percentage,
+                           "ratioDelta": delta if item.get("unit") == "ratio" else None,
+                           "distributionDelta": None, "trend": "INCREASED" if delta > 0 else "DECREASED" if delta < 0 else "UNCHANGED"})
+        return deltas, limitations
+
+    @staticmethod
+    def _findings(current: list[Mapping[str, Any]], baseline: list[Mapping[str, Any]]) -> tuple[list[dict[str, Any]], list[str], list[str]]:
+        old, new = ({item.get("findingId"): item for item in values} for values in (baseline, current))
+        severity = {"INFO": 0, "LOW": 1, "MEDIUM": 2, "HIGH": 3, "CRITICAL": 4}
+        transitions: list[dict[str, Any]] = []
+        regressions: list[str] = []
+        improvements: list[str] = []
+        for finding_id in sorted(set(old) | set(new)):
+            if finding_id not in old:
+                transition = "INTRODUCED"; regressions.append(finding_id)
+            elif finding_id not in new:
+                transition = "RESOLVED"; improvements.append(finding_id)
+            else:
+                before, after = severity.get(old[finding_id].get("severity"), 0), severity.get(new[finding_id].get("severity"), 0)
+                transition = "SEVERITY_INCREASED" if after > before else "SEVERITY_DECREASED" if after < before else "UNCHANGED"
+                (regressions if after > before else improvements if after < before else []).append(finding_id)
+            transitions.append({"findingId": finding_id, "transition": transition})
+        return transitions, regressions, improvements
+
+    @staticmethod
+    def _capabilities(current: Mapping[str, Any], baseline: Mapping[str, Any]) -> list[dict[str, Any]]:
+        old = {item["capabilityId"]: item for item in baseline.get("capabilityResults", [])}
+        return [{"capabilityId": item["capabilityId"], "comparisonSupport": "SUPPORTED" if item["capabilityId"] in old else "UNSUPPORTED",
+                 "limitations": [] if item["capabilityId"] in old else ["baseline has no compatible capability result"]}
+                for item in current.get("capabilityResults", [])]
+
+    @staticmethod
+    def _identity(current: Mapping[str, Any], baseline_id: str) -> str:
+        return "comparison." + sha256(f"{current['integrity']['contentDigest']}:{baseline_id}".encode()).hexdigest()[:16]
+
+
+class ComparisonRepository:
+    """Immutable repository for comparison evidence and its policy projection."""
+
+    def __init__(self, location: str | Path) -> None:
+        self.location = Path(location)
+
+    def persist(self, comparison: Mapping[str, Any], policy_evidence: Mapping[str, Any],
+                baseline: Mapping[str, Any]) -> dict[str, Any]:
+        if comparison.get("status") not in {"VALID", "BLOCKED"} or not comparison.get("comparisonId"):
+            raise BaselineError("comparison requires canonical comparison evidence")
+        payload = {"comparison": dict(comparison), "policyEvidence": dict(policy_evidence),
+                   "qualificationDelta": self._qualification_delta(
+                       baseline.get("evidence", {}).get("policyEvidence", {}).get("decision", "NOT_APPLICABLE"),
+                       policy_evidence.get("decision", "BLOCKED"))}
+        digest = "sha256:" + sha256(json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+        comparison_id = str(comparison["comparisonId"])
+        path = self.location / f"{comparison_id}.json"
+        if path.exists():
+            existing = self.load(comparison_id)
+            if existing["comparisonDigest"] != digest:
+                raise BaselineError(f"comparison identity collision: {comparison_id}")
+            return existing
+        record = {"comparisonId": comparison_id, "baselineId": comparison.get("baselineId"),
+                  "currentIdentity": comparison.get("currentEvidenceId"),
+                  "baselineIdentity": comparison.get("baselineEvidenceId"), "createdAt": utc_now(),
+                  "comparisonDigest": digest, **payload}
+        self.location.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(record, sort_keys=True, indent=2) + "\n", encoding="utf-8")
+        return record
+
+    def load(self, reference: str | Path) -> dict[str, Any]:
+        path = Path(reference)
+        path = path if path.is_absolute() or path.exists() else self.location / f"{reference}.json"
+        try:
+            record = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise BaselineError(f"cannot load comparison {reference}: {error}") from error
+        payload = {key: record.get(key) for key in ("comparison", "policyEvidence", "qualificationDelta")}
+        digest = "sha256:" + sha256(json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+        if digest != record.get("comparisonDigest"):
+            raise BaselineError("comparison evidence integrity check failed")
+        return record
+
+    def history(self) -> list[dict[str, Any]]:
+        return [self.load(path) for path in sorted(self.location.glob("*.json"))] if self.location.is_dir() else []
+
+    @staticmethod
+    def _qualification_delta(baseline: str, current: str) -> dict[str, str]:
+        # A baseline without applicable policy evidence is neutral; a newly
+        # applicable passing policy is not a qualification regression.
+        rank = {"NOT_APPLICABLE": 1, "PASS": 1, "PASS_WITH_WARNINGS": 2, "FAIL": 3, "BLOCKED": 4}
+        direction = "REGRESSED" if rank.get(current, 4) > rank.get(baseline, 4) else "IMPROVED" if rank.get(current, 4) < rank.get(baseline, 4) else "UNCHANGED"
+        return {"baselineDecision": baseline, "currentDecision": current, "direction": direction}