aethergovern 2.0.0__py3-none-any.whl

aethergovern/cli.py

@@ -0,0 +1,142 @@
+"""
+AetherGovern — Command-line interface (v2.0.0).
+
+Usage:
+    python -m aethergovern.cli info
+    python -m aethergovern.cli verify
+"""
+
+from __future__ import annotations
+
+import sys
+
+from aethergovern.__version__ import (
+    __version__,
+    __author__,
+    __email__,
+    __doi__,
+    __license__,
+    __paper_version__,
+    __record_id__,
+)
+
+
+def cmd_info(args) -> int:
+    """Print version, DOI, and record information."""
+    print("=" * 60)
+    print(f"AetherGovern v{__version__}")
+    print("=" * 60)
+    print(f"Author:          {__author__}")
+    print(f"Email:           {__email__}")
+    print(f"License:         {__license__}")
+    print(f"Paper version:   {__paper_version__}")
+    print(f"Record ID:       {__record_id__}")
+    print(f"DOI:             {__doi__}")
+    print(f"DOI URL:         https://doi.org/{__doi__}")
+    print()
+    print("AetherGovern is the fifth functional dimension of the Aether family:")
+    print("  AetherGit    (storage)          — 10.5281/zenodo.23966896")
+    print("  AetherFlow   (integration)      — 10.5281/zenodo.23979129")
+    print("  AetherProof  (verification)     — 10.5281/zenodo.24013124")
+    print("  AetherMesh   (decentralization) — 10.5281/zenodo.24053492")
+    print("  AetherGovern (governance)       — 10.5281/zenodo.24054524")
+    print()
+    print("Status: Architectural Hypothesis Under Investigation (v0.1.0).")
+    print("        No real-world deployment. Theorems P1–P2 are proof sketches.")
+    print("=" * 60)
+    return 0
+
+
+def cmd_verify(args) -> int:
+    """Run a quick self-check."""
+    print("=" * 60)
+    print(f"AetherGovern v{__version__} — self-check")
+    print("=" * 60)
+
+    ok = True
+
+    # 1. Ed25519 signature
+    print("[1/3] Ed25519 signature verification")
+    from aethergovern.authorization.certificates import generate_keypair
+    priv, pub = generate_keypair()
+    msg = b"test message"
+    sig = priv.sign(msg)
+    try:
+        pub.verify(sig, msg)
+        print("      ✅ Valid signature verified")
+    except Exception:
+        print("      ❌ Signature verification failed")
+        ok = False
+
+    # 2. Frontier join
+    print("[2/3] Revocation frontier join")
+    from aethergovern.models import RevocationFrontier
+    from aethergovern.revocation.frontier import join_frontiers
+    f1 = RevocationFrontier("f1", frozenset(["r1", "r2"]), "2026-11-09T00:00:00Z")
+    f2 = RevocationFrontier("f2", frozenset(["r2", "r3"]), "2026-11-09T00:00:00Z")
+    joined = join_frontiers(f1, f2)
+    if joined.revocations == frozenset(["r1", "r2", "r3"]):
+        print(f"      ✅ Frontier join: {sorted(joined.revocations)}")
+    else:
+        print(f"      ❌ Frontier join failed: {joined.revocations}")
+        ok = False
+
+    # 3. Policy evaluation
+    print("[3/3] Policy evaluation")
+    from aethergovern.models import (
+        Action, ActionKind, Policy, PolicyStatus, PolicyVerdict, Rule
+    )
+    from aethergovern.policy.enforcement import apply_policy, policy_hash
+    policy = Policy(
+        policy_id="p1", version=1,
+        rules=[Rule("commit", "branch/main", PolicyVerdict.ALLOW)],
+        approval_chain=["agent-1"],
+        status=PolicyStatus.ENFORCED,
+        created_at="2026-11-01T00:00:00Z",
+        effective_from="2026-11-01T00:00:00Z",
+    )
+    action = Action(
+        action_id="a"*64, kind=ActionKind.COMMIT, actor="agent-1",
+        resource="branch/main", payload={},
+        timestamp="2026-11-09T00:00:00Z",
+        frontier_ref="f"*64, policy_ref=policy_hash(policy),
+        authority_chain=["c"*64], signature=b"\x00"*64,
+    )
+    verdict = apply_policy(action, policy)
+    if verdict == PolicyVerdict.ALLOW:
+        print(f"      ✅ Policy verdict: {verdict.value}")
+    else:
+        print(f"      ❌ Policy verdict: {verdict.value}")
+        ok = False
+
+    print("=" * 60)
+    if ok:
+        print("      ✅ All checks passed")
+        return 0
+    else:
+        print("      ❌ Some checks failed")
+        return 1
+
+
+def main(argv=None) -> int:
+    """Main entry point."""
+    import argparse
+    parser = argparse.ArgumentParser(
+        prog="aethergovern",
+        description=f"AetherGovern v{__version__} — falsification-first governance",
+    )
+    parser.add_argument("--version", action="version", version=f"aethergovern {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_info = sub.add_parser("info", help="Print version and record info")
+    p_info.set_defaults(func=cmd_info)
+
+    p_verify = sub.add_parser("verify", help="Run a self-check")
+    p_verify.set_defaults(func=cmd_verify)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

aethergovern/dispute/__init__.py

@@ -0,0 +1,11 @@
+"""AetherGovern — Dispute resolution module (Layer 5)."""
+
+from aethergovern.dispute.resolution import (
+    escalate,
+    resolve_by_rule,
+)
+
+__all__ = [
+    "escalate",
+    "resolve_by_rule",
+]

aethergovern/dispute/resolution.py

@@ -0,0 +1,132 @@
+"""
+AetherGovern — Dispute resolution (Layer 5, v2.0.0).
+
+Implements:
+    - escalate: escalate an unresolved dispute to human review
+    - resolve_by_rule: resolve a dispute by a deterministic rule
+
+Reference:
+    Baladi, S. (2026). AetherGovern v2.0.0,
+    docs/specification/02_operations.md, Operation 6 (escalate).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Dict
+
+from aethergovern.models import (
+    Dispute,
+    DisputeResolution,
+)
+
+
+# =============================================================================
+# Time helpers
+# =============================================================================
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+# =============================================================================
+# escalate
+# =============================================================================
+
+def escalate(
+    dispute: Dispute,
+    reason: str,
+    escalation_target: str,
+) -> Dispute:
+    """
+    Escalate an unresolved dispute to human review.
+
+    Preconditions:
+        - dispute.resolution == PENDING or ESCALATED
+        - escalation_target is a non-empty string
+
+    Postconditions:
+        - result.resolution == ESCALATED
+        - result.escalation_record contains reason and escalation_target
+
+    Invariants:
+        I9.2 — Escalation completeness: escalation_record must be non-empty.
+        I9.3 — No silent resolution: the dispute is explicitly escalated.
+    """
+    if dispute.resolution == DisputeResolution.RESOLVED_BY_RULE:
+        raise ValueError(
+            f"dispute {dispute.dispute_id} is already resolved by rule "
+            f"(rule={dispute.precedence_rule})"
+        )
+    if not escalation_target:
+        raise ValueError("empty escalation target")
+    if not reason:
+        raise ValueError("empty escalation reason")
+
+    escalation_record: Dict = {
+        "reason": reason,
+        "escalation_target": escalation_target,
+        "escalated_at": _now_iso(),
+    }
+
+    return Dispute(
+        dispute_id=dispute.dispute_id,
+        claim_a=dispute.claim_a,
+        claim_b=dispute.claim_b,
+        precedence_rule=dispute.precedence_rule,
+        resolution=DisputeResolution.ESCALATED,
+        escalation_record=escalation_record,
+        created_at=dispute.created_at,
+    )
+
+
+# =============================================================================
+# resolve_by_rule
+# =============================================================================
+
+def resolve_by_rule(dispute: Dispute, rule: str) -> Dispute:
+    """
+    Resolve a dispute by a deterministic precedence rule.
+
+    Supported rules (for v2.0.0):
+        - "more_restrictive": the claim with the smaller scope wins.
+        - "later_expiry": the claim with the later expiry wins
+          (approximated by chain length for v2.0.0).
+
+    Preconditions:
+        - dispute.resolution == PENDING
+        - rule is a non-empty string
+
+    Postconditions:
+        - result.resolution == RESOLVED_BY_RULE
+        - result.precedence_rule == rule
+
+    Invariants:
+        I9.1 — Determinism: the same input always gives the same resolution.
+        I9.3 — No silent resolution: the rule is explicitly recorded.
+    """
+    if dispute.resolution == DisputeResolution.RESOLVED_BY_RULE:
+        raise ValueError(
+            f"dispute {dispute.dispute_id} is already resolved "
+            f"(rule={dispute.precedence_rule})"
+        )
+    if dispute.resolution == DisputeResolution.ESCALATED:
+        raise ValueError(
+            f"dispute {dispute.dispute_id} has been escalated; "
+            f"cannot resolve by rule"
+        )
+    if not rule:
+        raise ValueError("empty rule")
+
+    # Deterministic resolution: the rule determines the winner.
+    # For v2.0.0, we only record the rule; the winner is determined by the
+    # caller (or a future implementation of the rule).
+    return Dispute(
+        dispute_id=dispute.dispute_id,
+        claim_a=dispute.claim_a,
+        claim_b=dispute.claim_b,
+        precedence_rule=rule,
+        resolution=DisputeResolution.RESOLVED_BY_RULE,
+        escalation_record=dispute.escalation_record,
+        created_at=dispute.created_at,
+    )

aethergovern/models.py

@@ -0,0 +1,334 @@
+"""
+AetherGovern — Core data models (v2.0.0).
+
+This module defines the ten entities of AetherGovern v2.0.0:
+
+    1. Agent                    — actor identity
+    2. Action                   — operation (commit, merge, delete, deploy, rotate_key)
+    3. Resource                 — target (branch, path, key)
+    4. DelegationCertificate    — signed grant of scope
+    5. RevocationRecord         — signed withdrawal of a certificate
+    6. Policy                   — rule that governs authorization
+    7. RevocationFrontier       — set of revocation records an actor has seen
+    8. AuthorityChain           — sequence of certificates from root to leaf
+    9. Dispute                  — conflict between two authority claims
+   10. AccountabilityRecord     — after-the-fact trace of an admitted action
+
+Reference:
+    Baladi, S. (2026). AetherGovern: A Falsification-First Investigation
+    of Governance in the Aether Family. Zenodo.
+    https://doi.org/10.5281/zenodo.24054524
+
+    v2.0.0 Specification, docs/specification/01_entities.md.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, FrozenSet, List, Optional, Tuple
+
+
+# =============================================================================
+# Enums
+# =============================================================================
+
+class AgentStatus(str, Enum):
+    """Status of an agent."""
+    ACTIVE = "active"
+    SUSPENDED = "suspended"
+    REVOKED = "revoked"
+
+
+class ActionKind(str, Enum):
+    """Kind of action an agent may perform."""
+    COMMIT = "commit"
+    MERGE = "merge"
+    DELETE = "delete"
+    DEPLOY = "deploy"
+    ROTATE_KEY = "rotate_key"
+
+
+class ResourceKind(str, Enum):
+    """Kind of resource an action targets."""
+    BRANCH = "branch"
+    PATH = "path"
+    KEY = "key"
+
+
+class PolicyStatus(str, Enum):
+    """Status of a policy."""
+    PROPOSED = "proposed"
+    APPROVED = "approved"
+    ENFORCED = "enforced"
+    REVOKED = "revoked"
+
+
+class DisputeResolution(str, Enum):
+    """Resolution status of a dispute."""
+    PENDING = "pending"
+    RESOLVED_BY_RULE = "resolved_by_rule"
+    ESCALATED = "escalated"
+
+
+class PolicyVerdict(str, Enum):
+    """Verdict of a policy evaluation."""
+    ALLOW = "allow"
+    DENY = "deny"
+    QUARANTINE = "quarantine"
+
+
+# =============================================================================
+# Type aliases
+# =============================================================================
+
+Scope = FrozenSet[Tuple[str, str]]
+"""A scope is a frozen set of (action_kind, resource_id) pairs."""
+
+
+# =============================================================================
+# Entity 1 — Agent
+# =============================================================================
+
+@dataclass(frozen=True)
+class Agent:
+    """
+    An autonomous software actor.
+
+    Invariants:
+        I1.1 — Key uniqueness (enforced by the registry, not the entity)
+        I1.2 — Status monotonicity (enforced by the state machine)
+        I1.3 — Registration completeness (enforced by the admission layer)
+    """
+    agent_id: str
+    public_key: bytes
+    key_id: str
+    role: Optional[str]
+    registered_at: str
+    status: AgentStatus = AgentStatus.ACTIVE
+
+
+# =============================================================================
+# Entity 2 — Action
+# =============================================================================
+
+@dataclass(frozen=True)
+class Action:
+    """
+    An operation by an agent on a resource.
+
+    Invariants:
+        I2.1 — Causal citation (enforced by the admission layer)
+        I2.2 — Content addressing (enforced by the constructor)
+        I2.3 — Signature covers content (enforced by the signature layer)
+        I2.4 — Chain completeness (enforced by the admission layer)
+    """
+    action_id: str
+    kind: ActionKind
+    actor: str
+    resource: str
+    payload: Dict
+    timestamp: str
+    frontier_ref: str
+    policy_ref: str
+    authority_chain: List[str]
+    signature: bytes = b""
+
+
+# =============================================================================
+# Entity 3 — Resource
+# =============================================================================
+
+@dataclass(frozen=True)
+class Resource:
+    """
+    The target of an action.
+
+    Invariants:
+        I3.1 — Identifier stability (enforced by frozen dataclass)
+        I3.2 — Kind immutability (enforced by frozen dataclass)
+    """
+    resource_id: str
+    kind: ResourceKind
+    owner: str
+    metadata: Dict = field(default_factory=dict)
+
+
+# =============================================================================
+# Entity 4 — DelegationCertificate
+# =============================================================================
+
+@dataclass(frozen=True)
+class DelegationCertificate:
+    """
+    A signed grant of scope from an issuer to a subject.
+
+    Invariants:
+        I4.1 — Attenuation (enforced by the delegate operation)
+        I4.2 — Root recognition (enforced by the check operation)
+        I4.3 — Expiry (enforced by the check operation)
+        I4.4 — Signature covers content (enforced by the signature layer)
+        I4.5 — No cycle (enforced by the parent_ref chain)
+    """
+    certificate_id: str
+    issuer: str
+    subject: str
+    scope: Scope
+    constraints: Dict
+    expiry: str
+    parent_ref: Optional[str]
+    signature: bytes = b""
+
+
+# =============================================================================
+# Entity 5 — RevocationRecord
+# =============================================================================
+
+@dataclass(frozen=True)
+class RevocationRecord:
+    """
+    A signed withdrawal of a certificate.
+
+    Invariants:
+        I5.1 — Monotonicity (enforced by the frontier)
+        I5.2 — Signature covers content (enforced by the signature layer)
+        I5.3 — Issuer authority (enforced by the revoke operation)
+    """
+    revocation_id: str
+    certificate_ref: str
+    issuer: str
+    reason: str
+    timestamp: str
+    signature: bytes = b""
+
+
+# =============================================================================
+# Entity 6 — Policy
+# =============================================================================
+
+@dataclass(frozen=True)
+class Rule:
+    """A single policy rule."""
+    action_kind: str
+    resource_pattern: str
+    verdict: PolicyVerdict
+
+
+@dataclass(frozen=True)
+class Policy:
+    """
+    A rule that governs authorization.
+
+    Invariants:
+        I6.1 — Version monotonicity (enforced by the policy registry)
+        I6.2 — Approval completeness (enforced by the apply_policy operation)
+        I6.3 — Effective date (enforced by the apply_policy operation)
+        I6.4 — Supersession chain (enforced by the policy registry)
+    """
+    policy_id: str
+    version: int
+    rules: List[Rule]
+    approval_chain: List[str]
+    status: PolicyStatus
+    created_at: str
+    effective_from: str
+    supersedes: Optional[str] = None
+
+
+# =============================================================================
+# Entity 7 — RevocationFrontier
+# =============================================================================
+
+@dataclass(frozen=True)
+class RevocationFrontier:
+    """
+    The set of revocation records an actor has seen.
+
+    Invariants:
+        I7.1 — Grow-only (enforced by the frontier operations)
+        I7.2 — Join is union (enforced by the join method)
+        I7.3 — Content addressing (enforced by the constructor)
+    """
+    frontier_id: str
+    revocations: FrozenSet[str]
+    created_at: str
+
+    def join(self, other: "RevocationFrontier") -> "RevocationFrontier":
+        """Join two frontiers: set union of revocations."""
+        return RevocationFrontier(
+            frontier_id=f"{self.frontier_id}+{other.frontier_id}",
+            revocations=self.revocations | other.revocations,
+            created_at=self.created_at,
+        )
+
+    def __le__(self, other: "RevocationFrontier") -> bool:
+        """Partial order: self ≤ other iff self.revocations ⊆ other.revocations."""
+        return self.revocations <= other.revocations
+
+
+# =============================================================================
+# Entity 8 — AuthorityChain
+# =============================================================================
+
+@dataclass(frozen=True)
+class AuthorityChain:
+    """
+    A sequence of delegation certificates from a root to a leaf agent.
+
+    Invariants:
+        I8.1 — Attenuation preserved (enforced by the check operation)
+        I8.2 — Root recognized (enforced by the check operation)
+        I8.3 — No cycle (enforced by the certificate chain)
+        I8.4 — Contiguity (enforced by the check operation)
+    """
+    chain_id: str
+    certificates: List[str]
+    leaf_agent: str
+    leaf_scope: Scope
+
+
+# =============================================================================
+# Entity 9 — Dispute
+# =============================================================================
+
+@dataclass(frozen=True)
+class Dispute:
+    """
+    A conflict between two authority claims.
+
+    Invariants:
+        I9.1 — Determinism (enforced by the escalate operation)
+        I9.2 — Escalation completeness (enforced by the escalate operation)
+        I9.3 — No silent resolution (enforced by the escalate operation)
+    """
+    dispute_id: str
+    claim_a: AuthorityChain
+    claim_b: AuthorityChain
+    precedence_rule: Optional[str]
+    resolution: DisputeResolution
+    escalation_record: Optional[Dict] = None
+    created_at: str = ""
+
+
+# =============================================================================
+# Entity 10 — AccountabilityRecord
+# =============================================================================
+
+@dataclass(frozen=True)
+class AccountabilityRecord:
+    """
+    The after-the-fact trace of an admitted action.
+
+    Invariants:
+        I10.1 — Immutability (enforced by frozen dataclass)
+        I10.2 — Hash-link integrity (enforced by the record chain)
+        I10.3 — Attribution completeness (enforced by the admission layer)
+        I10.4 — Signature covers content (enforced by the signature layer)
+    """
+    record_id: str
+    action_ref: str
+    authority_chain_ref: str
+    admitted_at: str
+    admitted_by: str
+    prev_record_hash: str
+    signature: bytes = b""

aethergovern/policy/__init__.py

@@ -0,0 +1,11 @@
+"""AetherGovern — Policy module (Layer 2)."""
+
+from aethergovern.policy.enforcement import (
+    policy_hash,
+    apply_policy,
+)
+
+__all__ = [
+    "policy_hash",
+    "apply_policy",
+]