zexus 1.6.2

package/src/zexus/policy_engine.py

@@ -0,0 +1,365 @@
+# src/zexus/policy_engine.py
+"""
+Policy-as-Code Engine for Zexus PROTECT Feature
+Implements declarative security policy injection with VERIFY and RESTRICT
+"""
+
+from typing import Dict, List, Any, Callable, Optional
+from .object import Object, Boolean as BooleanObj, String, Integer, NULL, EvaluationError
+
+
+# ===============================================
+# POLICY RULE TYPES
+# ===============================================
+
+class PolicyRule:
+    """Base class for policy rules"""
+    
+    def __init__(self, description: str = ""):
+        self.description = description
+    
+    def evaluate(self, context: Dict[str, Any]) -> tuple[bool, str]:
+        """
+        Evaluate the policy rule
+        Returns: (success: bool, message: str)
+        """
+        raise NotImplementedError("Subclasses must implement evaluate()")
+
+
+class VerifyRule(PolicyRule):
+    """VERIFY rule - checks a boolean condition"""
+    
+    def __init__(self, condition_fn: Callable, description: str = "Verification check"):
+        super().__init__(description)
+        self.condition_fn = condition_fn
+    
+    def evaluate(self, context: Dict[str, Any]) -> tuple[bool, str]:
+        try:
+            result = self.condition_fn(context)
+            success = result.value if isinstance(result, BooleanObj) else bool(result)
+            message = self.description if not success else ""
+            return success, message
+        except Exception as e:
+            return False, f"Verification failed: {str(e)}"
+
+
+class RestrictRule(PolicyRule):
+    """RESTRICT rule - applies constraints to data"""
+    
+    def __init__(self, field_name: str, constraints: List[Callable], description: str = ""):
+        super().__init__(description)
+        self.field_name = field_name
+        self.constraints = constraints
+    
+    def evaluate(self, context: Dict[str, Any]) -> tuple[bool, str]:
+        value = context.get(self.field_name)
+        
+        if value is None:
+            return False, f"Field '{self.field_name}' not found in context"
+        
+        for constraint in self.constraints:
+            try:
+                result = constraint(value, context)
+                passed = result.value if isinstance(result, BooleanObj) else bool(result)
+                if not passed:
+                    return False, f"Constraint failed for '{self.field_name}'"
+            except Exception as e:
+                return False, f"Constraint evaluation error: {str(e)}"
+        
+        return True, ""
+
+
+# ===============================================
+# PROTECTION POLICY
+# ===============================================
+
+class ProtectionPolicy:
+    """Represents a complete protection policy for a target"""
+    
+    def __init__(self, target_name: str, enforcement_level: str = "strict"):
+        self.target_name = target_name
+        self.enforcement_level = enforcement_level  # "strict", "warn", "audit", "permissive"
+        self.rules: List[PolicyRule] = []
+        self.middleware_chain: List[Callable] = []
+        self.on_violation: Optional[Callable] = None
+        self.audit_log: List[Dict[str, Any]] = []
+    
+    def add_rule(self, rule: PolicyRule):
+        """Add a policy rule"""
+        self.rules.append(rule)
+    
+    def add_middleware(self, middleware: Callable):
+        """Add middleware to the protection chain"""
+        self.middleware_chain.append(middleware)
+    
+    def set_violation_handler(self, handler: Callable):
+        """Set handler for policy violations"""
+        self.on_violation = handler
+    
+    def evaluate(self, context: Dict[str, Any]) -> tuple[bool, List[str]]:
+        """
+        Evaluate all policy rules
+        Returns: (all_passed: bool, violation_messages: List[str])
+        """
+        violations = []
+        
+        for rule in self.rules:
+            passed, message = rule.evaluate(context)
+            
+            if not passed:
+                violations.append(message)
+                
+                # Log the violation
+                self._audit_violation(rule, message, context)
+                
+                # Handle based on enforcement level
+                if self.enforcement_level == "strict":
+                    # Strict mode: fail immediately
+                    return False, violations
+                elif self.enforcement_level == "warn":
+                    # Warn mode: continue but collect violations
+                    print(f"⚠️  Policy Warning ({self.target_name}): {message}")
+                elif self.enforcement_level == "audit":
+                    # Audit mode: log only, allow execution
+                    pass
+                # permissive mode: do nothing
+        
+        # All rules passed or enforcement allows it
+        all_passed = len(violations) == 0
+        return all_passed, violations
+    
+    def execute_middleware(self, context: Dict[str, Any], original_fn: Callable):
+        """Execute middleware chain"""
+        # Build middleware chain
+        def final_handler():
+            return original_fn(context)
+        
+        # Wrap with each middleware (reverse order for proper nesting)
+        handler = final_handler
+        for middleware in reversed(self.middleware_chain):
+            current_handler = handler
+            handler = lambda ctx=context, mw=middleware, h=current_handler: mw(ctx, h)
+        
+        # Execute the chain
+        return handler()
+    
+    def _audit_violation(self, rule: PolicyRule, message: str, context: Dict[str, Any]):
+        """Log a policy violation"""
+        import time
+        self.audit_log.append({
+            'timestamp': time.time(),
+            'target': self.target_name,
+            'rule': rule.description,
+            'message': message,
+            'context_keys': list(context.keys()),
+            'enforcement_level': self.enforcement_level
+        })
+    
+    def get_audit_log(self) -> List[Dict[str, Any]]:
+        """Get audit log"""
+        return self.audit_log
+
+
+# ===============================================
+# POLICY REGISTRY
+# ===============================================
+
+class PolicyRegistry:
+    """Global registry for protection policies"""
+    
+    def __init__(self):
+        self.policies: Dict[str, ProtectionPolicy] = {}
+        self.protected_functions: Dict[str, Callable] = {}
+    
+    def register_policy(self, target_name: str, policy: ProtectionPolicy):
+        """Register a protection policy for a target"""
+        self.policies[target_name] = policy
+    
+    def get_policy(self, target_name: str) -> Optional[ProtectionPolicy]:
+        """Get policy for a target"""
+        return self.policies.get(target_name)
+    
+    def protect_function(self, func_name: str, original_fn: Callable, policy: ProtectionPolicy):
+        """Wrap a function with policy enforcement"""
+        self.protected_functions[func_name] = original_fn
+        self.register_policy(func_name, policy)
+    
+    def execute_protected(self, func_name: str, context: Dict[str, Any]):
+        """Execute a protected function with policy checks"""
+        policy = self.get_policy(func_name)
+        original_fn = self.protected_functions.get(func_name)
+        
+        if not policy or not original_fn:
+            raise ValueError(f"Function '{func_name}' not registered for protection")
+        
+        # Evaluate policy
+        passed, violations = policy.evaluate(context)
+        
+        if not passed and policy.enforcement_level == "strict":
+            error_msg = "; ".join(violations)
+            if policy.on_violation:
+                return policy.on_violation(violations, context)
+            raise EvaluationError(f"Policy violation for {func_name}: {error_msg}")
+        
+        # Execute middleware chain
+        return policy.execute_middleware(context, original_fn)
+    
+    def list_protected_targets(self) -> List[str]:
+        """List all protected targets"""
+        return list(self.policies.keys())
+    
+    def get_audit_summary(self) -> Dict[str, Any]:
+        """Get summary of all audit logs"""
+        total_violations = 0
+        by_target = {}
+        
+        for target_name, policy in self.policies.items():
+            violations = policy.get_audit_log()
+            total_violations += len(violations)
+            by_target[target_name] = len(violations)
+        
+        return {
+            'total_violations': total_violations,
+            'by_target': by_target,
+            'protected_targets': len(self.policies)
+        }
+
+
+# Global policy registry
+_policy_registry = PolicyRegistry()
+
+
+def get_policy_registry() -> PolicyRegistry:
+    """Get the global policy registry"""
+    return _policy_registry
+
+
+# ===============================================
+# POLICY BUILDER (DSL Support)
+# ===============================================
+
+class PolicyBuilder:
+    """Builder for creating policies from PROTECT blocks"""
+    
+    def __init__(self, target_name: str):
+        self.policy = ProtectionPolicy(target_name)
+    
+    def add_verify_condition(self, condition_fn: Callable, description: str = ""):
+        """Add a VERIFY rule"""
+        rule = VerifyRule(condition_fn, description)
+        self.policy.add_rule(rule)
+        return self
+    
+    def add_restrict_constraint(self, field_name: str, constraints: List[Callable], description: str = ""):
+        """Add a RESTRICT rule"""
+        rule = RestrictRule(field_name, constraints, description)
+        self.policy.add_rule(rule)
+        return self
+    
+    def set_enforcement(self, level: str):
+        """Set enforcement level"""
+        self.policy.enforcement_level = level
+        return self
+    
+    def with_middleware(self, middleware: Callable):
+        """Add middleware"""
+        self.policy.add_middleware(middleware)
+        return self
+    
+    def on_violation(self, handler: Callable):
+        """Set violation handler"""
+        self.policy.set_violation_handler(handler)
+        return self
+    
+    def build(self) -> ProtectionPolicy:
+        """Build and return the policy"""
+        return self.policy
+
+
+# ===============================================
+# BUILT-IN POLICY CONSTRAINTS
+# ===============================================
+
+def length_constraint(min_len: int = 0, max_len: int = float('inf')):
+    """Create a length constraint for strings"""
+    def check(value: Object, context: Dict[str, Any]) -> BooleanObj:
+        if isinstance(value, String):
+            length = len(value.value)
+            return BooleanObj(min_len <= length <= max_len)
+        return BooleanObj(False)
+    return check
+
+
+def contains_constraint(substring: str):
+    """Create a contains constraint for strings"""
+    def check(value: Object, context: Dict[str, Any]) -> BooleanObj:
+        if isinstance(value, String):
+            return BooleanObj(substring in value.value)
+        return BooleanObj(False)
+    return check
+
+
+def range_constraint(min_val: int = float('-inf'), max_val: int = float('inf')):
+    """Create a range constraint for numbers"""
+    def check(value: Object, context: Dict[str, Any]) -> BooleanObj:
+        if isinstance(value, Integer):
+            return BooleanObj(min_val <= value.value <= max_val)
+        return BooleanObj(False)
+    return check
+
+
+def equality_constraint(expected_value: Any):
+    """Create an equality constraint"""
+    def check(value: Object, context: Dict[str, Any]) -> BooleanObj:
+        if hasattr(value, 'value'):
+            return BooleanObj(value.value == expected_value)
+        return BooleanObj(value == expected_value)
+    return check
+
+
+def caller_constraint(allowed_callers: List[str]):
+    """Create a constraint checking TX.caller"""
+    def check(value: Object, context: Dict[str, Any]) -> BooleanObj:
+        caller = context.get('TX', {}).get('caller', '')
+        if isinstance(caller, String):
+            caller = caller.value
+        return BooleanObj(caller in allowed_callers)
+    return check
+
+
+# ===============================================
+# UTILITY FUNCTIONS
+# ===============================================
+
+def create_policy(target_name: str) -> PolicyBuilder:
+    """Create a new policy builder"""
+    return PolicyBuilder(target_name)
+
+
+def protect_target(target_name: str, policy: ProtectionPolicy, original_fn: Callable):
+    """Register a target with protection policy"""
+    registry = get_policy_registry()
+    registry.protect_function(target_name, original_fn, policy)
+
+
+def check_policy(target_name: str, context: Dict[str, Any]) -> tuple[bool, List[str]]:
+    """Check if context passes policy for target"""
+    registry = get_policy_registry()
+    policy = registry.get_policy(target_name)
+    
+    if not policy:
+        return True, []  # No policy means no restrictions
+    
+    return policy.evaluate(context)
+
+
+def execute_protected(target_name: str, context: Dict[str, Any]):
+    """Execute a protected function"""
+    registry = get_policy_registry()
+    return registry.execute_protected(target_name, context)
+
+
+def get_audit_summary() -> Dict[str, Any]:
+    """Get audit summary for all policies"""
+    registry = get_policy_registry()
+    return registry.get_audit_summary()

package/src/zexus/profiler/__init__.py

@@ -0,0 +1,5 @@
+"""Zexus Performance Profiler."""
+
+from .profiler import Profiler, ProfileReport
+
+__all__ = ['Profiler', 'ProfileReport']

package/src/zexus/profiler/profiler.py

@@ -0,0 +1,233 @@
+"""Performance profiler for Zexus code."""
+
+import time
+import tracemalloc
+from typing import Dict, List, Any
+from dataclasses import dataclass, field
+from collections import defaultdict
+
+
+@dataclass
+class FunctionProfile:
+    """Profile data for a function."""
+    name: str
+    calls: int = 0
+    total_time: float = 0.0
+    self_time: float = 0.0
+    memory_allocated: int = 0
+    memory_peak: int = 0
+
+
+@dataclass
+class ProfileReport:
+    """Complete profiling report."""
+    total_time: float
+    total_calls: int
+    memory_peak: int
+    functions: Dict[str, FunctionProfile] = field(default_factory=dict)
+    hotspots: List[FunctionProfile] = field(default_factory=list)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert report to dictionary."""
+        return {
+            'total_time': self.total_time,
+            'total_calls': self.total_calls,
+            'memory_peak': self.memory_peak,
+            'functions': {
+                name: {
+                    'calls': prof.calls,
+                    'total_time': prof.total_time,
+                    'self_time': prof.self_time,
+                    'memory_allocated': prof.memory_allocated,
+                    'memory_peak': prof.memory_peak
+                }
+                for name, prof in self.functions.items()
+            },
+            'hotspots': [
+                {
+                    'name': prof.name,
+                    'calls': prof.calls,
+                    'total_time': prof.total_time,
+                    'self_time': prof.self_time
+                }
+                for prof in self.hotspots
+            ]
+        }
+
+
+class Profiler:
+    """Performance profiler for Zexus code execution."""
+
+    def __init__(self):
+        self.enabled = False
+        self.start_time = 0.0
+        self.functions = {}
+        self.call_stack = []
+        self.memory_enabled = False
+        
+    def start(self, enable_memory: bool = True):
+        """Start profiling."""
+        self.enabled = True
+        self.memory_enabled = enable_memory
+        self.start_time = time.time()
+        self.functions = {}
+        self.call_stack = []
+        
+        if enable_memory:
+            tracemalloc.start()
+    
+    def stop(self) -> ProfileReport:
+        """Stop profiling and generate report."""
+        self.enabled = False
+        total_time = time.time() - self.start_time
+        
+        memory_peak = 0
+        if self.memory_enabled:
+            _, peak = tracemalloc.get_traced_memory()
+            memory_peak = peak
+            tracemalloc.stop()
+        
+        # Calculate total calls
+        total_calls = sum(prof.calls for prof in self.functions.values())
+        
+        # Identify hotspots (functions taking most time)
+        hotspots = sorted(
+            self.functions.values(),
+            key=lambda p: p.total_time,
+            reverse=True
+        )[:10]  # Top 10 hotspots
+        
+        return ProfileReport(
+            total_time=total_time,
+            total_calls=total_calls,
+            memory_peak=memory_peak,
+            functions=self.functions,
+            hotspots=hotspots
+        )
+    
+    def enter_function(self, name: str):
+        """Record entering a function."""
+        if not self.enabled:
+            return
+        
+        if name not in self.functions:
+            self.functions[name] = FunctionProfile(name=name)
+        
+        profile = self.functions[name]
+        profile.calls += 1
+        
+        # Record memory if enabled
+        if self.memory_enabled:
+            current, _ = tracemalloc.get_traced_memory()
+            profile.memory_allocated = current
+        
+        # Push onto call stack
+        self.call_stack.append({
+            'name': name,
+            'start_time': time.time(),
+            'start_memory': profile.memory_allocated if self.memory_enabled else 0
+        })
+    
+    def exit_function(self, name: str):
+        """Record exiting a function."""
+        if not self.enabled or not self.call_stack:
+            return
+        
+        # Pop from call stack
+        call_info = self.call_stack.pop()
+        
+        if call_info['name'] != name:
+            # Stack mismatch - log warning
+            import logging
+            logger = logging.getLogger(__name__)
+            logger.warning(f"Profile stack mismatch. Expected {call_info['name']}, got {name}")
+            return
+        
+        # Calculate elapsed time
+        elapsed = time.time() - call_info['start_time']
+        
+        profile = self.functions[name]
+        profile.total_time += elapsed
+        profile.self_time += elapsed
+        
+        # Update memory if enabled
+        if self.memory_enabled:
+            current, peak = tracemalloc.get_traced_memory()
+            profile.memory_peak = max(profile.memory_peak, peak)
+        
+        # Subtract time from parent if exists
+        if self.call_stack:
+            parent_name = self.call_stack[-1]['name']
+            if parent_name in self.functions:
+                self.functions[parent_name].self_time -= elapsed
+    
+    def print_report(self, report: ProfileReport, top_n: int = 20):
+        """Print profiling report."""
+        print("\n" + "="*80)
+        print("ZEXUS PERFORMANCE PROFILE REPORT")
+        print("="*80)
+        print(f"\nTotal Time: {report.total_time:.4f} seconds")
+        print(f"Total Calls: {report.total_calls}")
+        print(f"Peak Memory: {report.memory_peak / 1024 / 1024:.2f} MB")
+        
+        print(f"\n{'Function':<40} {'Calls':>10} {'Total Time':>15} {'Self Time':>15} {'Avg Time':>15}")
+        print("-"*100)
+        
+        # Sort by total time
+        sorted_functions = sorted(
+            report.functions.values(),
+            key=lambda p: p.total_time,
+            reverse=True
+        )
+        
+        for prof in sorted_functions[:top_n]:
+            avg_time = prof.total_time / prof.calls if prof.calls > 0 else 0
+            print(f"{prof.name:<40} {prof.calls:>10} {prof.total_time:>15.4f}s {prof.self_time:>15.4f}s {avg_time:>15.6f}s")
+        
+        print("\n" + "="*80)
+        print("TOP HOTSPOTS (by total time)")
+        print("="*80)
+        
+        for i, prof in enumerate(report.hotspots[:10], 1):
+            pct = (prof.total_time / report.total_time * 100) if report.total_time > 0 else 0
+            print(f"{i}. {prof.name}: {prof.total_time:.4f}s ({pct:.1f}%)")
+        
+        print("="*80 + "\n")
+
+
+# Global profiler instance
+_profiler = Profiler()
+
+
+def start_profiling(enable_memory: bool = True):
+    """Start global profiler."""
+    _profiler.start(enable_memory)
+
+
+def stop_profiling() -> ProfileReport:
+    """Stop global profiler and get report."""
+    return _profiler.stop()
+
+
+def print_profile():
+    """Print current profile."""
+    report = stop_profiling()
+    _profiler.print_report(report)
+    return report
+
+
+def profile_function(func):
+    """Decorator to profile a function."""
+    def wrapper(*args, **kwargs):
+        _profiler.enter_function(func.__name__)
+        try:
+            result = func(*args, **kwargs)
+            return result
+        finally:
+            _profiler.exit_function(func.__name__)
+    return wrapper
+
+
+def get_profiler() -> Profiler:
+    """Get global profiler instance."""
+    return _profiler