zexus 1.8.2 → 1.8.3

package/src/zexus/evaluator/statements.py

@@ -1228,11 +1228,45 @@ class StatementEvaluatorMixin:
         if is_error(iterable): 
             return iterable
         
+        # R-007 fix: Support Map iteration in for-each loops
+        if isinstance(iterable, Map):
+            result = NULL
+            for key, val in iterable.pairs.items():
+                try:
+                    self.resource_limiter.check_iterations()
+                except Exception as e:
+                    from ..evaluator.resource_limiter import ResourceError, TimeoutError
+                    if isinstance(e, (ResourceError, TimeoutError)):
+                        return EvaluationError(str(e))
+                    raise
+                
+                if node.index:
+                    # for each key, val in map
+                    key_obj = String(key) if isinstance(key, str) else key
+                    env.set(node.index.value, key_obj)
+                    env.set(node.item.value, val)
+                else:
+                    # for each key in map (single variable gets the key)
+                    key_obj = String(key) if isinstance(key, str) else key
+                    env.set(node.item.value, key_obj)
+                
+                result = self.eval_node(node.body, env, stack_trace)
+                if isinstance(result, ReturnValue):
+                    return result
+                if isinstance(result, BreakException):
+                    return NULL
+                if isinstance(result, ContinueException):
+                    result = NULL
+                    continue
+                if isinstance(result, EvaluationError):
+                    return result
+            return result
+        
         if not isinstance(iterable, List):
-            return EvaluationError("ForEach expects List")
+            return EvaluationError("ForEach expects List or Map")
         
         result = NULL
-        for item in iterable.elements:
+        for idx, item in enumerate(iterable.elements):
             # Resource limit check (Security Fix #7)
             try:
                 self.resource_limiter.check_iterations()
@@ -1243,6 +1277,9 @@ class StatementEvaluatorMixin:
                     return EvaluationError(str(e))
                 raise  # Re-raise if not a resource error
             
+            # R-006 fix: Support indexed for-each (for each i, item in list)
+            if node.index:
+                env.set(node.index.value, Integer(idx))
             env.set(node.item.value, item)
             result = self.eval_node(node.body, env, stack_trace)
             if isinstance(result, ReturnValue):
@@ -1881,7 +1918,10 @@ class StatementEvaluatorMixin:
         
         for nm in names:
             val = env.get(nm)
-            if not val: 
+            # R-011 fix: Use ``is None`` instead of ``not val`` so that valid
+            # objects which might be falsy (empty lists, NULL placeholders from
+            # pre-registration, etc.) are not incorrectly rejected.
+            if val is None: 
                 return EvaluationError(f"Cannot export undefined: {nm}")
             
             # If inside a module, add to module's exports list
@@ -2302,7 +2342,7 @@ class StatementEvaluatorMixin:
                 
                 if isinstance(prop, dict):
                     # For dict format, default_value is in the dict
-                    if 'default_value' in prop:
+                    if 'default_value' in prop and prop['default_value'] is not None:
                         def_val = self.eval_node(prop['default_value'], env, stack_trace)
                         if is_error(def_val): 
                             return def_val

package/src/zexus/kernel/__init__.py

@@ -0,0 +1,34 @@
+"""
+Zexus Kernel — Extension layer for the interpreter and VM.
+
+The kernel sits *alongside* the existing evaluator and VM.  It does NOT
+replace them.  Instead it provides:
+
+* **DomainRegistry** — a place where feature domains (blockchain, web,
+  system, …) register their capabilities so the interpreter can discover
+  them at runtime.
+* **ZIR** — a formal opcode catalogue that documents (and validates) the
+  bytecode the VM already uses, plus domain-specific opcode ranges.
+* **Hooks** — optional integration points the evaluator/VM can call into
+  (e.g. ``kernel.resolve_opcode()``, ``kernel.check_security()``).
+
+The kernel is entirely opt-in.  Everything works without it — but with
+it, third-party domains can plug into the Zexus runtime cleanly.
+
+Quick start
+-----------
+>>> from zexus.kernel import get_kernel
+>>> k = get_kernel()
+>>> k.registry.list_domains()         # see what's loaded
+>>> k.registry.get_domain("blockchain")  # query a specific domain
+"""
+
+from .registry import DomainRegistry, get_registry
+from .hooks import Kernel, get_kernel
+
+__all__ = [
+    "DomainRegistry",
+    "get_registry",
+    "Kernel",
+    "get_kernel",
+]

package/src/zexus/kernel/hooks.py

@@ -0,0 +1,276 @@
+"""
+Kernel Hooks — Integration points between the kernel and the interpreter.
+
+The :class:`Kernel` object is the single entry-point that the evaluator,
+VM, or CLI can *optionally* use to tap into the domain/extension system.
+
+It does NOT wrap or replace any existing class.  It provides *additional*
+services that sit alongside the evaluator and VM:
+
+* Resolve domain-specific opcodes to handler functions.
+* Compose security policies across multiple domains.
+* Broadcast lifecycle events (program start, module load, …).
+* Provide a unified introspection API for tooling (LSP, debugger).
+
+Example — wiring the kernel into an existing run:
+
+    from zexus.evaluator import Evaluator
+    from zexus.kernel import get_kernel
+
+    kernel = get_kernel()
+    kernel.boot()              # auto-discovers built-in domains
+
+    evaluator = Evaluator()
+    # The evaluator still works exactly as before.
+    # But now you can also ask the kernel:
+    info = kernel.registry.get_domain("blockchain")
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any, Callable, Dict, List, Optional
+
+from .registry import DomainRegistry, DomainDescriptor, get_registry
+
+
+# ---------------------------------------------------------------------------
+# Lifecycle events
+# ---------------------------------------------------------------------------
+
+class KernelEvent:
+    """Simple event descriptor."""
+
+    __slots__ = ("name", "timestamp", "data")
+
+    def __init__(self, name: str, data: Optional[Dict[str, Any]] = None) -> None:
+        self.name = name
+        self.timestamp = time.time()
+        self.data = data or {}
+
+    def __repr__(self) -> str:
+        return f"KernelEvent({self.name!r})"
+
+
+# ---------------------------------------------------------------------------
+# Kernel
+# ---------------------------------------------------------------------------
+
+class Kernel:
+    """Extension layer that sits alongside the interpreter and VM.
+
+    The kernel is **purely additive** — the interpreter works with or
+    without it.  When present it provides domain discovery, opcode
+    resolution, security composition, and lifecycle events.
+    """
+
+    def __init__(self, registry: Optional[DomainRegistry] = None) -> None:
+        self.registry: DomainRegistry = registry or get_registry()
+        self._booted = False
+        self._event_listeners: Dict[str, List[Callable[[KernelEvent], None]]] = {}
+        self._opcode_handlers: Dict[int, Callable] = {}
+        self._middleware: List[Callable] = []
+
+    # -- Boot ---------------------------------------------------------------
+
+    def boot(self) -> "Kernel":
+        """Discover and register all built-in domains.
+
+        Safe to call multiple times — subsequent calls are no-ops.
+        Returns *self* for chaining.
+        """
+        if self._booted:
+            return self
+
+        self._register_builtin_domains()
+        self._booted = True
+        self._emit("kernel.booted", {"domains": list(self.registry.domain_names)})
+        return self
+
+    @property
+    def is_booted(self) -> bool:
+        return self._booted
+
+    # -- Opcode resolution --------------------------------------------------
+
+    def register_opcode_handler(self, opcode: int, handler: Callable) -> None:
+        """Map a domain opcode to a Python callable.
+
+        This lets domain authors provide executable implementations for
+        their custom opcodes.  The VM can query these at dispatch time.
+        """
+        self._opcode_handlers[opcode] = handler
+
+    def get_opcode_handler(self, opcode: int) -> Optional[Callable]:
+        """Return the handler for *opcode*, or ``None``."""
+        return self._opcode_handlers.get(opcode)
+
+    def resolve_opcode_domain(self, opcode: int) -> Optional[str]:
+        """Return the domain name that owns *opcode*."""
+        return self.registry.resolve_opcode(opcode)
+
+    # -- Security composition -----------------------------------------------
+
+    def check_security(self, operation: str, context: Optional[Dict[str, Any]] = None) -> bool:
+        """Ask every registered domain's security policy to approve *operation*.
+
+        Returns ``True`` only if **all** domains approve (or have no policy).
+        """
+        context = context or {}
+        for desc in self.registry.list_domains():
+            policy = desc.security_policy
+            if policy is not None and hasattr(policy, "check"):
+                try:
+                    if not policy.check(operation, context):
+                        return False
+                except Exception:
+                    return False
+        return True
+
+    # -- Middleware ----------------------------------------------------------
+
+    def use(self, middleware_fn: Callable) -> None:
+        """Register a middleware function.
+
+        Middleware is called in order for certain pipeline stages
+        (compile, execute) and can inspect or transform the data.
+        """
+        self._middleware.append(middleware_fn)
+
+    def run_middleware(self, stage: str, data: Any) -> Any:
+        """Run all middleware for *stage*, threading *data* through."""
+        for mw in self._middleware:
+            try:
+                result = mw(stage, data)
+                if result is not None:
+                    data = result
+            except Exception:
+                pass
+        return data
+
+    # -- Events -------------------------------------------------------------
+
+    def on(self, event_name: str, callback: Callable[[KernelEvent], None]) -> None:
+        """Subscribe to a kernel lifecycle event."""
+        self._event_listeners.setdefault(event_name, []).append(callback)
+
+    def _emit(self, event_name: str, data: Optional[Dict[str, Any]] = None) -> None:
+        event = KernelEvent(event_name, data)
+        for cb in self._event_listeners.get(event_name, []):
+            try:
+                cb(event)
+            except Exception:
+                pass
+        # Also fire wildcard listeners
+        for cb in self._event_listeners.get("*", []):
+            try:
+                cb(event)
+            except Exception:
+                pass
+
+    # -- Introspection ------------------------------------------------------
+
+    def status(self) -> Dict[str, Any]:
+        """Return a snapshot of the kernel state (useful for tooling/debug)."""
+        domains = self.registry.list_domains()
+        return {
+            "booted": self._booted,
+            "domain_count": len(domains),
+            "domains": {d.name: d.version for d in domains},
+            "opcode_handlers": len(self._opcode_handlers),
+            "middleware": len(self._middleware),
+            "event_subscriptions": {
+                k: len(v) for k, v in self._event_listeners.items()
+            },
+        }
+
+    # -- Built-in domain registration (private) -----------------------------
+
+    def _register_builtin_domains(self) -> None:
+        """Register the built-in domains that ship with the interpreter.
+
+        Each registration is idempotent — already-registered domains are
+        silently skipped.
+        """
+        builtins = [
+            {
+                "name": "blockchain",
+                "version": "1.8.3",
+                "description": "Ledger, smart-contract execution, crypto, gas metering",
+                "opcodes": {
+                    0x1000: "HASH_BLOCK",
+                    0x1001: "VERIFY_SIGNATURE",
+                    0x1002: "STATE_READ",
+                    0x1003: "STATE_WRITE",
+                    0x1004: "GAS_CHARGE",
+                    0x1005: "MERKLE_ROOT",
+                    0x1006: "CREATE_TX",
+                    0x1007: "EMIT_EVENT",
+                    0x1008: "REQUIRE",
+                    0x1009: "BALANCE_OF",
+                    0x100A: "CREATE_CHAIN",
+                    0x100B: "ADD_BLOCK",
+                },
+            },
+            {
+                "name": "web",
+                "version": "1.8.3",
+                "description": "HTTP server/client, WebSocket, middleware",
+                "opcodes": {
+                    0x1100: "HTTP_ROUTE",
+                    0x1101: "HTTP_METHOD",
+                    0x1102: "HTTP_RESPONSE",
+                    0x1103: "WS_CONNECT",
+                    0x1104: "WS_SEND",
+                    0x1105: "WS_RECEIVE",
+                },
+            },
+            {
+                "name": "system",
+                "version": "1.8.3",
+                "description": "File I/O, process management, environment variables",
+                "opcodes": {
+                    0x1200: "FS_READ",
+                    0x1201: "FS_WRITE",
+                    0x1202: "FS_DELETE",
+                    0x1203: "FS_LIST_DIR",
+                    0x1204: "PROCESS_SPAWN",
+                    0x1205: "ENV_GET",
+                    0x1206: "ENV_SET",
+                },
+            },
+            {
+                "name": "ui",
+                "version": "1.8.3",
+                "description": "Terminal graphics, web rendering, native widgets",
+                "opcodes": {},
+            },
+        ]
+
+        for domain in builtins:
+            if self.registry.get_domain(domain["name"]) is None:
+                self.registry.register_domain(**domain)
+
+    def __repr__(self) -> str:
+        state = "booted" if self._booted else "idle"
+        n = len(self.registry.list_domains())
+        return f"Kernel({state}, {n} domains)"
+
+
+# ---------------------------------------------------------------------------
+# Singleton
+# ---------------------------------------------------------------------------
+
+_global_kernel: Optional[Kernel] = None
+_kernel_lock = threading.Lock()
+
+
+def get_kernel() -> Kernel:
+    """Return the process-wide :class:`Kernel` singleton."""
+    global _global_kernel
+    if _global_kernel is None:
+        with _kernel_lock:
+            if _global_kernel is None:
+                _global_kernel = Kernel()
+    return _global_kernel

package/src/zexus/kernel/registry.py

@@ -0,0 +1,203 @@
+"""
+Domain Registry — Central registration point for Zexus domains.
+
+Each domain (blockchain, web, ui, system, …) registers itself here at
+import-time.  The kernel uses the registry to resolve domain-specific
+opcodes, security policies, and runtime services without directly
+importing any domain package.
+
+Usage
+-----
+>>> from zexus.kernel import get_registry
+>>> reg = get_registry()
+>>> reg.register_domain(
+...     name="blockchain",
+...     version="1.0.0",
+...     opcodes={0x1000: "HASH_BLOCK", 0x1001: "VERIFY_SIG"},
+... )
+>>> reg.get_domain("blockchain").version
+'1.0.0'
+"""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Set
+
+
+# ---------------------------------------------------------------------------
+# Domain descriptor
+# ---------------------------------------------------------------------------
+
+@dataclass
+class DomainDescriptor:
+    """Immutable description of a registered domain."""
+
+    name: str
+    version: str = "0.0.0"
+    opcodes: Dict[int, str] = field(default_factory=dict)
+    security_policy: Optional[Any] = None
+    runtime: Optional[Any] = None
+    validate_zir: Optional[Callable] = None
+    # Additional metadata
+    description: str = ""
+    dependencies: List[str] = field(default_factory=list)
+
+    def __repr__(self) -> str:
+        return f"DomainDescriptor(name={self.name!r}, version={self.version!r}, opcodes={len(self.opcodes)})"
+
+
+# ---------------------------------------------------------------------------
+# Domain Registry
+# ---------------------------------------------------------------------------
+
+class DomainRegistry:
+    """Thread-safe singleton registry for Zexus domains.
+
+    The registry enforces two key constraints:
+    1. Domain names are unique.
+    2. Opcode ranges must not overlap between domains.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._domains: Dict[str, DomainDescriptor] = {}
+        self._opcode_owners: Dict[int, str] = {}  # opcode → domain name
+        self._listeners: List[Callable[[DomainDescriptor], None]] = []
+
+    # -- Registration -------------------------------------------------------
+
+    def register_domain(
+        self,
+        name: str,
+        *,
+        version: str = "0.0.0",
+        opcodes: Optional[Dict[int, str]] = None,
+        security_policy: Optional[Any] = None,
+        runtime: Optional[Any] = None,
+        validate_zir: Optional[Callable] = None,
+        description: str = "",
+        dependencies: Optional[List[str]] = None,
+    ) -> DomainDescriptor:
+        """Register a new domain.
+
+        Raises
+        ------
+        ValueError
+            If *name* is already registered or any opcode collides with
+            another domain's opcode range.
+        """
+        opcodes = opcodes or {}
+        dependencies = dependencies or []
+
+        with self._lock:
+            if name in self._domains:
+                raise ValueError(f"Domain {name!r} is already registered")
+
+            # Check for opcode collisions
+            for op, op_name in opcodes.items():
+                if op in self._opcode_owners:
+                    owner = self._opcode_owners[op]
+                    raise ValueError(
+                        f"Opcode 0x{op:04X} ({op_name}) collides with "
+                        f"domain {owner!r}"
+                    )
+
+            desc = DomainDescriptor(
+                name=name,
+                version=version,
+                opcodes=opcodes,
+                security_policy=security_policy,
+                runtime=runtime,
+                validate_zir=validate_zir,
+                description=description,
+                dependencies=dependencies,
+            )
+
+            self._domains[name] = desc
+            for op in opcodes:
+                self._opcode_owners[op] = name
+
+            # Notify listeners
+            for listener in self._listeners:
+                try:
+                    listener(desc)
+                except Exception:
+                    pass
+
+        return desc
+
+    def unregister_domain(self, name: str) -> None:
+        """Remove a previously registered domain."""
+        with self._lock:
+            desc = self._domains.pop(name, None)
+            if desc:
+                for op in desc.opcodes:
+                    self._opcode_owners.pop(op, None)
+
+    # -- Query --------------------------------------------------------------
+
+    def get_domain(self, name: str) -> Optional[DomainDescriptor]:
+        """Return the descriptor for *name*, or ``None``."""
+        return self._domains.get(name)
+
+    def list_domains(self) -> List[DomainDescriptor]:
+        """Return all registered domains (snapshot)."""
+        with self._lock:
+            return list(self._domains.values())
+
+    @property
+    def domain_names(self) -> Set[str]:
+        """Set of registered domain names."""
+        return set(self._domains.keys())
+
+    def resolve_opcode(self, opcode: int) -> Optional[str]:
+        """Return the domain name that owns *opcode*, or ``None``."""
+        return self._opcode_owners.get(opcode)
+
+    # -- Listeners ----------------------------------------------------------
+
+    def on_domain_registered(self, callback: Callable[[DomainDescriptor], None]) -> None:
+        """Register a callback that fires whenever a new domain is registered."""
+        self._listeners.append(callback)
+
+    # -- Utilities ----------------------------------------------------------
+
+    def check_dependencies(self, name: str) -> List[str]:
+        """Return list of missing dependencies for domain *name*.
+
+        Returns an empty list if all dependencies are satisfied.
+        """
+        desc = self._domains.get(name)
+        if desc is None:
+            return [name]
+        return [dep for dep in desc.dependencies if dep not in self._domains]
+
+    def reset(self) -> None:
+        """Remove all registered domains (useful for testing)."""
+        with self._lock:
+            self._domains.clear()
+            self._opcode_owners.clear()
+
+    def __repr__(self) -> str:
+        names = ", ".join(sorted(self._domains.keys()))
+        return f"DomainRegistry(domains=[{names}])"
+
+
+# ---------------------------------------------------------------------------
+# Singleton
+# ---------------------------------------------------------------------------
+
+_global_registry: Optional[DomainRegistry] = None
+_registry_lock = threading.Lock()
+
+
+def get_registry() -> DomainRegistry:
+    """Return the process-wide :class:`DomainRegistry` singleton."""
+    global _global_registry
+    if _global_registry is None:
+        with _registry_lock:
+            if _global_registry is None:
+                _global_registry = DomainRegistry()
+    return _global_registry