graphite-code 0.3.0__py3-none-any.whl

graphite/routing/__init__.py

@@ -0,0 +1,5 @@
+"""Approval-gated development model routing for Graphite."""
+
+from .settings import RoutingSettings, RoutingSettingsError
+
+__all__ = ["RoutingSettings", "RoutingSettingsError"]

graphite/routing/approval.py

@@ -0,0 +1,362 @@
+"""Default-No consent, HMAC integrity, and single-use quota coordination."""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import secrets
+import sqlite3
+from contextlib import closing
+import stat
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, TextIO
+
+from .contracts import ApprovalManifest, CliApprovalManifest
+from .route_pool import ApprovedRoutePool
+from .storage import RepositoryStore, StorageError
+
+_REPARSE_POINT = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
+
+
+class ApprovalError(RuntimeError):
+    """A stable, path-free approval failure."""
+
+    def __init__(self, code: str) -> None:
+        self.code = code
+        super().__init__(code)
+
+
+@dataclass(frozen=True)
+class SignedApproval:
+    manifest: ApprovalManifest | CliApprovalManifest | ApprovedRoutePool
+    signature: str
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "manifest": self.manifest.to_dict(),
+            "signature": self.signature,
+        }
+
+
+def approval_prompt(
+    *,
+    stdin: TextIO,
+    stdout: TextIO,
+    stdin_is_tty: bool,
+    stdout_is_tty: bool,
+    json_mode: bool,
+    assume_yes: bool,
+    ci: bool,
+) -> bool:
+    """Request one explicit interactive approval; every other mode declines."""
+    if (
+        not stdin_is_tty
+        or not stdout_is_tty
+        or json_mode
+        or assume_yes
+        or ci
+    ):
+        return False
+    stdout.write("Approve this development model call? [y/N] ")
+    stdout.flush()
+    try:
+        answer = stdin.readline(16)
+    except (EOFError, OSError):
+        return False
+    return answer.strip().casefold() in {"y", "yes"}
+
+
+def _canonical_manifest(
+    manifest: ApprovalManifest | CliApprovalManifest | ApprovedRoutePool,
+) -> bytes:
+    return json.dumps(
+        manifest.to_dict(),
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+
+
+def _is_reparse(metadata: os.stat_result) -> bool:
+    return bool(getattr(metadata, "st_file_attributes", 0) & _REPARSE_POINT)
+
+
+def _secure_parent(path: Path) -> None:
+    try:
+        path.mkdir(parents=True, exist_ok=True, mode=0o700)
+        metadata = path.lstat()
+        if stat.S_ISLNK(metadata.st_mode) or _is_reparse(metadata) or not stat.S_ISDIR(metadata.st_mode):
+            raise ApprovalError("approval_state_path_invalid")
+        if os.name != "nt":
+            path.chmod(0o700)
+    except ApprovalError:
+        raise
+    except OSError as exc:
+        raise ApprovalError("approval_state_unavailable") from exc
+
+
+def _load_or_create_key(path: Path, repository_root: Path) -> bytes:
+    resolved_parent = path.parent.resolve(strict=False)
+    try:
+        resolved_parent.relative_to(repository_root)
+    except ValueError:
+        pass
+    else:
+        raise ApprovalError("approval_key_path_invalid")
+    _secure_parent(path.parent)
+    try:
+        metadata = path.lstat()
+    except FileNotFoundError:
+        metadata = None
+    except OSError as exc:
+        raise ApprovalError("approval_key_unavailable") from exc
+    if metadata is None:
+        key = secrets.token_bytes(32)
+        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0)
+        try:
+            descriptor = os.open(path, flags, 0o600)
+            try:
+                written = os.write(descriptor, key)
+                if written != len(key):
+                    raise ApprovalError("approval_key_unavailable")
+                os.fsync(descriptor)
+            finally:
+                os.close(descriptor)
+        except FileExistsError:
+            return _load_or_create_key(path, repository_root)
+        except ApprovalError:
+            raise
+        except OSError as exc:
+            raise ApprovalError("approval_key_unavailable") from exc
+        if os.name != "nt":
+            path.chmod(0o600)
+        return key
+    if stat.S_ISLNK(metadata.st_mode) or _is_reparse(metadata) or not stat.S_ISREG(metadata.st_mode):
+        raise ApprovalError("approval_key_path_invalid")
+    if metadata.st_size != 32:
+        raise ApprovalError("approval_key_invalid")
+    try:
+        key = path.read_bytes()
+    except OSError as exc:
+        raise ApprovalError("approval_key_unavailable") from exc
+    if len(key) != 32:
+        raise ApprovalError("approval_key_invalid")
+    return key
+
+
+class _MachineQuotaStore:
+    def __init__(self, path: Path, repository_root: Path) -> None:
+        resolved = path.resolve(strict=False)
+        try:
+            resolved.relative_to(repository_root)
+        except ValueError:
+            pass
+        else:
+            raise ApprovalError("quota_path_invalid")
+        self.path = path
+        _secure_parent(path.parent)
+        try:
+            with closing(sqlite3.connect(path, timeout=2.0)) as connection, connection:
+                connection.execute("PRAGMA busy_timeout = 2000")
+                connection.execute(
+                    """CREATE TABLE IF NOT EXISTS reservations (
+                        nonce_hash TEXT PRIMARY KEY,
+                        token_amount INTEGER NOT NULL,
+                        status TEXT NOT NULL CHECK(status IN ('reserved', 'released', 'settled')),
+                        created_at INTEGER NOT NULL
+                    )"""
+                )
+        except sqlite3.Error as exc:
+            raise ApprovalError("quota_unavailable") from exc
+        if os.name != "nt":
+            path.chmod(0o600)
+
+    def reserve(self, nonce_hash: str, amount: int, quota: int, created_at: int) -> None:
+        connection: sqlite3.Connection | None = None
+        try:
+            connection = sqlite3.connect(self.path, timeout=2.0, isolation_level=None)
+            connection.execute("PRAGMA busy_timeout = 2000")
+            connection.execute("BEGIN IMMEDIATE")
+            existing = connection.execute(
+                "SELECT status FROM reservations WHERE nonce_hash = ?",
+                (nonce_hash,),
+            ).fetchone()
+            if existing is not None:
+                raise ApprovalError("approval_reused")
+            total = int(
+                connection.execute(
+                    "SELECT COALESCE(SUM(token_amount), 0) FROM reservations WHERE status = 'reserved'"
+                ).fetchone()[0]
+            )
+            if amount > quota or total + amount > quota:
+                raise ApprovalError("budget_exhausted")
+            connection.execute(
+                "INSERT INTO reservations(nonce_hash, token_amount, status, created_at) VALUES (?, ?, 'reserved', ?)",
+                (nonce_hash, amount, created_at),
+            )
+            connection.commit()
+        except ApprovalError:
+            if connection is not None and connection.in_transaction:
+                connection.rollback()
+            raise
+        except sqlite3.Error as exc:
+            if connection is not None and connection.in_transaction:
+                connection.rollback()
+            raise ApprovalError("quota_unavailable") from exc
+        finally:
+            if connection is not None:
+                connection.close()
+
+    def release(self, nonce_hash: str) -> None:
+        try:
+            with closing(sqlite3.connect(self.path, timeout=2.0)) as connection, connection:
+                connection.execute(
+                    "UPDATE reservations SET status = 'released' WHERE nonce_hash = ? AND status = 'reserved'",
+                    (nonce_hash,),
+                )
+        except sqlite3.Error as exc:
+            raise ApprovalError("quota_unavailable") from exc
+
+    def reserved_total(self) -> int:
+        try:
+            with closing(sqlite3.connect(self.path, timeout=2.0)) as connection, connection:
+                return int(
+                    connection.execute(
+                        "SELECT COALESCE(SUM(token_amount), 0) FROM reservations WHERE status = 'reserved'"
+                    ).fetchone()[0]
+                )
+        except sqlite3.Error as exc:
+            raise ApprovalError("quota_unavailable") from exc
+
+
+class ApprovalAuthority:
+    """Issues and consumes signed approvals.
+
+    HMAC protects cross-file and accidental tampering. A hostile process running
+    as the same operating-system user remains outside this trust boundary.
+    """
+
+    def __init__(
+        self,
+        store: RepositoryStore,
+        *,
+        key_path: Path,
+        quota_path: Path,
+        now: Callable[[], int] | None = None,
+    ) -> None:
+        self.store = store
+        self._key = _load_or_create_key(key_path, store.root)
+        self._quota = _MachineQuotaStore(quota_path, store.root)
+        self._now = now or (lambda: int(time.time()))
+
+    def issue(
+        self,
+        manifest: ApprovalManifest | CliApprovalManifest | ApprovedRoutePool,
+        *,
+        lifecycle_identity_digest: str | None = None,
+        capability_snapshot_digest: str | None = None,
+        bound_at: int | None = None,
+    ) -> SignedApproval:
+        lifecycle_values = (
+            lifecycle_identity_digest,
+            capability_snapshot_digest,
+            bound_at,
+        )
+        if any(value is not None for value in lifecycle_values) and (
+            not isinstance(manifest, CliApprovalManifest)
+            or lifecycle_identity_digest is None
+            or capability_snapshot_digest != manifest.capability_snapshot_digest
+            or bound_at is None
+        ):
+            raise ApprovalError("approval_lifecycle_binding_invalid")
+        payload = _canonical_manifest(manifest)
+        manifest_hash = hashlib.sha256(payload).hexdigest()
+        nonce_hash = hashlib.sha256(manifest.nonce.encode("utf-8")).hexdigest()
+        signature = hmac.new(self._key, payload, hashlib.sha256).hexdigest()
+        try:
+            self.store.save_approval_record(
+                approval_id=manifest.approval_id,
+                task_id=None,
+                decision_id=None,
+                nonce_hash=nonce_hash,
+                manifest_hash=manifest_hash,
+                expires_at=manifest.expires_at,
+                reserved_tokens=manifest.max_input_tokens + manifest.max_output_tokens,
+            )
+        except StorageError as exc:
+            raise ApprovalError(exc.code) from exc
+        if any(value is not None for value in lifecycle_values):
+            assert isinstance(manifest, CliApprovalManifest)
+            assert lifecycle_identity_digest is not None
+            assert capability_snapshot_digest is not None
+            assert bound_at is not None
+            try:
+                self.store.save_lifecycle_approval_binding(
+                    approval_id=manifest.approval_id,
+                    capability_snapshot_digest=capability_snapshot_digest,
+                    lifecycle_identity_digest=lifecycle_identity_digest,
+                    bound_at=bound_at,
+                )
+            except (StorageError, ValueError):
+                raise ApprovalError("approval_lifecycle_binding_invalid") from None
+        return SignedApproval(manifest, signature)
+
+    def verify(
+        self,
+        signed: SignedApproval,
+        current_manifest: ApprovalManifest | CliApprovalManifest | ApprovedRoutePool,
+    ) -> None:
+        if not isinstance(signed, SignedApproval):
+            raise ApprovalError("approval_invalid")
+        signed_payload = _canonical_manifest(signed.manifest)
+        current_payload = _canonical_manifest(current_manifest)
+        if not hmac.compare_digest(signed_payload, current_payload):
+            raise ApprovalError("approval_manifest_changed")
+        expected = hmac.new(self._key, signed_payload, hashlib.sha256).hexdigest()
+        if not hmac.compare_digest(expected, signed.signature):
+            raise ApprovalError("approval_signature_invalid")
+
+    def consume(
+        self,
+        signed: SignedApproval,
+        current_manifest: ApprovalManifest | CliApprovalManifest | ApprovedRoutePool,
+        *,
+        repository_quota_tokens: int,
+        machine_quota_tokens: int,
+        lifecycle_identity_digest: str | None = None,
+        capability_snapshot_digest: str | None = None,
+    ) -> None:
+        self.verify(signed, current_manifest)
+        if lifecycle_identity_digest is not None or capability_snapshot_digest is not None:
+            try:
+                binding = self.store.lifecycle_approval_binding_details(
+                    current_manifest.approval_id
+                )
+            except (StorageError, ValueError):
+                raise ApprovalError("approval_lifecycle_stale") from None
+            if not isinstance(current_manifest, CliApprovalManifest) or lifecycle_identity_digest is None or capability_snapshot_digest != current_manifest.capability_snapshot_digest or binding != (capability_snapshot_digest, lifecycle_identity_digest):
+                raise ApprovalError("approval_lifecycle_stale")
+        now = self._now()
+        if now >= current_manifest.expires_at:
+            raise ApprovalError("approval_expired")
+        amount = current_manifest.max_input_tokens + current_manifest.max_output_tokens
+        nonce_hash = hashlib.sha256(current_manifest.nonce.encode("utf-8")).hexdigest()
+        manifest_hash = hashlib.sha256(_canonical_manifest(current_manifest)).hexdigest()
+        self._quota.reserve(nonce_hash, amount, machine_quota_tokens, now)
+        try:
+            self.store.consume_approval_record(
+                approval_id=current_manifest.approval_id,
+                nonce_hash=nonce_hash,
+                manifest_hash=manifest_hash,
+                now=now,
+                token_amount=amount,
+                repository_quota=repository_quota_tokens,
+            )
+        except StorageError as exc:
+            self._quota.release(nonce_hash)
+            raise ApprovalError(exc.code) from exc
+
+    def machine_reserved_token_total(self) -> int:
+        return self._quota.reserved_total()

graphite/routing/classifier.py

@@ -0,0 +1,169 @@
+"""Deterministic task classification from requests and bounded graph evidence."""
+from __future__ import annotations
+
+import hashlib
+import json
+from collections import deque
+from typing import Any, Final
+
+from .contracts import RiskTier, TaskCategory, TaskProfile, TaskRequest
+
+MAX_IMPACT_NODES: Final = 10_000
+
+_CATEGORY_RULES: tuple[tuple[TaskCategory, tuple[str, ...]], ...] = (
+    (TaskCategory.TENANT_ISOLATION, ("tenant isolation", "cross-tenant", "multi-tenant")),
+    (TaskCategory.AUTHORIZATION, ("authorization", "authorisation", "permission", "role access")),
+    (TaskCategory.AUTHENTICATION, ("authentication", "login", "sign in", "oauth", "session")),
+    (TaskCategory.MIGRATION, ("database migration", "schema migration", "rollback migration")),
+    (TaskCategory.DEPLOYMENT, ("deployment", "deploy", "release pipeline", "production release")),
+    (TaskCategory.INFRASTRUCTURE, ("infrastructure", "terraform", "kubernetes", "cloud provision")),
+    (TaskCategory.CONCURRENCY, ("concurrent", "concurrency", "race condition", "deadlock", "transaction race")),
+    (TaskCategory.FINANCIAL, ("financial", "money", "mortgage", "payment", "billing", "invoice")),
+    (TaskCategory.LEGAL, ("legal", "contract clause", "compliance policy")),
+    (TaskCategory.ARCHITECTURE, ("architecture", "system design", "service boundary")),
+    (TaskCategory.REFACTOR, ("refactor", "restructure", "extract module")),
+    (TaskCategory.FEATURE, ("feature", "add a", "implement", "customer search", "endpoint")),
+    (TaskCategory.ISOLATED_CODE, ("isolated", "formatting helper", "small helper", "typo fix")),
+    (TaskCategory.DOCUMENTATION, ("documentation", "readme", "guide", "docs")),
+)
+
+_CATEGORY_RISK: Final[dict[TaskCategory, RiskTier]] = {
+    TaskCategory.DOCUMENTATION: RiskTier.LOW,
+    TaskCategory.ISOLATED_CODE: RiskTier.LOW,
+    TaskCategory.FEATURE: RiskTier.MEDIUM,
+    TaskCategory.REFACTOR: RiskTier.MEDIUM,
+    TaskCategory.ARCHITECTURE: RiskTier.HIGH,
+    TaskCategory.AUTHENTICATION: RiskTier.HIGH,
+    TaskCategory.AUTHORIZATION: RiskTier.HIGH,
+    TaskCategory.TENANT_ISOLATION: RiskTier.HIGH,
+    TaskCategory.MIGRATION: RiskTier.HIGH,
+    TaskCategory.DEPLOYMENT: RiskTier.HIGH,
+    TaskCategory.INFRASTRUCTURE: RiskTier.HIGH,
+    TaskCategory.CONCURRENCY: RiskTier.HIGH,
+    TaskCategory.FINANCIAL: RiskTier.HIGH,
+    TaskCategory.LEGAL: RiskTier.HIGH,
+    TaskCategory.UNKNOWN: RiskTier.HIGH,
+}
+_RISK_ORDER = {RiskTier.LOW: 0, RiskTier.MEDIUM: 1, RiskTier.HIGH: 2}
+
+
+def _detect_category(objective: str) -> TaskCategory:
+    normalized = " ".join(objective.casefold().split())
+    for category, keywords in _CATEGORY_RULES:
+        if any(keyword in normalized for keyword in keywords):
+            return category
+    return TaskCategory.UNKNOWN
+
+
+def _target_nodes(graph: Any, targets: tuple[str, ...]) -> list[str]:
+    selected: list[str] = []
+    target_set = set(targets)
+    try:
+        nodes = graph.nodes(data=True)
+    except (AttributeError, TypeError):
+        return []
+    for node_id, data in nodes:
+        if isinstance(data, dict) and data.get("source_file") in target_set:
+            selected.append(str(node_id))
+    return sorted(set(selected))
+
+
+def _bounded_impact(graph: Any, starts: list[str]) -> tuple[set[str], bool]:
+    visited = set(starts)
+    queue = deque(starts)
+    truncated = False
+    while queue:
+        node = queue.popleft()
+        try:
+            neighbors = set(graph.predecessors(node)) | set(graph.successors(node))
+        except (AttributeError, KeyError):
+            continue
+        for neighbor in sorted(neighbors, key=str):
+            normalized = str(neighbor)
+            if normalized in visited:
+                continue
+            if len(visited) >= MAX_IMPACT_NODES:
+                truncated = True
+                return visited, truncated
+            visited.add(normalized)
+            queue.append(normalized)
+    return visited, truncated
+
+
+def classify_task(request: TaskRequest, graph: Any) -> TaskProfile:
+    """Classify a request using fixed rules and bounded graph features."""
+    detected = _detect_category(request.objective)
+    category = detected
+    detected_risk = _CATEGORY_RISK[detected]
+    if request.category_hint is not None:
+        hint_risk = _CATEGORY_RISK[request.category_hint]
+        if _RISK_ORDER[hint_risk] > _RISK_ORDER[detected_risk]:
+            category = request.category_hint
+    risk = _CATEGORY_RISK[category]
+
+    starts = _target_nodes(graph, request.targets)
+    impacted, truncated = _bounded_impact(graph, starts)
+    flags: list[str] = []
+    communities: set[object] = set()
+    tests_nearby = False
+    for node in sorted(impacted):
+        try:
+            data = graph.nodes[node]
+        except (AttributeError, KeyError):
+            continue
+        source_file = data.get("source_file") if isinstance(data, dict) else None
+        if isinstance(source_file, str) and (
+            source_file.startswith("tests/")
+            or ".test." in source_file
+            or ".spec." in source_file
+            or source_file.endswith("_test.py")
+        ):
+            tests_nearby = True
+        if isinstance(data, dict) and data.get("community") is not None:
+            communities.add(data["community"])
+    if tests_nearby:
+        flags.append("tests_nearby")
+    if len(communities) > 1:
+        flags.append("community_crossing")
+    if len(impacted) >= 25 or truncated:
+        flags.append("broad_impact")
+        if risk is RiskTier.LOW:
+            risk = RiskTier.MEDIUM
+    if detected is TaskCategory.UNKNOWN:
+        flags.append("unknown_scope")
+    if risk is RiskTier.HIGH:
+        flags.append("high_risk_category")
+
+    verification = ["tests"]
+    if risk is RiskTier.HIGH:
+        verification.extend(("security_review", "manual_frontier_review"))
+    if category is TaskCategory.MIGRATION:
+        verification.append("rollback_test")
+    complexity = min(
+        10,
+        max(1, 1 + len(request.targets) + len(impacted) // 5 + _RISK_ORDER[risk] * 2),
+    )
+    task_material = json.dumps(
+        {
+            "objective": request.objective,
+            "targets": list(request.targets),
+            "category": category.value,
+            "risk": risk.value,
+        },
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    task_id = "task-" + hashlib.sha256(task_material).hexdigest()[:24]
+    context_requirements = ["explicit_targets"]
+    if impacted:
+        context_requirements.append("dependency_neighbors")
+    return TaskProfile(
+        task_id=task_id,
+        category=category,
+        risk=risk,
+        complexity=complexity,
+        impact_radius=len(impacted),
+        risk_flags=tuple(flags),
+        context_requirements=tuple(context_requirements),
+        verification_requirements=tuple(verification),
+    )