awgit 0.1.0__py3-none-any.whl

awgit/identity.py

@@ -0,0 +1,80 @@
+"""Verified-identity → attribution resolution (standalone).
+
+The verified actor is the GitHub identity (the Aitherium GitHub OAuth-app login
+via ``gh``). This module makes it the AUTHORITATIVE attribution identity:
+
+  - ``attribution_id(login)`` → ``github:<login>`` — a deterministic namespace
+    so the GitHub identity can never collide with a platform ``user_id``;
+  - ``github_email()`` → the gh account's primary email (cached, best-effort).
+
+Standalone awgit records attribution only — who changed what, under a verified
+GitHub identity, with a deterministic handle per op. A downstream AitherOS
+reward program that consumes this attribution lives in the AitherOS monorepo's
+internal awgit, not in the public package.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import subprocess
+import time
+from pathlib import Path
+from typing import Dict, Optional
+
+from awgit.data_root import vcs_data_root
+
+logger = logging.getLogger(__name__)
+
+_TTL_SEC = 6 * 3600  # refresh the GitHub identity at most this often
+
+
+def attribution_id(verified_actor: str) -> str:
+    """The authoritative attribution identity for a verified GitHub login."""
+    return f"github:{verified_actor}"
+
+
+def github_email(data_root: Optional[Path] = None) -> str:
+    """Primary email of the gh-authenticated account (cached, best-effort).
+
+    Returns "" on any failure (no ``gh``, offline, unauthenticated) — identity
+    resolution never blocks attribution.
+    """
+    data = data_root or vcs_data_root()
+    cache = data / "identity.json"
+    if cache.exists():
+        try:
+            rec = json.loads(cache.read_text(encoding="utf-8"))
+            if rec.get("email") and time.time() - rec.get("ts", 0) < _TTL_SEC:
+                return rec["email"]
+        except (OSError, ValueError):
+            logger.debug("vcs: identity email cache unreadable, re-resolving")
+    try:
+        out = subprocess.run(
+            ["gh", "api", "user/emails", "--jq", ".[] | select(.primary) | .email"],
+            capture_output=True, text=True, encoding="utf-8",
+            timeout=5, check=True,
+        ).stdout.strip().splitlines()
+        email = out[0] if out else ""
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    if email:
+        try:
+            data.mkdir(parents=True, exist_ok=True)
+            rec: Dict[str, object] = {"ts": time.time(), "email": email}
+            try:
+                existing = (
+                    json.loads(cache.read_text(encoding="utf-8"))
+                    if cache.exists() else {}
+                )
+                if existing.get("login"):
+                    rec["login"] = existing["login"]
+            except (OSError, ValueError):
+                logger.debug("vcs: identity cache unreadable while merging")
+            tmp = cache.with_suffix(".tmp")
+            tmp.write_text(json.dumps(rec), encoding="utf-8")
+            os.replace(tmp, cache)
+        except OSError:
+            logger.debug("vcs: identity email cache write failed (best-effort)")
+    return email

awgit/leases.py

@@ -0,0 +1,264 @@
+"""Lease registry — conflict PREVENTION for concurrent agents.
+
+An agent registers intent ("I am editing nodes/files X") before editing; the
+registry grants or rejects so two agents never collide. Leases are
+heartbeat-renewed TTLs (the ``xPageDriverAt`` pattern): a lease self-heals when
+its holder disappears — expiry frees the target, never a kill switch.
+
+All-or-nothing acquire: if ANY requested target is held by another actor's
+ACTIVE lease, the whole batch is rejected naming the conflicting holder.
+
+The store is ``Library/Data/vcs/leases.json`` (gitignored). Mutations run under
+the same cross-process ``FileLock`` as the op-log.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from awgit.data_root import vcs_data_root
+from awgit.oplog import FileLock
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TTL_SEC = 300
+
+
+def _iso(offset_sec: int = 0) -> str:
+    return (datetime.now(timezone.utc) + timedelta(seconds=offset_sec)).isoformat()
+
+
+@dataclass
+class Lease:
+    lease_id: str
+    actor: str
+    kind: str  # "node" | "path"
+    target: str
+    granted_ts: str
+    expires_ts: str
+    heartbeat_ts: str
+    ttl_sec: int = DEFAULT_TTL_SEC
+    reason: str = ""
+    status: str = "active"  # active | expired | revoked | released
+
+    def to_dict(self) -> Dict[str, object]:
+        return {
+            "lease_id": self.lease_id,
+            "actor": self.actor,
+            "kind": self.kind,
+            "target": self.target,
+            "granted_ts": self.granted_ts,
+            "expires_ts": self.expires_ts,
+            "heartbeat_ts": self.heartbeat_ts,
+            "ttl_sec": self.ttl_sec,
+            "reason": self.reason,
+            "status": self.status,
+        }
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, object]) -> "Lease":
+        return cls(
+            lease_id=str(d["lease_id"]),
+            actor=str(d["actor"]),
+            kind=str(d.get("kind", "path")),
+            target=str(d["target"]),
+            granted_ts=str(d.get("granted_ts", "")),
+            expires_ts=str(d.get("expires_ts", "")),
+            heartbeat_ts=str(d.get("heartbeat_ts", "")),
+            ttl_sec=int(d.get("ttl_sec", DEFAULT_TTL_SEC)),
+            reason=str(d.get("reason", "")),
+            status=str(d.get("status", "active")),
+        )
+
+
+class LeaseConflictError(Exception):
+    """All-or-nothing acquire collided with another actor's active lease."""
+
+    def __init__(self, holder: "Lease"):
+        self.holder = holder
+        super().__init__(
+            f"lease conflict: {holder.target!r} held by {holder.actor!r} "
+            f"until {holder.expires_ts}"
+        )
+
+
+class LeaseRegistry:
+    """Heartbeat-renewed TTL lease registry (durable, cross-process)."""
+
+    def __init__(self, data_root: Optional[Path] = None) -> None:
+        self._data_root = data_root or vcs_data_root()
+        self._path = self._data_root / "leases.json"
+        self._leases: Dict[str, Lease] = {}
+        self._reload()
+
+    # ── persistence (always under the store lock) ────────────────────────
+
+    def _reload(self) -> None:
+        self._leases = {}
+        if not self._path.exists():
+            return
+        try:
+            payload = json.loads(self._path.read_text(encoding="utf-8"))
+            for d in payload.get("leases", []):
+                lz = Lease.from_dict(d)
+                self._leases[lz.lease_id] = lz
+        except (json.JSONDecodeError, KeyError, ValueError) as exc:
+            # Loud degrade, never silent: a corrupt store is empty + logged.
+            logger.warning("[vcs.leases] reload failed (%s); treating as empty", exc)
+
+    def _save(self) -> None:
+        self._data_root.mkdir(parents=True, exist_ok=True)
+        payload = {"leases": [lz.to_dict() for lz in self._leases.values()]}
+        tmp = self._path.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(payload, ensure_ascii=False), encoding="utf-8")
+        os.replace(tmp, self._path)
+
+    # ── core ops ─────────────────────────────────────────────────────────
+
+    def acquire(
+        self,
+        actor: str,
+        targets: List[str],
+        *,
+        ttl_sec: int = DEFAULT_TTL_SEC,
+        reason: str = "",
+        kind: Optional[str] = None,
+    ) -> List[Lease]:
+        """Grant a batch, or raise ``LeaseConflict`` naming the blocker.
+
+        All-or-nothing: if ANY target is held by another actor's active lease,
+        NO target is granted. Re-acquiring targets the SAME actor already holds
+        extends them (idempotent). Expired leases are swept first.
+        """
+        with FileLock(self._data_root / "leases.lock"):
+            self._reload()
+            self._mark_expired()
+            now = _iso()
+            active_by_target: Dict[str, List[Lease]] = {}
+            for lz in self._leases.values():
+                if lz.status == "active":
+                    active_by_target.setdefault(lz.target, []).append(lz)
+            for t in targets:
+                for lz in active_by_target.get(t, []):
+                    if lz.actor != actor:
+                        raise LeaseConflictError(lz)
+            granted: List[Lease] = []
+            for t in targets:
+                existing = [
+                    lz for lz in active_by_target.get(t, []) if lz.actor == actor
+                ]
+                if existing:
+                    lz = existing[0]
+                    lz.expires_ts = _iso(ttl_sec)
+                    lz.heartbeat_ts = now
+                    lz.reason = reason
+                    granted.append(lz)
+                else:
+                    k = kind or ("node" if t.startswith("node_") else "path")
+                    lz = Lease(
+                        lease_id=uuid.uuid4().hex,
+                        actor=actor,
+                        kind=k,
+                        target=t,
+                        granted_ts=now,
+                        expires_ts=_iso(ttl_sec),
+                        heartbeat_ts=now,
+                        ttl_sec=ttl_sec,
+                        reason=reason,
+                    )
+                    self._leases[lz.lease_id] = lz
+                    granted.append(lz)
+            self._save()
+            return granted
+
+    def heartbeat(self, actor: str, lease_ids: List[str]) -> int:
+        """Refresh TTL for the actor's active leases; returns count refreshed."""
+        with FileLock(self._data_root / "leases.lock"):
+            self._reload()
+            now = _iso()
+            count = 0
+            for lid in lease_ids:
+                lz = self._leases.get(lid)
+                if lz and lz.actor == actor and lz.status == "active":
+                    lz.expires_ts = _iso(lz.ttl_sec)
+                    lz.heartbeat_ts = now
+                    count += 1
+            if count:
+                self._save()
+            return count
+
+    def release(self, actor: str, lease_ids: List[str]) -> int:
+        """Mark the actor's leases released (frees targets immediately)."""
+        with FileLock(self._data_root / "leases.lock"):
+            self._reload()
+            now = _iso()
+            count = 0
+            for lid in lease_ids:
+                lz = self._leases.get(lid)
+                if lz and lz.actor == actor and lz.status == "active":
+                    lz.status = "released"
+                    lz.heartbeat_ts = now
+                    count += 1
+            if count:
+                self._save()
+            return count
+
+    def sweep_expired(self) -> int:
+        """Mark expired leases 'expired'; returns count swept."""
+        with FileLock(self._data_root / "leases.lock"):
+            self._reload()
+            n = self._mark_expired()
+            if n:
+                self._save()
+            return n
+
+    def _mark_expired(self) -> int:
+        now = _iso()
+        n = 0
+        for lz in self._leases.values():
+            # <= not <: a lease whose expiry has been REACHED is expired.
+            # With strict <, a ttl=0 lease granted and checked in the same
+            # microsecond never expires (a real timing race the tests caught).
+            if lz.status == "active" and lz.expires_ts <= now:
+                lz.status = "expired"
+                n += 1
+        return n
+
+    # ── queries ──────────────────────────────────────────────────────────
+
+    def get(self, lease_id: str) -> Optional[Lease]:
+        return self._leases.get(lease_id)
+
+    def active_leases(self) -> List[Lease]:
+        return [lz for lz in self._leases.values() if lz.status == "active"]
+
+    def leases_by_actor(self, actor: str) -> List[Lease]:
+        return [lz for lz in self._leases.values() if lz.actor == actor]
+
+
+def coverage_gap(
+    changed_files: List[str],
+    actor: str,
+    data_root: Optional[Path] = None,
+) -> List[str]:
+    """Changed Python files NOT covered by the actor's active path-leases.
+
+    The pre-commit gate's primitive: a commit touching a Python file with no
+    active path-lease is an unleased edit — a visible risk flag when leases
+    are enforced (VCS_LEASES_ENFORCE=1), recorded as ``leased=false`` otherwise.
+    """
+    registry = LeaseRegistry(data_root=data_root)
+    registry.sweep_expired()
+    covered = {
+        lz.target
+        for lz in registry.active_leases()
+        if lz.actor == actor and lz.kind == "path"
+    }
+    return [f for f in changed_files if f.endswith(".py") and f not in covered]

awgit/ledger.py

@@ -0,0 +1,80 @@
+"""Ledger attribution — the op-log as a durable who-changed-what record.
+
+Each EditOp already carries everything attribution needs: actor, verified
+GitHub identity, git_sha, node_changes, parent chain, timestamp. This module
+flattens an op into a ``LedgerEntry`` — the record a team (or a downstream
+reward program) can point at. The op-log itself only ever RECORDS; it never
+gates a commit.
+
+``ledger_ref`` is the durable attribution handle. It is minted deterministically
+from (op_id, git_sha), so it is stable across op-log replays/exports and needs
+no external counter.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from typing import Dict, List
+
+from awgit.schema import EditOp
+
+
+@dataclass
+class LedgerEntry:
+    """One op flattened into an attribution record."""
+
+    ledger_ref: str
+    op_id: str
+    actor: str
+    verified_actor: str
+    actor_verified: bool
+    git_sha: str
+    git_parent_sha: str
+    ts: str
+    file_paths: List[str]
+    node_changes: int
+    change_types: Dict[str, int]
+    summary: str
+
+    def to_dict(self) -> Dict[str, object]:
+        return {
+            "ledger_ref": self.ledger_ref,
+            "op_id": self.op_id,
+            "actor": self.actor,
+            "verified_actor": self.verified_actor,
+            "actor_verified": self.actor_verified,
+            "git_sha": self.git_sha,
+            "git_parent_sha": self.git_parent_sha,
+            "ts": self.ts,
+            "file_paths": list(self.file_paths),
+            "node_changes": self.node_changes,
+            "change_types": dict(self.change_types),
+            "summary": self.summary,
+        }
+
+
+def mint_ledger_ref(op_id: str, git_sha: str) -> str:
+    """Deterministic ledger ref — stable across replays, no external state."""
+    return hashlib.sha256(f"op:{op_id}:{git_sha}".encode()).hexdigest()[:16]
+
+
+def op_to_ledger_entry(op: EditOp) -> LedgerEntry:
+    """Convert an op to its attribution record."""
+    counts: Dict[str, int] = {}
+    for nc in op.node_changes:
+        counts[nc.change_type] = counts.get(nc.change_type, 0) + 1
+    return LedgerEntry(
+        ledger_ref=op.ledger_ref or mint_ledger_ref(op.op_id, op.git_sha),
+        op_id=op.op_id,
+        actor=op.actor,
+        verified_actor=op.verified_actor,
+        actor_verified=op.actor_verified,
+        git_sha=op.git_sha,
+        git_parent_sha=op.git_parent_sha,
+        ts=op.ts,
+        file_paths=list(op.file_paths),
+        node_changes=len(op.node_changes),
+        change_types=counts,
+        summary=op.summary,
+    )

awgit/mcp.py

@@ -0,0 +1,94 @@
+"""MCP tool surface for the semantic-VCS layer (gateway :8182).
+
+Handlers are PURE functions returning JSON-able dicts — the tool LOGIC. Wiring
+them into the gateway's MCP server is a thin seam (see ``register_tools``).
+Phase 6+ integration targets (notebooks, RLM/AgentForge, AitherFlow) consume
+exactly these handlers.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from awgit.data_root import vcs_data_root
+from awgit.diff import diff_git, render
+from awgit.leases import LeaseConflictError, LeaseRegistry
+from awgit.merge import list_conflicts
+from awgit.oplog import OpLog
+
+
+def _root(data_root: Optional[str]) -> Path:
+    return Path(data_root) if data_root else vcs_data_root()
+
+
+def vcs_semantic_diff(a: str, b: str, **kw) -> Dict[str, Any]:
+    """Node-level diff between two shas (JSON shape for MCP/agents)."""
+    changes = diff_git(a, b, data_root=_root(kw.get("data_root")))
+    return {
+        "count": len(changes),
+        "changes": [c.to_dict() for c in changes],
+        "rendered": render(changes),
+    }
+
+
+def vcs_oplog_query(
+    sha: Optional[str] = None,
+    node_id: Optional[str] = None,
+    actor: Optional[str] = None,
+    limit: int = 50,
+    **kw,
+) -> Dict[str, Any]:
+    """Query the op-log by commit / node / actor."""
+    log = OpLog(data_root=_root(kw.get("data_root")))
+    if sha:
+        ops = log.ops_for_commit(sha)
+    elif node_id:
+        ops = log.ops_for_node(node_id)
+    elif actor:
+        ops = log.ops_by(actor)
+    else:
+        ops = log.all_ops()
+    return {"count": len(ops), "ops": [op.to_dict() for op in ops[-limit:]]}
+
+
+def vcs_lease_acquire(
+    actor: str, targets: List[str], ttl_sec: int = 300, reason: str = "", **kw
+) -> Dict[str, Any]:
+    """Acquire leases all-or-nothing; returns the conflicting lease if any."""
+    registry = LeaseRegistry(data_root=_root(kw.get("data_root")))
+    try:
+        leases = registry.acquire(actor, targets, ttl_sec=ttl_sec, reason=reason)
+        return {"granted": [lz.to_dict() for lz in leases], "conflict": None}
+    except LeaseConflictError as exc:
+        return {"granted": [], "conflict": exc.holder.to_dict()}
+
+
+def vcs_lease_list(actor: Optional[str] = None, **kw) -> Dict[str, Any]:
+    """List active leases, optionally filtered by actor."""
+    leases = LeaseRegistry(data_root=_root(kw.get("data_root"))).active_leases()
+    if actor:
+        leases = [lz for lz in leases if lz.actor == actor]
+    return {"count": len(leases), "leases": [lz.to_dict() for lz in leases]}
+
+
+def vcs_merge_conflicts(status: Optional[str] = None, **kw) -> Dict[str, Any]:
+    """List escalated merge conflicts, optionally filtered by status."""
+    conflicts = list_conflicts(data_root=_root(kw.get("data_root")))
+    if status:
+        conflicts = [c for c in conflicts if c.status == status]
+    return {"count": len(conflicts), "conflicts": [c.to_dict() for c in conflicts]}
+
+
+def register_tools(server) -> int:
+    """Wire the handlers onto an MCP server (gateway :8182).
+
+    The gateway exposes a tool registry; the exact registration API is the
+    gateway seam. Wire these when the MCP surface is enabled:
+      server.tool("vcs_semantic_diff", desc)(vcs_semantic_diff)
+      server.tool("vcs_oplog_query", desc)(vcs_oplog_query)
+      server.tool("vcs_lease_acquire", desc)(vcs_lease_acquire)
+      server.tool("vcs_lease_list", desc)(vcs_lease_list)
+      server.tool("vcs_merge_conflicts", desc)(vcs_merge_conflicts)
+    """
+    return 5