verification-ecology-kit 1.0.0__py3-none-any.whl

verification_ecology_kit/__init__.py

@@ -0,0 +1,58 @@
+"""Public API for verification-ecology-kit."""
+
+from verification_ecology_kit.audit.reports import AuditEngine
+from verification_ecology_kit.canonicalization import Canonicalizer
+from verification_ecology_kit.digest import DigestPolicy
+from verification_ecology_kit.model.authority import AuthorityEngine
+from verification_ecology_kit.model.certification import CertificationEngine
+from verification_ecology_kit.model.conformance import ConformanceEngine, VetBundle
+from verification_ecology_kit.model.ecology_state import VerifierEcologyState
+from verification_ecology_kit.model.history import ObservableProcessHistory
+from verification_ecology_kit.model.ledger import ResidualLedger, TraceCertificate
+from verification_ecology_kit.model.maturity import MaturityProfile
+from verification_ecology_kit.model.overclosure import OverclosureWitness
+from verification_ecology_kit.model.packets import (
+    BoundaryTesterPacket,
+    CounterPacket,
+    VerifierPacket,
+)
+from verification_ecology_kit.model.residuals import ResidualRecord
+from verification_ecology_kit.operations.base import PacketOperationEngine
+from verification_ecology_kit.references import (
+    DigestRecord,
+    ObjectEnvelope,
+    ObjectRef,
+    ReferenceEdge,
+    SchemaMigrationWitness,
+)
+from verification_ecology_kit.runtime.engine import RuntimeEngine
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "AuditEngine",
+    "AuthorityEngine",
+    "BoundaryTesterPacket",
+    "Canonicalizer",
+    "CertificationEngine",
+    "ConformanceEngine",
+    "CounterPacket",
+    "DigestPolicy",
+    "DigestRecord",
+    "MaturityProfile",
+    "ObjectEnvelope",
+    "ObjectRef",
+    "ObservableProcessHistory",
+    "OverclosureWitness",
+    "PacketOperationEngine",
+    "ReferenceEdge",
+    "ResidualLedger",
+    "ResidualRecord",
+    "RuntimeEngine",
+    "SchemaMigrationWitness",
+    "TraceCertificate",
+    "VerifierEcologyState",
+    "VerifierPacket",
+    "VetBundle",
+    "__version__",
+]

verification_ecology_kit/audit/__init__.py

@@ -0,0 +1 @@
+"""Audit engines."""

verification_ecology_kit/audit/adversarial_ingress.py

@@ -0,0 +1,31 @@
+"""Adversarial packet ingress audit."""
+
+from __future__ import annotations
+
+from verification_ecology_kit.audit.reports import AuditFinding, AuditReport
+from verification_ecology_kit.model.packets import VerifierPacket
+from verification_ecology_kit.model.records import TrustStatus, Visibility
+
+
+def audit_adversarial_ingress(packet: VerifierPacket) -> AuditReport:
+    findings: list[AuditFinding] = []
+    status = packet.circulation_status
+    if status is None:
+        findings.append(
+            AuditFinding("missing_circulation_status", "Packet has no circulation status.")
+        )
+    elif (
+        status.trust_status in {TrustStatus.LOW_TRUST, TrustStatus.ADVERSARIAL}
+        and status.visibility != Visibility.QUARANTINED
+    ):
+        findings.append(
+            AuditFinding(
+                "low_trust_not_quarantined",
+                "Low-trust or adversarial packet must be quarantined before internalization.",
+                severity="high",
+                evidence_refs=(packet.packet_id,),
+                suggested_repair_hooks=("quarantine_packet",),
+            )
+        )
+    decision = "pass" if not findings else "quarantine"
+    return AuditReport("adversarial-ingress", decision, findings=findings).finalize()

verification_ecology_kit/audit/aperture_regression.py

@@ -0,0 +1,45 @@
+"""Aperture regression audit."""
+
+from __future__ import annotations
+
+from verification_ecology_kit.audit.reports import AuditFinding, AuditReport
+from verification_ecology_kit.model.aperture import Aperture
+
+
+def audit_aperture_regression(before: Aperture, after: Aperture) -> AuditReport:
+    findings: list[AuditFinding] = []
+    if before.strict_capacity_leq(after):
+        return AuditReport(
+            audit_name="aperture-regression",
+            decision="pass",
+            passed_checks=["strict_capacity_comparison"],
+        ).finalize()
+    if before.accountable_loss_leq(after):
+        findings.append(
+            AuditFinding(
+                code="accountable_aperture_loss",
+                message="Feasible aperture decreased, but the loss is residualized.",
+                severity="low",
+                suggested_repair_hooks=("review_aperture_debt",),
+            )
+        )
+        return AuditReport(
+            audit_name="aperture-regression",
+            decision="residualize",
+            findings=findings,
+            residualized_failures=["aperture_debt"],
+        ).finalize()
+    findings.append(
+        AuditFinding(
+            code="silent_aperture_loss",
+            message="Feasible aperture decreased without a residual obligation.",
+            severity="high",
+            suggested_repair_hooks=("create_aperture_debt_residual",),
+        )
+    )
+    return AuditReport(
+        audit_name="aperture-regression",
+        decision="reject",
+        findings=findings,
+        support_blocking_failures=["aperture_debt"],
+    ).finalize()

verification_ecology_kit/audit/local_info.py

@@ -0,0 +1,82 @@
+"""Local information leak scanner."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from verification_ecology_kit.audit.reports import AuditFinding, AuditReport
+
+LOCAL_PATH_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(r"[A-Za-z]:[\\/](?:Users|Documents and Settings)[\\/][^\\/\s]+", re.IGNORECASE),
+    re.compile(r"/(?:Users|home)/[^/\s]+", re.IGNORECASE),
+)
+EMAIL_PATTERN = re.compile(r"\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b", re.IGNORECASE)
+
+
+def scan_local_info(path: Path, *, allowlist: tuple[str, ...] = ()) -> AuditReport:
+    findings: list[AuditFinding] = []
+    for file_path in _iter_text_files(path):
+        text = file_path.read_text(encoding="utf-8", errors="ignore")
+        for pattern in LOCAL_PATH_PATTERNS:
+            for match in pattern.finditer(text):
+                value = match.group(0)
+                if any(item in value for item in allowlist):
+                    continue
+                findings.append(
+                    AuditFinding(
+                        "local_information_leak",
+                        f"Local path-like value in {file_path.as_posix()}",
+                        severity="high",
+                    )
+                )
+        for match in EMAIL_PATTERN.finditer(text):
+            value = match.group(0)
+            if any(item in value for item in allowlist):
+                continue
+            findings.append(
+                AuditFinding(
+                    "private_email",
+                    f"Email-like value in {file_path.as_posix()}",
+                    severity="medium",
+                )
+            )
+    return AuditReport(
+        "local-info",
+        "pass" if not findings else "quarantine",
+        findings=findings,
+        support_blocking_failures=["local_information_leak"] if findings else [],
+    ).finalize()
+
+
+def _iter_text_files(path: Path) -> list[Path]:
+    if path.is_file():
+        return [path]
+    excluded = {
+        ".git",
+        ".venv",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".mypy_cache",
+        ".hypothesis",
+        "__pycache__",
+        "dist",
+        "build",
+        "site",
+    }
+    files: list[Path] = []
+    for file_path in path.rglob("*"):
+        if any(part in excluded for part in file_path.parts):
+            continue
+        if file_path.name == ".coverage":
+            continue
+        if file_path.is_file() and file_path.suffix.lower() not in {
+            ".pyc",
+            ".png",
+            ".jpg",
+            ".jpeg",
+            ".gif",
+            ".pdf",
+        }:
+            files.append(file_path)
+    return files

verification_ecology_kit/audit/monoculture.py

@@ -0,0 +1,34 @@
+"""Verifier monoculture audit."""
+
+from __future__ import annotations
+
+from verification_ecology_kit.audit.reports import AuditFinding, AuditReport
+from verification_ecology_kit.model.overclosure import VerifierMonocultureDetector
+
+
+def audit_monoculture(
+    *,
+    origin_assumptions: list[tuple[str, ...]],
+    question_forms: list[tuple[str, ...]],
+    residual_filters: list[tuple[str, ...]],
+    counter_packet_routes: list[tuple[str, ...]],
+) -> AuditReport:
+    result = VerifierMonocultureDetector().detect(
+        origin_assumptions=origin_assumptions,
+        question_forms=question_forms,
+        residual_filters=residual_filters,
+        counter_packet_routes=counter_packet_routes,
+    )
+    findings = [
+        AuditFinding(
+            code=code.value,
+            message="Packet population has shared assumptions, filters, or missing counter routes.",
+            suggested_repair_hooks=result.suggested_repair_hooks,
+        )
+        for code in result.failure_codes
+    ]
+    return AuditReport(
+        "monoculture",
+        "pass" if result.passed else "residualize",
+        findings=findings,
+    ).finalize()

verification_ecology_kit/audit/packet_ecology.py

@@ -0,0 +1,39 @@
+"""Packet ecology audit."""
+
+from __future__ import annotations
+
+from verification_ecology_kit.audit.reports import AuditFinding, AuditReport
+from verification_ecology_kit.model.packets import VerifierPacket
+
+
+def audit_packet_ecology(packets: list[VerifierPacket]) -> AuditReport:
+    findings: list[AuditFinding] = []
+    passed: list[str] = []
+    residualized: list[str] = []
+    blocking: list[str] = []
+    for packet in packets:
+        for result in packet.validate():
+            if result.passed:
+                passed.append(f"{packet.packet_id}:{result.check_name}")
+                continue
+            codes = [code.value for code in result.failure_codes]
+            residualized.extend(codes)
+            if result.support_blocking_failures:
+                blocking.extend(code.value for code in result.support_blocking_failures)
+            findings.append(
+                AuditFinding(
+                    code=",".join(codes) or result.check_name,
+                    message=f"Packet {packet.packet_id} requires {result.check_name}",
+                    evidence_refs=(packet.packet_id,),
+                    suggested_repair_hooks=result.suggested_repair_hooks,
+                )
+            )
+    decision = "pass" if not findings else "residualize"
+    return AuditReport(
+        audit_name="packet-ecology",
+        decision=decision,
+        findings=findings,
+        passed_checks=passed,
+        residualized_failures=residualized,
+        support_blocking_failures=blocking,
+    ).finalize()

verification_ecology_kit/audit/reports.py

@@ -0,0 +1,97 @@
+"""Shared audit reports and aggregate audit engine."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+from verification_ecology_kit.canonicalization import Canonicalizer
+from verification_ecology_kit.digest import DigestPolicy
+from verification_ecology_kit.model.aperture import Aperture
+from verification_ecology_kit.model.ecology_state import VerifierEcologyState
+from verification_ecology_kit.model.packets import VerifierPacket
+
+
+@dataclass(frozen=True)
+class AuditFinding:
+    code: str
+    message: str
+    severity: str = "medium"
+    evidence_refs: tuple[str, ...] = ()
+    suggested_repair_hooks: tuple[str, ...] = ()
+
+
+@dataclass
+class AuditReport:
+    audit_name: str
+    decision: str
+    findings: list[AuditFinding] = field(default_factory=list)
+    passed_checks: list[str] = field(default_factory=list)
+    residualized_failures: list[str] = field(default_factory=list)
+    support_blocking_failures: list[str] = field(default_factory=list)
+    evidence_refs: list[str] = field(default_factory=list)
+    provenance: list[str] = field(default_factory=list)
+    report_digest: str = ""
+
+    def finalize(self) -> AuditReport:
+        payload = self.to_dict(include_digest=False)
+        self.report_digest = (
+            DigestPolicy().digest_json(payload, canonicalizer=Canonicalizer()).value
+        )
+        return self
+
+    def to_dict(self, *, include_digest: bool = True) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "audit_name": self.audit_name,
+            "decision": self.decision,
+            "findings": [
+                {
+                    "code": finding.code,
+                    "message": finding.message,
+                    "severity": finding.severity,
+                    "evidence_refs": list(finding.evidence_refs),
+                    "suggested_repair_hooks": list(finding.suggested_repair_hooks),
+                }
+                for finding in self.findings
+            ],
+            "passed_checks": self.passed_checks,
+            "residualized_failures": self.residualized_failures,
+            "support_blocking_failures": self.support_blocking_failures,
+            "evidence_refs": self.evidence_refs,
+            "provenance": self.provenance,
+        }
+        if include_digest:
+            data["report_digest"] = self.report_digest
+        return data
+
+    def to_json(self) -> str:
+        self.finalize()
+        return json.dumps(self.to_dict(), indent=2, sort_keys=True)
+
+    def to_markdown(self) -> str:
+        self.finalize()
+        lines = [f"# {self.audit_name}", "", f"Decision: `{self.decision}`", ""]
+        if not self.findings:
+            lines.append("No findings.")
+        for finding in self.findings:
+            lines.append(f"- `{finding.code}` {finding.severity}: {finding.message}")
+        lines.extend(["", f"Report digest: `{self.report_digest}`"])
+        return "\n".join(lines)
+
+
+class AuditEngine:
+    def packet_ecology(self, packets: list[VerifierPacket]) -> AuditReport:
+        from verification_ecology_kit.audit.packet_ecology import audit_packet_ecology
+
+        return audit_packet_ecology(packets)
+
+    def residual_metabolism(self, state: VerifierEcologyState) -> AuditReport:
+        from verification_ecology_kit.audit.residual_metabolism import audit_residual_metabolism
+
+        return audit_residual_metabolism(state)
+
+    def aperture_regression(self, before: Aperture, after: Aperture) -> AuditReport:
+        from verification_ecology_kit.audit.aperture_regression import audit_aperture_regression
+
+        return audit_aperture_regression(before, after)

verification_ecology_kit/audit/residual_metabolism.py

@@ -0,0 +1,39 @@
+"""Residual metabolism audit."""
+
+from __future__ import annotations
+
+from verification_ecology_kit.audit.reports import AuditFinding, AuditReport
+from verification_ecology_kit.model.ecology_state import VerifierEcologyState
+from verification_ecology_kit.model.records import LedgerStatus
+from verification_ecology_kit.model.residuals import check_residual_liveness
+
+
+def audit_residual_metabolism(state: VerifierEcologyState) -> AuditReport:
+    findings: list[AuditFinding] = []
+    passed: list[str] = []
+    residualized: list[str] = []
+    for residual in state.residual_ledger.residuals.values():
+        if residual.status != LedgerStatus.ACTIVE:
+            passed.append(f"{residual.residual_id}:inactive_disposition")
+            continue
+        result = check_residual_liveness(residual)
+        if result.passed:
+            passed.append(f"{residual.residual_id}:live")
+        else:
+            residualized.extend(code.value for code in result.failure_codes)
+            findings.append(
+                AuditFinding(
+                    code="liveness_debt",
+                    message=f"Residual {residual.residual_id} is active without a live route",
+                    evidence_refs=(residual.residual_id,),
+                    suggested_repair_hooks=("route_residual", "retire_with_reason", "quarantine"),
+                )
+            )
+    decision = "pass" if not findings else "residualize"
+    return AuditReport(
+        audit_name="residual-metabolism",
+        decision=decision,
+        findings=findings,
+        passed_checks=passed,
+        residualized_failures=residualized,
+    ).finalize()

verification_ecology_kit/audit/schema_overclosure.py

@@ -0,0 +1,33 @@
+"""Schema-overclosure audit."""
+
+from __future__ import annotations
+
+from verification_ecology_kit.audit.reports import AuditFinding, AuditReport
+from verification_ecology_kit.model.overclosure import SchemaOverclosureDetector
+
+
+def audit_schema_overclosure(
+    *,
+    schema_rejected_unknown: bool,
+    suppressed_residuals: tuple[str, ...] = (),
+    dashboard_hid_component_failure: bool = False,
+) -> AuditReport:
+    result, residuals = SchemaOverclosureDetector().detect(
+        schema_rejected_unknown=schema_rejected_unknown,
+        suppressed_residuals=suppressed_residuals,
+        dashboard_hid_component_failure=dashboard_hid_component_failure,
+    )
+    findings = [
+        AuditFinding(
+            code=code.value,
+            message="Schema behavior may suppress residuals or unknowns.",
+            evidence_refs=tuple(residual.residual_id for residual in residuals),
+            suggested_repair_hooks=result.suggested_repair_hooks,
+        )
+        for code in result.failure_codes
+    ]
+    return AuditReport(
+        "schema-overclosure",
+        "pass" if result.passed else "residualize",
+        findings=findings,
+    ).finalize()

verification_ecology_kit/audit/security.py

@@ -0,0 +1,150 @@
+"""Secret and package safety scanners."""
+
+from __future__ import annotations
+
+import re
+import tarfile
+import zipfile
+from pathlib import Path
+
+from verification_ecology_kit.audit.reports import AuditFinding, AuditReport
+
+TOKEN_PREFIXES = ("sk" + "-", "gh" + "p_", "gh" + "o_", "pypi" + "-")
+PRIVATE_KEY_MARKER = "BEGIN " + "PRIVATE KEY"
+AWS_ACCESS_KEY = "AK" + "IA"
+
+
+def scan_secrets(path: Path) -> AuditReport:
+    findings: list[AuditFinding] = []
+    token_pattern = re.compile(
+        "(" + "|".join(re.escape(prefix) for prefix in TOKEN_PREFIXES) + r")[A-Za-z0-9_\-]{12,}"
+    )
+    for file_path in _iter_text_files(path):
+        text = file_path.read_text(encoding="utf-8", errors="ignore")
+        if PRIVATE_KEY_MARKER in text:
+            findings.append(
+                AuditFinding("private_key", f"Private key marker in {file_path.as_posix()}", "high")
+            )
+        if AWS_ACCESS_KEY in text:
+            findings.append(
+                AuditFinding(
+                    "cloud_credential", f"Cloud key marker in {file_path.as_posix()}", "high"
+                )
+            )
+        if token_pattern.search(text):
+            findings.append(
+                AuditFinding("token", f"Token-like value in {file_path.as_posix()}", "high")
+            )
+        if file_path.name.startswith(".env") and file_path.name != ".env.example":
+            findings.append(
+                AuditFinding(
+                    "env_file", f"Environment file included: {file_path.as_posix()}", "high"
+                )
+            )
+    return AuditReport(
+        "security",
+        "pass" if not findings else "quarantine",
+        findings=findings,
+        support_blocking_failures=["secret_leak"] if findings else [],
+    ).finalize()
+
+
+def verify_package_paths(paths: list[Path]) -> AuditReport:
+    findings: list[AuditFinding] = []
+    forbidden_suffixes = {".aux", ".bbl", ".bcf", ".blg", ".log", ".out", ".toc", ".pdf"}
+    for path in paths:
+        if path.suffix.lower() in forbidden_suffixes:
+            findings.append(
+                AuditFinding(
+                    "package_content_leak", f"Forbidden build artifact: {path.as_posix()}", "high"
+                )
+            )
+        if ".ipynb_checkpoints" in path.parts:
+            findings.append(
+                AuditFinding(
+                    "package_content_leak", f"Notebook checkpoint: {path.as_posix()}", "high"
+                )
+            )
+    return AuditReport(
+        "package-contents",
+        "pass" if not findings else "quarantine",
+        findings=findings,
+        support_blocking_failures=["package_content_leak"] if findings else [],
+    ).finalize()
+
+
+def verify_package_archives(dist: Path) -> AuditReport:
+    findings: list[AuditFinding] = []
+    paths: list[Path] = []
+    evidence_refs: list[str] = []
+    wheels = 0
+    sdists = 0
+
+    if not dist.exists():
+        findings.append(
+            AuditFinding("package_artifact_missing", "dist directory is missing", "high")
+        )
+    else:
+        for archive in dist.iterdir():
+            if archive.suffix == ".whl":
+                wheels += 1
+                evidence_refs.append(archive.as_posix())
+                with zipfile.ZipFile(archive) as wheel:
+                    paths.extend(Path(name) for name in wheel.namelist())
+            elif archive.suffixes[-2:] == [".tar", ".gz"]:
+                sdists += 1
+                evidence_refs.append(archive.as_posix())
+                with tarfile.open(archive) as sdist:
+                    paths.extend(Path(member.name) for member in sdist.getmembers())
+
+    if wheels == 0:
+        findings.append(
+            AuditFinding("package_artifact_missing", "wheel artifact is missing", "high")
+        )
+    if sdists == 0:
+        findings.append(
+            AuditFinding("package_artifact_missing", "sdist artifact is missing", "high")
+        )
+
+    content_report = verify_package_paths(paths)
+    findings.extend(content_report.findings)
+    return AuditReport(
+        "package-contents",
+        "pass" if not findings else "quarantine",
+        findings=findings,
+        support_blocking_failures=["package_content_leak"] if findings else [],
+        evidence_refs=evidence_refs,
+    ).finalize()
+
+
+def _iter_text_files(path: Path) -> list[Path]:
+    if path.is_file():
+        return [path]
+    excluded = {
+        ".git",
+        ".venv",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".mypy_cache",
+        ".hypothesis",
+        "__pycache__",
+        "dist",
+        "build",
+        "site",
+    }
+    files: list[Path] = []
+    for file_path in path.rglob("*"):
+        if any(part in excluded for part in file_path.parts):
+            continue
+        if file_path.name == ".coverage":
+            continue
+        if file_path.is_file() and file_path.suffix.lower() not in {
+            ".pyc",
+            ".png",
+            ".jpg",
+            ".jpeg",
+            ".gif",
+            ".pdf",
+        }:
+            files.append(file_path)
+    return files