aetherproof-arch 0.1.0a1__py3-none-any.whl

aetherproof/__init__.py

@@ -0,0 +1,76 @@
+"""
+AetherProof v2.0.0 — Empirical Implementation of the Formal Architecture.
+
+Reference implementation of the formal architecture specified in:
+
+    Baladi, S. (2026). AetherProof: Autonomous Formal Verification and
+    Invariant Synthesis for Multi-Agent Software Ecosystems.
+    Zenodo. https://doi.org/10.5281/zenodo.24013124
+
+This is a reference implementation, not a production system.
+No real-world deployment has been evaluated.
+"""
+
+from aetherproof.__version__ import __version__
+
+from aetherproof.models import (
+    CSRecord,
+    Obligation,
+    Counterexample,
+    Verdict,
+    ObligationType,
+    CounterexampleType,
+    Layer,
+)
+from aetherproof.csr.record import CSRRecord
+from aetherproof.csr.relations import SemanticRelation, RelationType
+from aetherproof.obligations.generator import generate_obligations
+from aetherproof.obligations.odg import ODG, EdgeType
+from aetherproof.proof.pdg import PDG, PDGNode, NodeType
+from aetherproof.proof.invalidation import invalidate
+from aetherproof.proof.engine import ProofEngine
+from aetherproof.remediation.diagnosis import diagnose
+from aetherproof.remediation.guardrails import check_guardrails, ViolationType, Patch
+from aetherproof.remediation.cycle import RemediationCycle
+from aetherproof.protocol.messages import Message, MessageType, Envelope
+from aetherproof.review.roles import Role, Authority, AUTHORITY_MATRIX
+
+__all__ = [
+    "__version__",
+    # Models
+    "CSRecord",
+    "Obligation",
+    "Counterexample",
+    "Verdict",
+    "ObligationType",
+    "CounterexampleType",
+    "Layer",
+    # CSR
+    "CSRRecord",
+    "SemanticRelation",
+    "RelationType",
+    # Obligations
+    "generate_obligations",
+    "ODG",
+    "EdgeType",
+    # Proof
+    "PDG",
+    "PDGNode",
+    "NodeType",
+    "invalidate",
+    "ProofEngine",
+    # Remediation
+    "diagnose",
+    "check_guardrails",
+    "ViolationType",
+    "Patch",
+    "RemediationCycle",
+    # Protocol
+    "Message",
+    "MessageType",
+    "Envelope",
+    # Review
+    "Role",
+    "Authority",
+    "AUTHORITY_MATRIX",
+]

aetherproof/__version__.py

@@ -0,0 +1 @@
+__version__ = "2.0.0"

aetherproof/cli.py

@@ -0,0 +1,83 @@
+"""Command-line interface for AetherProof v2.0.0."""
+
+import argparse
+import sys
+
+from aetherproof.__version__ import __version__
+from aetherproof.models import CSRecord, Layer, Verdict
+from aetherproof.csr.relations import SemanticRelation, RelationType
+from aetherproof.obligations.generator import generate_obligations
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="aetherproof",
+        description="AetherProof v2.0.0 — Reference Implementation",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # csr command
+    csr = sub.add_parser("csr", help="CSR record operations")
+    csr.add_argument("--layer", choices=["L1", "L2", "L3"], required=True)
+    csr.add_argument("--language", required=True)
+    csr.add_argument("--content", required=True)
+    csr.add_argument("--role", required=True)
+
+    # obligation command
+    obl = sub.add_parser("obligation", help="Obligation operations")
+    obl.add_argument("--csr-id", required=True)
+    obl.add_argument("--property", required=True)
+
+    # relation command
+    rel = sub.add_parser("relation", help="Semantic relation operations")
+    rel.add_argument("--source", required=True)
+    rel.add_argument("--target", required=True)
+    rel.add_argument(
+        "--type",
+        choices=[r.value for r in RelationType],
+        required=True,
+    )
+    rel.add_argument("--loss-description")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "csr":
+        layer = Layer(args.layer)
+        record = CSRecord.create(
+            layer=layer,
+            language=args.language,
+            content=args.content,
+            semantic_role=args.role,
+        )
+        print(f"CSR ID:        {record.csr_id}")
+        print(f"Artifact Hash: {record.artifact_hash}")
+        print(f"Semantic ID:   {record.semantic_id}")
+        print(f"Layer:         {record.layer.value}")
+        print(f"Language:      {record.language}")
+
+    elif args.command == "obligation":
+        # In a real CLI, this would fetch the CSR record
+        print(f"Obligation for CSR {args.csr_id}: {args.property}")
+
+    elif args.command == "relation":
+        try:
+            relation = SemanticRelation(
+                source=args.source,
+                target=args.target,
+                relation_type=RelationType(args.type),
+                loss_description=args.loss_description,
+            )
+            print(f"Relation created: {relation.source} "
+                  f"-> {relation.target} ({relation.relation_type.value})")
+        except ValueError as e:
+            print(f"Error: {e}")
+            return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

aetherproof/csr/__init__.py

@@ -0,0 +1,6 @@
+"""Canonical Specification Representation (CSR)."""
+
+from aetherproof.csr.record import CSRRecord
+from aetherproof.csr.relations import SemanticRelation, RelationType
+
+__all__ = ["CSRRecord", "SemanticRelation", "RelationType"]

aetherproof/csr/record.py

@@ -0,0 +1,12 @@
+"""
+CSR Record — Definition 1 implementation.
+
+See manuscript Section 3.2.
+"""
+
+from aetherproof.models import CSRecord
+
+# Re-export for convenience
+CSRRecord = CSRecord
+
+__all__ = ["CSRRecord"]

aetherproof/csr/relations.py

@@ -0,0 +1,46 @@
+"""
+Semantic Relations — Definition 2 implementation.
+
+Seven typed relations: refines, instantiates, approximates, implies,
+contradicts, depends_on, supersedes.
+
+See manuscript Section 3.3.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+
+class RelationType(str, Enum):
+    """Seven semantic relations (Section 3.3)."""
+    REFINES = "refines"
+    INSTANTIATES = "instantiates"
+    APPROXIMATES = "approximates"
+    IMPLIES = "implies"
+    CONTRADICTS = "contradicts"
+    DEPENDS_ON = "depends_on"
+    SUPERSEDES = "supersedes"
+
+
+@dataclass(frozen=True)
+class SemanticRelation:
+    """A semantic relation between two CSR records."""
+    source: str  # csr_id
+    target: str  # csr_id
+    relation_type: RelationType
+    loss_description: Optional[str] = None  # required for approximates
+    justification: str = ""
+
+    def __post_init__(self):
+        if self.relation_type == RelationType.APPROXIMATES:
+            if not self.loss_description:
+                raise ValueError(
+                    "approximates relation requires a loss_description "
+                    "(Section 3.3.1)"
+                )
+
+
+__all__ = ["SemanticRelation", "RelationType"]

aetherproof/models.py

@@ -0,0 +1,172 @@
+"""
+Core data models for AetherProof v2.0.0.
+
+Implements Definitions 1–6 from the manuscript.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+
+# ─── Enums ───
+
+class Verdict(str, Enum):
+    """Verification verdict (Section 4.6)."""
+    PROVEN = "proven"
+    REFUTED = "refuted"
+    UNKNOWN = "unknown"
+
+
+class ObligationType(str, Enum):
+    """Obligation types (Section 4.2)."""
+    INVARIANCE = "invariance"
+    PRE_POST = "pre_post"
+    SATISFIABILITY = "satisfiability"
+    CONSISTENCY = "consistency"
+
+
+class CounterexampleType(str, Enum):
+    """Counterexample types (Section 6.1)."""
+    CODE_DEFECT = "code_defect"
+    SPECIFICATION_ERROR = "specification_error"
+    ASSUMPTION_VIOLATION = "assumption_violation"
+    MODEL_ERROR = "model_error"
+    FLAKY_REFUTATION = "flaky_refutation"
+    UNKNOWN = "unknown"
+
+
+class Layer(str, Enum):
+    """Functional layers (Section 3.1)."""
+    L1 = "L1"  # System-level properties (TLA+)
+    L2 = "L2"  # Functional contracts (Why3/Lean)
+    L3 = "L3"  # Logical constraints (SMT-LIB/Z3)
+
+
+# ─── Core Models ───
+
+@dataclass(frozen=True)
+class CSRecord:
+    """
+    Canonical Specification Representation (Definition 1).
+
+    Three identities:
+    - Record identity (csr_id)
+    - Artifact identity (artifact_hash)
+    - Semantic identity (semantic_id)
+    """
+    csr_id: str
+    artifact_hash: str
+    semantic_id: str
+    layer: Layer
+    language: str
+    content: str
+    semantic_role: str
+    requirements_refs: tuple[str, ...] = field(default_factory=tuple)
+    assumptions: tuple[str, ...] = field(default_factory=tuple)
+    relations: tuple[str, ...] = field(default_factory=tuple)
+    version: str = "1.0.0"
+    provenance: str = ""
+
+    @classmethod
+    def create(
+        cls,
+        layer: Layer,
+        language: str,
+        content: str,
+        semantic_role: str,
+        requirements_refs: tuple[str, ...] = (),
+        assumptions: tuple[str, ...] = (),
+    ) -> "CSRecord":
+        """Create a new CSR record with computed identities."""
+        artifact_hash = hashlib.sha256(content.encode()).hexdigest()[:16]
+        semantic_id = hashlib.sha256(
+            f"{semantic_role}:{content}".encode()
+        ).hexdigest()[:16]
+        csr_id = f"csr-{layer.value}-{artifact_hash[:8]}"
+
+        return cls(
+            csr_id=csr_id,
+            artifact_hash=artifact_hash,
+            semantic_id=semantic_id,
+            layer=layer,
+            language=language,
+            content=content,
+            semantic_role=semantic_role,
+            requirements_refs=requirements_refs,
+            assumptions=assumptions,
+        )
+
+
+@dataclass(frozen=True)
+class Obligation:
+    """
+    Proof obligation (Definition 4).
+
+    O = (id, property, assumptions, source_csr, discharged_by, verdict)
+    """
+    id: str
+    property: str
+    assumptions: tuple[str, ...]
+    source_csr: str
+    discharged_by: Optional[str] = None
+    verdict: Verdict = Verdict.UNKNOWN
+
+    @classmethod
+    def create(
+        cls,
+        property: str,
+        assumptions: tuple[str, ...],
+        source_csr: str,
+    ) -> "Obligation":
+        """Create a new obligation."""
+        oid = hashlib.sha256(
+            f"{property}:{source_csr}".encode()
+        ).hexdigest()[:16]
+        return cls(
+            id=f"O-{oid}",
+            property=property,
+            assumptions=assumptions,
+            source_csr=source_csr,
+        )
+
+
+@dataclass(frozen=True)
+class Counterexample:
+    """
+    Counterexample (Definition 6).
+
+    C = (id, obligation, witness, refutation_evidence, type, provenance)
+    """
+    id: str
+    obligation: str
+    witness: str
+    refutation_evidence: str
+    type: CounterexampleType
+    provenance: str = ""
+
+    @classmethod
+    def create(
+        cls,
+        obligation: str,
+        witness: str,
+        refutation_evidence: str,
+        type: CounterexampleType = CounterexampleType.UNKNOWN,
+        provenance: str = "",
+    ) -> "Counterexample":
+        """Create a new counterexample."""
+        cid = hashlib.sha256(
+            f"{obligation}:{witness}".encode()
+        ).hexdigest()[:16]
+        return cls(
+            id=f"C-{cid}",
+            obligation=obligation,
+            witness=witness,
+            refutation_evidence=refutation_evidence,
+            type=type,
+            provenance=provenance,
+        )

aetherproof/obligations/__init__.py

@@ -0,0 +1,6 @@
+"""Proof obligations and Obligation Dependency Graph (ODG)."""
+
+from aetherproof.obligations.generator import generate_obligations
+from aetherproof.obligations.odg import ODG
+
+__all__ = ["generate_obligations", "ODG"]

aetherproof/obligations/generator.py

@@ -0,0 +1,68 @@
+"""
+Obligation Generator — Section 4.2 implementation.
+
+Generates proof obligations from CSR records according to their
+semantic role.
+"""
+
+from __future__ import annotations
+
+from aetherproof.models import (
+    CSRecord,
+    Obligation,
+    ObligationType,
+    Layer,
+)
+
+
+def generate_obligations(record: CSRecord) -> list[Obligation]:
+    """
+    Generate obligations from a CSR record.
+
+    Parameters
+    ----------
+    record : CSRecord
+        The CSR record.
+
+    Returns
+    -------
+    list[Obligation]
+        Generated obligations.
+    """
+    if record.semantic_role == "invariant" and record.layer == Layer.L1:
+        return [
+            Obligation.create(
+                property=f"Invariance({record.content})",
+                assumptions=record.assumptions,
+                source_csr=record.csr_id,
+            )
+        ]
+    elif record.semantic_role == "contract" and record.layer == Layer.L2:
+        return [
+            Obligation.create(
+                property=f"PrePost({record.content})",
+                assumptions=record.assumptions,
+                source_csr=record.csr_id,
+            )
+        ]
+    elif record.semantic_role == "constraint" and record.layer == Layer.L3:
+        return [
+            Obligation.create(
+                property=f"Satisfiability({record.content})",
+                assumptions=record.assumptions,
+                source_csr=record.csr_id,
+            )
+        ]
+    elif record.semantic_role == "translation":
+        return [
+            Obligation.create(
+                property=f"Consistency({record.content})",
+                assumptions=record.assumptions,
+                source_csr=record.csr_id,
+            )
+        ]
+    else:
+        return []
+
+
+__all__ = ["generate_obligations"]

aetherproof/obligations/odg.py

@@ -0,0 +1,115 @@
+"""
+Obligation Dependency Graph (ODG) — Section 4.3 implementation.
+
+The ODG is a directed acyclic graph over obligations.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+from aetherproof.models import Obligation, Verdict
+
+
+class EdgeType(str, Enum):
+    """ODG edge types (Section 4.3)."""
+    REQUIRES = "requires"
+    REFINES = "refines"
+    ASSUMES = "assumes"
+    CONTRADICTS = "contradicts"
+
+
+@dataclass
+class ODG:
+    """Obligation Dependency Graph."""
+    obligations: dict[str, Obligation] = field(default_factory=dict)
+    edges: list[tuple[str, str, EdgeType]] = field(default_factory=list)
+
+    def add_obligation(self, obligation: Obligation) -> None:
+        """Add an obligation to the graph."""
+        self.obligations[obligation.id] = obligation
+
+    def add_edge(
+        self,
+        source_id: str,
+        target_id: str,
+        edge_type: EdgeType,
+    ) -> None:
+        """Add an edge between two obligations."""
+        if source_id not in self.obligations:
+            raise ValueError(f"Source obligation {source_id} not found")
+        if target_id not in self.obligations:
+            raise ValueError(f"Target obligation {target_id} not found")
+
+        # Check for cycles in dependency-bearing edges
+        if edge_type in (EdgeType.REQUIRES, EdgeType.REFINES, EdgeType.ASSUMES):
+            if self._would_create_cycle(source_id, target_id):
+                raise ValueError(
+                    f"Adding edge ({source_id} -> {target_id}) "
+                    f"would create a cycle (Proposition P3)"
+                )
+
+        self.edges.append((source_id, target_id, edge_type))
+
+    def _would_create_cycle(self, source_id: str, target_id: str) -> bool:
+        """Check if adding an edge would create a cycle."""
+        # Simple DFS from target_id to see if we can reach source_id
+        visited: set[str] = set()
+        stack = [target_id]
+
+        while stack:
+            current = stack.pop()
+            if current == source_id:
+                return True
+            if current in visited:
+                continue
+            visited.add(current)
+
+            for s, t, e in self.edges:
+                if s == current and e in (
+                    EdgeType.REQUIRES, EdgeType.REFINES, EdgeType.ASSUMES
+                ):
+                    stack.append(t)
+
+        return False
+
+    def invalidate(self, obligation_id: str) -> list[str]:
+        """
+        Invalidate an obligation and all dependents.
+
+        Returns list of invalidated obligation IDs.
+
+        The invalidation propagates FORWARD: if O1 requires O2 (O1 depends on O2),
+        then invalidating O2 invalidates O1. The edge direction is (source, target),
+        meaning "source depends on target". So if we invalidate `obligation_id`,
+        we need to find all `source` that point to `obligation_id` as their target.
+        """
+        if obligation_id not in self.obligations:
+            raise ValueError(f"Obligation {obligation_id} not found")
+
+        invalidated = []
+        to_invalidate = {obligation_id}
+
+        while to_invalidate:
+            current = to_invalidate.pop()
+            if current in invalidated:
+                continue
+
+            invalidated.append(current)
+
+            # Find dependents: obligations that require/refine/assume current
+            # Edge direction is (source, target), where source depends on target.
+            # So if target == current, then source is a dependent.
+            for s, t, e in self.edges:
+                if t == current and e in (
+                    EdgeType.REQUIRES, EdgeType.REFINES, EdgeType.ASSUMES
+                ):
+                    if s not in invalidated:
+                        to_invalidate.add(s)
+
+        return invalidated
+
+
+__all__ = ["ODG", "EdgeType"]

aetherproof/proof/__init__.py

@@ -0,0 +1,7 @@
+"""Proof Dependency Graph (PDG) and differential proving."""
+
+from aetherproof.proof.pdg import PDG, NodeType
+from aetherproof.proof.invalidation import invalidate
+from aetherproof.proof.engine import ProofEngine
+
+__all__ = ["PDG", "NodeType", "invalidate", "ProofEngine"]

aetherproof/proof/engine.py

@@ -0,0 +1,77 @@
+"""
+Differential Proof Engine — Section 5 implementation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from aetherproof.models import Obligation, Verdict
+from aetherproof.proof.pdg import PDG
+from aetherproof.proof.invalidation import invalidate
+
+
+@dataclass
+class ProofEngine:
+    """
+    Incremental differential proof engine.
+
+    Implements cost-aware tiered proving (Section 5.6).
+    """
+    pdg: PDG
+    proof_budget: dict = field(default_factory=lambda: {
+        "time": 60.0,
+        "cost": 100.0,
+        "human_attention": 5.0,
+    })
+
+    def discharge(
+        self,
+        obligation: Obligation,
+        evidence: str,
+    ) -> Obligation:
+        """Discharge an obligation with evidence."""
+        return Obligation(
+            id=obligation.id,
+            property=obligation.property,
+            assumptions=obligation.assumptions,
+            source_csr=obligation.source_csr,
+            discharged_by=evidence,
+            verdict=Verdict.PROVEN,
+        )
+
+    def refute(
+        self,
+        obligation: Obligation,
+        counterexample: str,
+    ) -> Obligation:
+        """Refute an obligation with a counterexample."""
+        return Obligation(
+            id=obligation.id,
+            property=obligation.property,
+            assumptions=obligation.assumptions,
+            source_csr=obligation.source_csr,
+            discharged_by=counterexample,
+            verdict=Verdict.REFUTED,
+        )
+
+    def reuse_conditions_met(
+        self,
+        obligation_id: str,
+        new_changeset: str,
+    ) -> bool:
+        """
+        Check if an invalidated obligation can be reused.
+
+        Implements the five reuse conditions (Section 5.4).
+        """
+        # In a real implementation, this would check:
+        # 1. Assumption preservation
+        # 2. Evidence compatibility
+        # 3. Property stability
+        # 4. Semantic relation preservation
+        # 5. Artifact stability (proposed)
+        return False  # Conservative: always re-discharge
+
+
+__all__ = ["ProofEngine"]