aetherruntime-arch 2.0.0__py3-none-any.whl

aetherruntime/halt/order.py

@@ -0,0 +1,248 @@
+"""
+AetherRuntime v2.0.0 — Halt: Order (Layer 4)
+
+This module implements Operation 5 (`propose_halt`) from
+docs/specification/02_operations.md.
+
+The `propose_halt` operation creates a signed halt order for an agent.
+The halt becomes enforced when a quorum of authorized nodes approves it
+(see `quorum.py`).
+
+Key properties:
+    - The proposer must be authorized (via AetherGovern).
+    - The proposer's signature must verify (Ed25519).
+    - The halt window Δt_window > 0 (Proposition 2).
+
+Invariants enforced:
+    - I14: proposer_signature verifies
+    - I15: quorum_threshold in [0.5, 1.0]
+    - I16: enforced_at set iff quorum reached
+    - I17: Δt_window > 0 (Proposition 2)
+    - O5: propose_halt requires valid signature
+
+Errors:
+    - E15: AgentNotFound
+    - E16: UnauthorizedProposer
+    - E17: InvalidSignature
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Optional
+
+from ..models import (
+    Agent,
+    AgentStatus,
+    HaltOrder,
+    _now_iso,
+    _random_hex,
+)
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Errors
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+class AgentNotFound(Exception):
+    """E15: Agent does not exist."""
+    pass
+
+
+class UnauthorizedProposer(Exception):
+    """E16: Proposer is not authorized (via AetherGovern)."""
+    pass
+
+
+class InvalidSignature(Exception):
+    """E17: proposer_signature does not verify."""
+    pass
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Signature verification (stub; Ed25519 in production)
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+def _verify_signature(
+    public_key: bytes,
+    signature: bytes,
+    message: bytes,
+) -> bool:
+    """
+    Verify an Ed25519 signature.
+
+    In simulation, we use a deterministic hash-based stub. In production,
+    this would use the `cryptography` library's Ed25519 verifier.
+    """
+    if len(signature) != 64:
+        return False
+    if len(public_key) != 32:
+        return False
+    # Stub: signature must be 64 bytes and start with a non-zero byte
+    # In production: Ed25519PublicKey.from_public_bytes(public_key).verify(signature, message)
+    return signature[0] != 0
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Operation 5 — propose_halt
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+def propose_halt(
+    agent: Agent,
+    proposer: Agent,
+    proposer_signature: bytes,
+    reason: str,
+    quorum_threshold: float = 0.67,
+    is_proposer_authorized: bool = True,
+) -> HaltOrder:
+    """
+    Propose a halt order for a compromised agent (Operation 5).
+
+    Args:
+        agent: The agent to halt.
+        proposer: The agent proposing the halt. Must be authorized.
+        proposer_signature: Ed25519 signature from the proposer.
+        reason: Human-readable reason for the halt.
+        quorum_threshold: Required fraction of approvals (default 0.67 = 2/3).
+        is_proposer_authorized: In production, checked via AetherGovern.
+
+    Returns:
+        A new HaltOrder with `enforced_at = None`.
+
+    Raises:
+        AgentNotFound: If agent or proposer is None.
+        UnauthorizedProposer: If proposer is not authorized.
+        InvalidSignature: If proposer_signature does not verify.
+
+    Invariants:
+        I14: proposer_signature verifies.
+        I15: quorum_threshold in [0.5, 1.0].
+        I16: enforced_at is None (until quorum reached).
+        O5: propose_halt requires valid signature.
+
+    Example:
+        >>> order = propose_halt(agent, proposer, sig, "anomalous CPU")
+        >>> order.enforced_at
+        None
+    """
+    # ─── E15: Agent and proposer must exist ───
+    if agent is None:
+        raise AgentNotFound("agent must not be None")
+    if proposer is None:
+        raise AgentNotFound("proposer must not be None")
+
+    # ─── E16: Proposer must be authorized (via AetherGovern) ───
+    if not is_proposer_authorized:
+        raise UnauthorizedProposer(
+            f"Proposer {proposer.agent_id} is not authorized"
+        )
+
+    # ─── I15: quorum_threshold in [0.5, 1.0] ───
+    if not (0.5 <= quorum_threshold <= 1.0):
+        raise ValueError(
+            f"quorum_threshold must be in [0.5, 1.0], got {quorum_threshold}"
+        )
+
+    # ─── I14: Verify proposer signature ───
+    halt_id = _random_hex()
+    created_at = _now_iso()
+    message = _halt_message(halt_id, agent.agent_id, reason, created_at)
+    if not _verify_signature(proposer.public_key, proposer_signature, message):
+        raise InvalidSignature("proposer_signature does not verify")
+
+    # ─── Q1: Create HaltOrder with enforced_at = None ───
+    return HaltOrder(
+        halt_id=halt_id,
+        agent_id=agent.agent_id,
+        reason=reason,
+        proposer=proposer.agent_id,
+        proposer_signature=proposer_signature,
+        quorum_threshold=quorum_threshold,
+        created_at=created_at,
+        approvals=[],
+        enforced_at=None,  # I16: not enforced until quorum
+    )
+
+
+def _halt_message(
+    halt_id: str,
+    agent_id: str,
+    reason: str,
+    created_at: str,
+) -> bytes:
+    """Construct the message that the proposer signs."""
+    return hashlib.sha256(
+        f"{halt_id}|{agent_id}|{reason}|{created_at}".encode("utf-8")
+    ).digest()
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Halt order registry
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+class HaltOrderRegistry:
+    """An in-memory registry of halt orders."""
+
+    def __init__(self) -> None:
+        self._orders: dict[str, HaltOrder] = {}
+        self._by_agent: dict[str, list[HaltOrder]] = {}
+
+    def put(self, order: HaltOrder) -> None:
+        """Register a halt order."""
+        if order.halt_id in self._orders:
+            raise ValueError(f"halt_id {order.halt_id} already registered")
+        self._orders[order.halt_id] = order
+        self._by_agent.setdefault(order.agent_id, []).append(order)
+
+    def get(self, halt_id: str) -> Optional[HaltOrder]:
+        """Get a halt order by ID."""
+        return self._orders.get(halt_id)
+
+    def get_by_agent(self, agent_id: str) -> list[HaltOrder]:
+        """Get all halt orders for an agent."""
+        return list(self._by_agent.get(agent_id, []))
+
+    def enforced_for_agent(self, agent_id: str) -> list[HaltOrder]:
+        """Get all enforced halt orders for an agent."""
+        return [o for o in self.get_by_agent(agent_id) if o.is_enforced()]
+
+    def count(self) -> int:
+        """Count all halt orders."""
+        return len(self._orders)
+
+    def clear(self) -> None:
+        """Clear all halt orders."""
+        self._orders.clear()
+        self._by_agent.clear()
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Halt window computation (Proposition 2)
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+def compute_halt_window(order: HaltOrder) -> Optional[float]:
+    """
+    Compute the halt window Δt_window for an enforced halt order.
+
+    Δt_window = enforced_at - created_at (Proposition 2).
+
+    Returns:
+        The window in seconds, or None if not enforced.
+    """
+    return order.halt_window_seconds()
+
+
+def validate_halt_window(order: HaltOrder) -> bool:
+    """
+    Validate that Δt_window > 0 (I17, Proposition 2).
+
+    Returns:
+        True if enforced and window > 0, False otherwise.
+    """
+    window = compute_halt_window(order)
+    return window is not None and window > 0

aetherruntime/halt/quorum.py

@@ -0,0 +1,280 @@
+"""
+AetherRuntime v2.0.0 — Halt: Quorum (Layer 4)
+
+This module implements Operation 6 (`approve_halt`) from
+docs/specification/02_operations.md.
+
+The `approve_halt` operation registers an approval from an authorized node
+and, when the quorum threshold is reached, enforces the halt order.
+
+Key properties:
+    - Each approver can approve only once (I20).
+    - Enforced when approvals count / total ≥ quorum_threshold (I16).
+    - Δt_window > 0 (Proposition 2, I17).
+
+Invariants enforced:
+    - I16: enforced_at set iff quorum reached
+    - I17: Δt_window > 0
+    - I18: signature verifies
+    - I19: approval_id unique
+    - I20: approver cannot approve twice
+    - O6: approve_halt cannot be done twice by same approver
+
+Errors:
+    - E18: HaltNotFound
+    - E19: InvalidSignature
+    - Additional: AlreadyApproved, QuorumAlreadyReached
+"""
+
+from __future__ import annotations
+
+import hashlib
+from datetime import datetime, timezone
+from typing import Optional
+
+from ..models import (
+    Agent,
+    HaltApproval,
+    HaltOrder,
+    _now_iso,
+    _random_hex,
+)
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Errors
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+class HaltNotFound(Exception):
+    """E18: halt_id does not exist."""
+    pass
+
+
+class InvalidSignature(Exception):
+    """E19: approver_signature does not verify."""
+    pass
+
+
+class AlreadyApproved(Exception):
+    """The approver has already approved this halt (I20)."""
+    pass
+
+
+class QuorumAlreadyReached(Exception):
+    """Quorum was already reached; halt is enforced."""
+    pass
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Signature verification (stub)
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+def _verify_signature(
+    public_key: bytes,
+    signature: bytes,
+    message: bytes,
+) -> bool:
+    """Verify an Ed25519 signature (stub)."""
+    if len(signature) != 64:
+        return False
+    if len(public_key) != 32:
+        return False
+    return signature[0] != 0
+
+
+def _approval_message(halt_id: str, approver_id: str, timestamp: str) -> bytes:
+    """Construct the message that the approver signs."""
+    return hashlib.sha256(
+        f"{halt_id}|{approver_id}|{timestamp}".encode("utf-8")
+    ).digest()
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Operation 6 — approve_halt
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+def approve_halt(
+    halt_order: HaltOrder,
+    approver: Agent,
+    approver_signature: bytes,
+    total_authorized_nodes: int,
+    is_approver_authorized: bool = True,
+) -> HaltApproval:
+    """
+    Approve a halt order (Operation 6).
+
+    Args:
+        halt_order: The HaltOrder to approve.
+        approver: The agent approving. Must be authorized.
+        approver_signature: Ed25519 signature from the approver.
+        total_authorized_nodes: Total number of authorized nodes.
+        is_approver_authorized: In production, checked via AetherGovern.
+
+    Returns:
+        A new HaltApproval. If quorum is reached, halt_order.enforced_at
+        is updated and the halt is enforced.
+
+    Raises:
+        HaltNotFound: If halt_order is None.
+        InvalidSignature: If approver_signature does not verify.
+        AlreadyApproved: If approver has already approved.
+        QuorumAlreadyReached: If quorum was already reached.
+
+    Invariants:
+        I16: enforced_at set iff quorum reached.
+        I17: Δt_window > 0 (Proposition 2).
+        I18: signature verifies.
+        I19: approval_id unique.
+        I20: approver cannot approve twice.
+        O6: approve_halt cannot be done twice by same approver.
+
+    Example:
+        >>> approval = approve_halt(order, node1, sig, total=3)
+        >>> order.is_enforced()
+        False  # need 2/3 approvals
+        >>> approval2 = approve_halt(order, node2, sig2, total=3)
+        >>> order.is_enforced()
+        True   # 2/3 = quorum
+    """
+    # ─── E18: HaltOrder must exist ───
+    if halt_order is None:
+        raise HaltNotFound("halt_order must not be None")
+
+    # ─── Quorum already reached? ───
+    if halt_order.is_enforced():
+        raise QuorumAlreadyReached(
+            f"Quorum already reached for halt {halt_order.halt_id}"
+        )
+
+    # ─── E16: Approver must be authorized ───
+    if not is_approver_authorized:
+        raise InvalidSignature(
+            f"Approver {approver.agent_id} is not authorized"
+        )
+
+    # ─── I20: Approver cannot approve twice ───
+    for existing in halt_order.approvals:
+        if existing.approver == approver.agent_id:
+            raise AlreadyApproved(
+                f"Approver {approver.agent_id} already approved halt "
+                f"{halt_order.halt_id}"
+            )
+
+    # ─── I19: Generate unique approval_id ───
+    approval_id = _random_hex()
+    timestamp = _now_iso()
+
+    # ─── I18: Verify signature ───
+    message = _approval_message(halt_order.halt_id, approver.agent_id, timestamp)
+    if not _verify_signature(approver.public_key, approver_signature, message):
+        raise InvalidSignature("approver_signature does not verify")
+
+    # ─── Q1: Create HaltApproval ───
+    approval = HaltApproval(
+        approval_id=approval_id,
+        halt_id=halt_order.halt_id,
+        approver=approver.agent_id,
+        signature=approver_signature,
+        timestamp=timestamp,
+    )
+
+    # ─── Register approval ───
+    halt_order.approvals.append(approval)
+
+    # ─── I16: Check quorum ───
+    approvals_count = len(halt_order.approvals)
+    quorum_reached = (approvals_count / total_authorized_nodes) >= halt_order.quorum_threshold
+
+    if quorum_reached:
+        # ─── I17: Δt_window > 0 (Proposition 2) ───
+        created_dt = datetime.fromisoformat(
+            halt_order.created_at.replace("Z", "+00:00")
+        )
+        enforced_dt = datetime.now(timezone.utc)
+        if enforced_dt <= created_dt:
+            # Force at least 1 microsecond window
+            from datetime import timedelta
+            enforced_dt = created_dt + timedelta(microseconds=1)
+        halt_order.enforced_at = enforced_dt.isoformat()
+
+    return approval
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Batch approval
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+def approve_batch(
+    halt_order: HaltOrder,
+    approvals: list[tuple[Agent, bytes, bool]],
+    total_authorized_nodes: int,
+) -> list[HaltApproval]:
+    """
+    Approve a halt order with multiple nodes in sequence.
+
+    Args:
+        halt_order: The HaltOrder to approve.
+        approvals: List of (approver, signature, is_authorized) tuples.
+        total_authorized_nodes: Total number of authorized nodes.
+
+    Returns:
+        List of successfully registered HaltApprovals.
+    """
+    result: list[HaltApproval] = []
+    for approver, sig, is_auth in approvals:
+        try:
+            approval = approve_halt(
+                halt_order, approver, sig, total_authorized_nodes, is_auth
+            )
+            result.append(approval)
+        except (AlreadyApproved, QuorumAlreadyReached):
+            continue
+    return result
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Quorum tracker
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+class QuorumTracker:
+    """
+    Tracks quorum status for halt orders.
+
+    Provides query methods for approval counts, quorum percentage,
+    and enforcement status.
+    """
+
+    def __init__(self, total_authorized_nodes: int) -> None:
+        if total_authorized_nodes <= 0:
+            raise ValueError("total_authorized_nodes must be > 0")
+        self.total = total_authorized_nodes
+
+    def status(self, halt_order: HaltOrder) -> dict:
+        """Return quorum status for a halt order."""
+        n_approvals = len(halt_order.approvals)
+        percentage = n_approvals / self.total if self.total > 0 else 0.0
+        return {
+            "halt_id": halt_order.halt_id,
+            "n_approvals": n_approvals,
+            "total_authorized": self.total,
+            "percentage": percentage,
+            "threshold": halt_order.quorum_threshold,
+            "quorum_reached": percentage >= halt_order.quorum_threshold,
+            "enforced": halt_order.is_enforced(),
+        }
+
+    def is_enforced(self, halt_order: HaltOrder) -> bool:
+        """Check if a halt order is enforced."""
+        return halt_order.is_enforced()
+
+    def remaining_approvals(self, halt_order: HaltOrder) -> int:
+        """Count how many more approvals are needed."""
+        if halt_order.is_enforced():
+            return 0
+        needed = int(self.total * halt_order.quorum_threshold) + 1
+        return max(0, needed - len(halt_order.approvals))