equiframe 0.12.4__py3-none-any.whl

equiframe/assertions.py

@@ -0,0 +1,271 @@
+"""Fail-closed assertions and integration decisions over existing comparisons.
+
+Nothing here compares data again, changes its policy or authenticates a producer.
+By default no evidence files are opened. Optional bounded verification checks
+only the current comparison manifest and its complete differences, under an
+explicit caller-authorized root. Reports must be written separately beforehand.
+"""
+
+from __future__ import annotations
+
+import errno
+import json
+from pathlib import Path
+from typing import cast
+
+from equiframe.assertion_types import (
+    EquivalenceCode,
+    EquivalenceDecision,
+    EquivalencePolicy,
+    EvidenceFailureCode,
+    EvidenceStatus,
+    GuaranteeFailure,
+)
+from equiframe.comparison_report import comparison_report
+from equiframe.comparison_types import ComparisonResult
+from equiframe.errors import (
+    ArtifactIntegrityError,
+    ArtifactIOError,
+    EquiFrameError,
+    ResourceLimitError,
+)
+from equiframe.report_types import ReportOptions
+
+
+class EquivalenceInputError(ValueError, EquiFrameError):
+    """Invalid caller input or unsupported assertion configuration, not a verdict."""
+
+    code = "invalid_assertion_input"
+
+
+class EquivalenceAssertionError(AssertionError, EquiFrameError):
+    """Safe failure carrying a detached decision, never the raw comparison data."""
+
+    code = "equivalence_not_accepted"
+
+    def __init__(self, decision: EquivalenceDecision, *, report_path: Path | None = None) -> None:
+        self.decision = decision
+        self.code = decision.code
+        messages = {
+            "different": "Comparison differs; review the report and declared policies",
+            "not_evaluable": "Comparison is not evaluable; resolve the diagnostic and rerun",
+            "guarantee_mismatch": "Required comparison context differs; review policy pins",
+            "evidence_missing": "Required evidence is missing; restore finalized comparison files",
+            "evidence_corrupt": "Required evidence failed integrity checks; restore or regenerate",
+            "evidence_path_rejected": "Evidence path was rejected; use a confined local root",
+            "evidence_budget_exceeded": "Evidence verification exceeded its budget; review limits",
+            "evidence_unreadable": "Required evidence is unreadable; check local read access",
+        }
+        message = f"[{decision.code}] {messages.get(decision.code, 'Equivalence was not accepted')}"
+        if decision.safe_reason_code is not None:
+            message += f" (reason: {decision.safe_reason_code})"
+        if report_path is not None:
+            # This is a trusted pointer supplied by the caller, not a result URI.
+            # No resolution or file access. ASCII JSON escapes terminal controls.
+            escaped = json.dumps(str(report_path), ensure_ascii=True)
+            pointer = escaped if len(escaped) <= 240 else escaped[:236] + '..."'
+            message += f"; report: {pointer}"
+        super().__init__(message)
+
+
+class EquivalenceDifferentError(EquivalenceAssertionError):
+    """A completed comparison found differences or contract violations."""
+
+    code = "different"
+
+
+class EquivalenceNotEvaluableError(EquivalenceAssertionError):
+    """A comparison cannot establish equivalence, even if traversal completed."""
+
+    code = "not_evaluable"
+
+
+class EquivalenceGuaranteeError(EquivalenceAssertionError):
+    """Observed equivalence does not satisfy the caller's pinned context."""
+
+    code = "guarantee_mismatch"
+
+
+class EquivalenceEvidenceError(EquivalenceAssertionError):
+    """Observed equivalence lacks the required verified persisted evidence."""
+
+    code = "equivalence_evidence_error"
+
+
+def _validated(
+    result: ComparisonResult, policy: EquivalencePolicy | None, evidence_root: Path | None
+) -> tuple[ComparisonResult, EquivalencePolicy]:
+    __tracebackhide__ = True
+    if not isinstance(result, ComparisonResult):
+        raise EquivalenceInputError(
+            "[invalid_assertion_input] result must be a ComparisonResult, not a report or mapping"
+        ) from None
+    if policy is not None and not isinstance(policy, EquivalencePolicy):
+        raise EquivalenceInputError(
+            "[invalid_assertion_input] policy must be an EquivalencePolicy or None"
+        ) from None
+    if evidence_root is not None and not isinstance(evidence_root, Path):
+        raise EquivalenceInputError(
+            "[invalid_assertion_input] evidence_root must be an explicit pathlib.Path"
+        ) from None
+    if evidence_root is not None and (
+        "\x00" in str(evidence_root)
+        or any(0xD800 <= ord(char) <= 0xDFFF for char in str(evidence_root))
+    ):
+        raise EquivalenceInputError(
+            "[invalid_assertion_input] evidence_root must contain a valid local path"
+        ) from None
+    try:
+        # FrozenModel revalidates instances recursively, including model_copy and
+        # model_construct bypasses. Do not coerce mappings or serialized reports.
+        result = ComparisonResult.model_validate(result, strict=True)
+        policy = EquivalencePolicy.model_validate(
+            policy if policy is not None else EquivalencePolicy(), strict=True
+        )
+    except (ValueError, TypeError, AttributeError, RecursionError):
+        raise EquivalenceInputError(
+            "[invalid_assertion_input] invalid comparison result or assertion policy; "
+            "recreate it through the typed API"
+        ) from None
+    if policy.require_persisted_evidence != (evidence_root is not None):
+        raise EquivalenceInputError(
+            "[invalid_assertion_input] require_persisted_evidence and an explicit evidence_root "
+            "must be supplied together"
+        ) from None
+    return result, policy
+
+
+def _inspect(
+    result: ComparisonResult, policy: EquivalencePolicy, root: Path | None
+) -> tuple[EvidenceStatus, EvidenceFailureCode | None]:
+    __tracebackhide__ = True
+    if root is None:
+        return "not_requested", None
+    from equiframe._report_io import EvidencePathError, inspect_evidence
+
+    try:
+        inspect_evidence(
+            result,
+            root,
+            max_bytes=policy.max_evidence_bytes,
+            max_records=policy.max_records,
+            max_examples=0,
+        )
+    except EvidencePathError:
+        return "path_rejected", "evidence_path_rejected"
+    except ResourceLimitError:
+        return "budget_exceeded", "evidence_budget_exceeded"
+    except ArtifactIOError as error:
+        cause = error.__cause__
+        if isinstance(cause, FileNotFoundError):
+            return "missing", "evidence_missing"
+        if isinstance(cause, OSError) and cause.errno in (errno.ELOOP, errno.ENOTDIR):
+            return "path_rejected", "evidence_path_rejected"
+        return "unreadable", "evidence_unreadable"
+    except ArtifactIntegrityError:
+        return "corrupt", "evidence_corrupt"
+    return "verified", None
+
+
+def _safe_reason(result: ComparisonResult) -> str | None:
+    __tracebackhide__ = True
+    if result.state == "equivalent":
+        return None
+    try:
+        report = comparison_report(result, options=ReportOptions(max_examples=1))
+    except Exception:
+        # Presentation is best-effort, with no authority over acceptance. A
+        # formatting failure or budget must not mask the comparison verdict.
+        return None
+    if report.reasons:
+        return report.reasons[0].partition(":")[0]
+    return report.examples[0].code if report.examples else None
+
+
+def equivalence_decision(
+    result: ComparisonResult,
+    *,
+    policy: EquivalencePolicy | None = None,
+    evidence_root: Path | None = None,
+) -> EquivalenceDecision:
+    """Return explicit acceptance of a validated, full output-schema comparison.
+
+    Only equivalent + complete + final counts can pass. Both peer and expected
+    references establish only observed_contract equivalence. Optional pins and
+    persisted evidence can tighten acceptance, never change comparison truth.
+
+    Invalid inputs/configuration raise EquivalenceInputError. Other failures are
+    recorded without raising. Precedence is original state, guarantee pins, then
+    evidence; all requested checks remain visible on the returned decision.
+    Supplying evidence_root requires policy.require_persisted_evidence=True.
+    """
+    __tracebackhide__ = True
+    result, policy = _validated(result, policy, evidence_root)
+    failures: list[GuaranteeFailure] = []
+    for field, required, observed in (
+        ("required_contract_sha256", policy.required_contract_sha256, result.contract_sha256),
+        ("required_spec_sha256", policy.required_spec_sha256, result.spec_sha256),
+        ("required_reference", policy.required_reference, result.reference),
+    ):
+        if required is not None and required != observed:
+            failures.append(cast(GuaranteeFailure, field))
+    evidence_status, evidence_code = _inspect(result, policy, evidence_root)
+    code: EquivalenceCode = (
+        result.state
+        if result.state != "equivalent"
+        else "guarantee_mismatch"
+        if failures
+        else evidence_code or "equivalent"
+    )
+    return EquivalenceDecision(
+        accepted=code == "equivalent",
+        code=code,
+        state=result.state,
+        complete=result.complete,
+        counts_final=result.counts.final,
+        scope=result.scope,
+        reference=result.reference,
+        contract_sha256=result.contract_sha256,
+        spec_sha256=result.spec_sha256,
+        guarantee=policy.guarantee,
+        guarantee_conforms=not failures,
+        guarantee_failures=tuple(failures),
+        evidence_status=evidence_status,
+        evidence_code=evidence_code,
+        safe_reason_code=_safe_reason(result),
+    )
+
+
+def assert_equivalent(
+    result: ComparisonResult,
+    *,
+    policy: EquivalencePolicy | None = None,
+    evidence_root: Path | None = None,
+    report_path: Path | None = None,
+) -> None:
+    """Return None on accepted equivalence; otherwise raise a safe typed assertion.
+
+    Write any desired report before calling. report_path is only a caller-trusted,
+    escaped, bounded pointer displayed on failure; no report is written or read.
+    Values, names, producer diagnostics and result paths are never displayed.
+    Pytest can hide helper frames; a caller's own source/locals and separately
+    published artifacts remain the caller's responsibility.
+    """
+    __tracebackhide__ = True
+    if report_path is not None and not isinstance(report_path, Path):
+        raise EquivalenceInputError(
+            "[invalid_assertion_input] report_path must be a pathlib.Path or None"
+        ) from None
+    decision = equivalence_decision(result, policy=policy, evidence_root=evidence_root)
+    if decision.accepted:
+        return
+    error_type = (
+        EquivalenceDifferentError
+        if decision.code == "different"
+        else EquivalenceNotEvaluableError
+        if decision.code == "not_evaluable"
+        else EquivalenceGuaranteeError
+        if decision.code == "guarantee_mismatch"
+        else EquivalenceEvidenceError
+    )
+    raise error_type(decision, report_path=report_path) from None

equiframe/benchmark.py

@@ -0,0 +1,101 @@
+"""Quarantine for the removed, unsupported auxiliary benchmark draft.
+
+The former implementation supplied placeholder metrics, reused training profiles
+for calibration, and mislabeled row-count comparisons as R. It is not scientific
+evidence. The old function names remain only to give callers an actionable error;
+none executes, reads inputs, fits a detector, computes metrics, or writes files.
+The independent ``equiframe_benchmark`` distribution is not a drop-in replacement.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import TYPE_CHECKING, NoReturn
+
+if TYPE_CHECKING:
+    from equiframe import (
+        DecisionState,
+        DetectorBundle,
+        DetectorSupport,
+        ExecutionResult,
+        IsolationForestConfig,
+        ProfileVector,
+    )
+
+_UNSUPPORTED_MESSAGE = (
+    "equiframe.benchmark is quarantined: the unsupported auxiliary draft has been "
+    "removed and cannot produce benchmark results or evidence. Use the separate "
+    "equiframe_benchmark package following packages/equiframe-benchmark/README.md "
+    "(Instalar y ejecutar), then run 'equiframe-benchmark --help'. This is not a "
+    "drop-in replacement; independent review and experimental protocol requirements "
+    "still apply."
+)
+
+
+class UnsupportedBenchmarkError(RuntimeError):
+    """An attempt to use the quarantined auxiliary benchmark draft."""
+
+
+def run_benchmark(engines: list[str], families: list[str], work_dir: Path) -> NoReturn:
+    """Reject the unsupported draft without running ETL or creating artifacts."""
+    raise UnsupportedBenchmarkError(_UNSUPPORTED_MESSAGE)
+
+
+def collect_profile_vectors(work_dir: Path, families: list[str], engines: list[str]) -> NoReturn:
+    """Reject the unsupported draft without reading any profiles."""
+    raise UnsupportedBenchmarkError(_UNSUPPORTED_MESSAGE)
+
+
+def fit_isolation_forest_mad(
+    training_vectors: list[ProfileVector],
+    config: IsolationForestConfig | None = None,
+    support: DetectorSupport | None = None,
+) -> NoReturn:
+    """Reject the unsupported draft without fitting or calibrating detectors."""
+    raise UnsupportedBenchmarkError(_UNSUPPORTED_MESSAGE)
+
+
+def detect_anomalies(bundle: DetectorBundle, vectors: list[ProfileVector]) -> NoReturn:
+    """Reject the unsupported draft without issuing detector decisions."""
+    raise UnsupportedBenchmarkError(_UNSUPPORTED_MESSAGE)
+
+
+def rule_divergence(results: dict[str, dict[str, list[ExecutionResult]]]) -> NoReturn:
+    """Reject the removed row-count proxy; it did not implement rules R."""
+    raise UnsupportedBenchmarkError(_UNSUPPORTED_MESSAGE)
+
+
+def compute_metrics(
+    rule_diverge: dict[str, list[bool]],
+    model_decisions: list[DecisionState],
+    engines: list[str],
+) -> NoReturn:
+    """Reject the removed placeholder metrics; no metric values are returned."""
+    raise UnsupportedBenchmarkError(_UNSUPPORTED_MESSAGE)
+
+
+def write_summary_tables(
+    work_dir: Path,
+    results: dict[str, dict[str, list[ExecutionResult]]],
+    profile_vectors: list[tuple[str, str, ProfileVector]],
+    m_decisions: list[DecisionState],
+    b_decisions: list[DecisionState],
+    rule_diverge: dict[str, list[bool]],
+    engines: list[str],
+) -> NoReturn:
+    """Reject the unsupported draft without creating or modifying any files."""
+    raise UnsupportedBenchmarkError(_UNSUPPORTED_MESSAGE)
+
+
+def main() -> NoReturn:
+    """Explain quarantine and exit 2; only --help exits successfully."""
+    parser = argparse.ArgumentParser(description=_UNSUPPORTED_MESSAGE)
+    # Accept old options only far enough to provide the quarantine diagnostic.
+    # They never select inputs, create a destination, or execute the old workflow.
+    parser.parse_known_args()
+    parser.error(_UNSUPPORTED_MESSAGE)
+
+
+if __name__ == "__main__":
+    main()

equiframe/bundle.py

@@ -0,0 +1,240 @@
+"""Closed portable evidence, retaining historical bytes and resolving owned artifacts."""
+
+from __future__ import annotations
+
+import hashlib
+import shutil
+from pathlib import Path
+from typing import Literal
+
+from pydantic import model_validator
+from typing_extensions import Self
+
+from equiframe._base import FrozenModel, Text
+from equiframe._regular_io import (
+    new_directory_path,
+    open_regular_file,
+    regular_directory,
+    regular_files,
+)
+from equiframe.errors import ArtifactIntegrityError
+from equiframe.evidence import (
+    MAX_DOCUMENT_BYTES,
+    describe_file,
+    parse_json,
+    publish_json,
+    verify_files,
+)
+from equiframe.local import _bundle_paths, local_path
+from equiframe.pipeline_types import EvidenceFile
+from equiframe.types import ArtifactRef
+
+
+class BundleReference(FrozenModel):
+    uri: Text
+    member: EvidenceFile
+
+
+class EvidenceBundle(FrozenModel):
+    schema_version: Literal["1.0"] = "1.0"
+    kind: Literal["migration", "verification", "workflow"]
+    root_document: Text
+    files: tuple[EvidenceFile, ...]
+    references: tuple[BundleReference, ...]
+    producer: Literal["equiframe"] = "equiframe"
+    producer_version: Text
+
+    @model_validator(mode="after")
+    def consistent(self) -> Self:
+        names = {f.path for f in self.files}
+        if len(names) != len(self.files) or self.root_document not in names:
+            raise ValueError("bundle requires a unique closed inventory and root document")
+        if "bundle.json" in names:
+            raise ValueError("bundle cannot inventory its own root manifest")
+        if len({r.uri for r in self.references}) != len(self.references):
+            raise ValueError("bundle URI mappings must be unique")
+        inventory = {f.path: f for f in self.files}
+        if any(inventory.get(r.member.path) != r.member for r in self.references):
+            raise ValueError("bundle mapping must bind an inventoried member")
+        return self
+
+
+def _members(root: Path) -> tuple[Path, ...]:
+    return regular_files(root)
+
+
+def _references(value: object) -> tuple[ArtifactRef, ...]:
+    result: list[ArtifactRef] = []
+    if isinstance(value, dict):
+        if {"uri", "sha256", "format", "media_type", "size_bytes"} <= value.keys():
+            result.append(ArtifactRef.model_validate(value))
+        else:
+            for child in value.values():
+                result.extend(_references(child))
+    elif isinstance(value, list):
+        for child in value:
+            result.extend(_references(child))
+    return tuple(result)
+
+
+def _document_references(root: Path, members: tuple[Path, ...]) -> dict[str, ArtifactRef]:
+    result: dict[str, ArtifactRef] = {}
+    for path in members:
+        if path.suffix == ".json":
+            with open_regular_file(path) as stream:
+                raw = stream.read(MAX_DOCUMENT_BYTES + 1)
+            if len(raw) > MAX_DOCUMENT_BYTES:
+                raise ArtifactIntegrityError("portable document exceeds its byte budget")
+            for ref in _references(parse_json(raw)):
+                if ref.uri in result and result[ref.uri] != ref:
+                    raise ArtifactIntegrityError("one artifact URI has conflicting identities")
+                result[ref.uri] = ref
+    return result
+
+
+def _inspect(root: Path, kind: str, document: str) -> object:
+    if kind == "migration":
+        from equiframe.migration.io import read_migration
+
+        return read_migration(root / document)
+    if kind == "verification":
+        from equiframe.verify import read_verification
+
+        return read_verification(root / document)
+    from equiframe.workflow import read_workflow
+
+    return read_workflow(root / document)
+
+
+def export_bundle(source: Path, destination: Path) -> EvidenceBundle:
+    """Export checked migration/Verify/workflow bytes to a new directory.
+
+    No artifact is fetched from outside the source. External provenance can map
+    only to an already captured member with exactly the same hash and size.
+    """
+    if source.is_file():
+        with open_regular_file(source):
+            pass
+        source = source.parent
+    source = regular_directory(source).resolve()
+    names = {
+        "migration.json": "migration",
+        "verification.json": "verification",
+        "workflow.json": "workflow",
+    }
+    found = [(name, kind) for name, kind in names.items() if (source / name).is_file()]
+    if len(found) != 1:
+        raise ValueError("export requires one supported finalized operation")
+    document, kind = found[0]
+    members = _members(source)
+    _inspect(source, kind, document)
+    refs = _document_references(source, members)
+    entries = tuple(describe_file(p, source) for p in members)
+    by_path = {f.path: f for f in entries}
+    by_identity = {(f.sha256, f.size_bytes): f for f in entries}
+    mappings: list[BundleReference] = []
+    for ref in refs.values():
+        p = local_path(ref).resolve()
+        item = by_path.get(p.relative_to(source).as_posix()) if p.is_relative_to(source) else None
+        if item is None:
+            item = by_identity.get((ref.sha256, ref.size_bytes))
+        if item is None or (item.sha256, item.size_bytes) != (ref.sha256, ref.size_bytes):
+            raise ArtifactIntegrityError("artifact reference is outside the captured bundle")
+        member = EvidenceFile(
+            path="operation/" + item.path, sha256=item.sha256, size_bytes=item.size_bytes
+        )
+        mappings.append(BundleReference(uri=ref.uri, member=member))
+    destination = new_directory_path(destination)
+    if destination.is_relative_to(source):
+        raise ValueError("portable destination must be outside the source operation")
+    destination.mkdir(parents=True, exist_ok=False)
+    shutil.copytree(source, destination / "operation")
+    from equiframe import __version__
+
+    bundle = EvidenceBundle.model_validate(
+        dict(
+            kind=kind,
+            root_document="operation/" + document,
+            files=tuple(
+                EvidenceFile(path="operation/" + e.path, sha256=e.sha256, size_bytes=e.size_bytes)
+                for e in entries
+            ),
+            references=tuple(mappings),
+            producer_version=__version__,
+        )
+    )
+    publish_json(bundle, destination / "bundle.json")
+    read_bundle(destination)
+    return bundle
+
+
+def read_bundle(path: Path, *, expected_sha256: str | None = None) -> EvidenceBundle:
+    """Verify membership and operation; only None omits the optional manifest pin."""
+    root = path if path.is_dir() else path.parent
+    root = regular_directory(root).resolve()
+    manifest = root / "bundle.json"
+    with open_regular_file(manifest) as stream:
+        raw = stream.read(MAX_DOCUMENT_BYTES + 1)
+    if len(raw) > MAX_DOCUMENT_BYTES:
+        raise ArtifactIntegrityError("portable manifest exceeds its byte budget")
+    if expected_sha256 is not None and hashlib.sha256(raw).hexdigest() != expected_sha256:
+        raise ArtifactIntegrityError("portable manifest differs from trusted SHA-256")
+    parse_json(raw)
+    bundle = EvidenceBundle.model_validate_json(raw)
+    members = _members(root)
+    actual = {p.relative_to(root).as_posix() for p in members if p != manifest}
+    if actual != {f.path for f in bundle.files}:
+        raise ArtifactIntegrityError("portable inventory is not closed")
+    verify_files(root, bundle.files)
+    mappings = {r.uri: root / r.member.path for r in bundle.references}
+    refs = _document_references(root, tuple(p for p in members if p != manifest))
+    if set(refs) != set(mappings):
+        raise ArtifactIntegrityError("portable URI mapping differs from captured documents")
+    for uri, ref in refs.items():
+        entry = next(r.member for r in bundle.references if r.uri == uri)
+        if (entry.sha256, entry.size_bytes) != (ref.sha256, ref.size_bytes):
+            raise ArtifactIntegrityError("portable reference content identity mismatch")
+    with _bundle_paths(mappings):
+        _inspect(root, bundle.kind, bundle.root_document)
+    return bundle
+
+
+def import_bundle(
+    source: Path, destination: Path, *, expected_sha256: str | None = None
+) -> EvidenceBundle:
+    """Copy to a new directory and verify again; original bytes are preserved."""
+    read_bundle(source, expected_sha256=expected_sha256)
+    root = source if source.is_dir() else source.parent
+    destination = new_directory_path(destination)
+    if destination.exists() or destination.is_relative_to(root.resolve()):
+        raise ValueError("bundle import requires a new destination outside the source")
+    shutil.copytree(root, destination)
+    return read_bundle(destination, expected_sha256=expected_sha256)
+
+
+def inspect_bundle(path: Path, *, expected_sha256: str | None = None) -> dict[str, object]:
+    """Inspect semantic/technical outcomes while resolving original portable URIs."""
+    bundle = read_bundle(path, expected_sha256=expected_sha256)
+    root = (path if path.is_dir() else path.parent).resolve()
+    mapping = {r.uri: root / r.member.path for r in bundle.references}
+    with _bundle_paths(mapping):
+        if bundle.kind == "migration":
+            from equiframe.migration.io import migration_summary, read_migration
+
+            outcome = migration_summary(read_migration(root / bundle.root_document))
+        elif bundle.kind == "verification":
+            from equiframe.verify import read_verification, verification_summary
+
+            outcome = verification_summary(read_verification(root / bundle.root_document))
+        else:
+            from equiframe.workflow import read_workflow
+
+            workflow = read_workflow(root / bundle.root_document)
+            outcome = {
+                "run_id": workflow.run_id,
+                "complete": workflow.complete,
+                "exit_code": workflow.exit_code,
+                "first_divergent_stage": workflow.first_divergent_stage,
+                "checkpoints": [c.model_dump(mode="json") for c in workflow.checkpoints],
+            }
+    return {"kind": bundle.kind, "integrity": "passed", "outcome": outcome}