tactus 0.31.2__py3-none-any.whl

tactus/utils/safe_libraries.py

@@ -0,0 +1,234 @@
+"""
+Safe Lua standard library implementations with determinism warnings.
+
+Provides wrapped versions of math.random, os.time, os.date, os.clock that
+warn when used outside checkpoint boundaries to prevent replay bugs in
+Tactus's checkpoint-and-replay execution system.
+"""
+
+import warnings
+import time
+import random
+import math
+from datetime import datetime
+from typing import Callable, Any, Optional
+from functools import wraps
+
+
+class DeterminismWarning(UserWarning):
+    """Warning issued when non-deterministic function called outside checkpoint."""
+
+    pass
+
+
+class NonDeterministicError(Exception):
+    """Raised in strict mode when non-deterministic function called outside checkpoint."""
+
+    pass
+
+
+def warn_if_unsafe(operation_name: str, get_context: Callable[[], Optional[Any]]):
+    """
+    Decorator that warns when non-deterministic operation used outside checkpoint.
+
+    Args:
+        operation_name: Human-readable name of operation (e.g., "math.random()")
+        get_context: Callback to retrieve current ExecutionContext
+
+    Returns:
+        Decorated function that checks checkpoint scope
+    """
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # Get context via callback
+            context = get_context()
+
+            # If no context, can't enforce (allow silently for REPL/testing)
+            if context is None:
+                return func(*args, **kwargs)
+
+            # Check if inside checkpoint
+            inside_checkpoint = getattr(context, "_inside_checkpoint", False)
+
+            if not inside_checkpoint:
+                message = (
+                    f"\n{'=' * 70}\n"
+                    f"DETERMINISM WARNING: {operation_name} called outside checkpoint\n"
+                    f"{'=' * 70}\n\n"
+                    f"Non-deterministic operations must be wrapped in checkpoints "
+                    f"for durability.\n\n"
+                    f"To fix, wrap your code in a checkpoint:\n\n"
+                    f"  -- Lua example:\n"
+                    f"  local random_value = Step.checkpoint(function()\n"
+                    f"    return {operation_name}\n"
+                    f"  end)\n\n"
+                    f"Or use checkpoint() directly:\n\n"
+                    f"  local result = checkpoint(function()\n"
+                    f"    -- Your non-deterministic code here\n"
+                    f"    return {operation_name}\n"
+                    f"  end)\n\n"
+                    f"Why: Tactus uses checkpointing for durable execution. "
+                    f"Operations outside\n"
+                    f"checkpoints may produce different results on replay, "
+                    f"breaking determinism.\n"
+                    f"\n{'=' * 70}\n"
+                )
+
+                # Check strict mode
+                strict_mode = getattr(context, "strict_determinism", False)
+
+                if strict_mode:
+                    raise NonDeterministicError(message)
+                else:
+                    # Use stacklevel=4 to point to Lua code, not wrapper
+                    warnings.warn(message, DeterminismWarning, stacklevel=4)
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def create_safe_math_library(get_context: Callable, strict_mode: bool = False):
+    """
+    Create safe math library with warnings for random functions.
+
+    Args:
+        get_context: Callback returning current ExecutionContext
+        strict_mode: If True, raise errors instead of warnings (not currently used - context has it)
+
+    Returns:
+        Dict with safe math functions (keys are strings for Lua table)
+    """
+
+    @warn_if_unsafe("math.random()", get_context)
+    def safe_random(m=None, n=None):
+        """
+        Safe math.random() with checkpoint warning.
+
+        Lua's math.random() has three forms:
+        - math.random(): returns float in [0, 1)
+        - math.random(n): returns integer in [1, n]
+        - math.random(m, n): returns integer in [m, n]
+        """
+        if m is None and n is None:
+            # No arguments: return float [0, 1)
+            return random.random()
+        elif n is None:
+            # One argument: return integer [1, m]
+            return random.randint(1, int(m))
+        else:
+            # Two arguments: return integer [m, n]
+            return random.randint(int(m), int(n))
+
+    @warn_if_unsafe("math.randomseed()", get_context)
+    def safe_randomseed(seed):
+        """Safe math.randomseed() with checkpoint warning."""
+        random.seed(int(seed))
+        return None
+
+    # Standard math functions (deterministic - pass through)
+    return {
+        # Deterministic functions - safe to use anywhere
+        "abs": abs,
+        "acos": math.acos,
+        "asin": math.asin,
+        "atan": math.atan,
+        "atan2": math.atan2,
+        "ceil": math.ceil,
+        "cos": math.cos,
+        "cosh": math.cosh,
+        "deg": math.degrees,
+        "exp": math.exp,
+        "floor": math.floor,
+        "fmod": math.fmod,
+        "huge": float("inf"),
+        "log": math.log,
+        "log10": math.log10,
+        "max": max,
+        "min": min,
+        "modf": math.modf,
+        "pi": math.pi,
+        "pow": pow,
+        "rad": math.radians,
+        "sin": math.sin,
+        "sinh": math.sinh,
+        "sqrt": math.sqrt,
+        "tan": math.tan,
+        "tanh": math.tanh,
+        # Non-deterministic functions (wrapped with warnings)
+        "random": safe_random,
+        "randomseed": safe_randomseed,
+    }
+
+
+def create_safe_os_library(get_context: Callable, strict_mode: bool = False):
+    """
+    Create safe os library with warnings for non-deterministic functions.
+
+    Args:
+        get_context: Callback returning current ExecutionContext
+        strict_mode: If True, raise errors instead of warnings (not currently used - context has it)
+
+    Returns:
+        Dict with safe os functions
+    """
+
+    @warn_if_unsafe("os.time()", get_context)
+    def safe_time(date_table=None):
+        """Safe os.time() with checkpoint warning."""
+        if date_table is None:
+            return int(time.time())
+        else:
+            # Lua date table format: {year, month, day, hour, min, sec}
+            # For simplicity, just return current time
+            # Full implementation would parse the table
+            return int(time.time())
+
+    @warn_if_unsafe("os.date()", get_context)
+    def safe_date(format_str=None):
+        """Safe os.date() with checkpoint warning."""
+        now = datetime.utcnow()
+
+        if format_str is None:
+            # Default format like Lua's os.date()
+            return now.strftime("%a %b %d %H:%M:%S %Y")
+        elif format_str == "%Y-%m-%dT%H:%M:%SZ":
+            # ISO 8601 format
+            return now.strftime("%Y-%m-%dT%H:%M:%SZ")
+        else:
+            # Support Python strftime formats
+            try:
+                return now.strftime(format_str)
+            except Exception:
+                return now.strftime("%a %b %d %H:%M:%S %Y")
+
+    @warn_if_unsafe("os.clock()", get_context)
+    def safe_clock():
+        """Safe os.clock() with checkpoint warning."""
+        return time.process_time()
+
+    @warn_if_unsafe("os.getenv()", get_context)
+    def safe_getenv(varname):
+        """Safe os.getenv() with checkpoint warning - environment variables can change."""
+        import os
+
+        return os.getenv(varname)
+
+    @warn_if_unsafe("os.tmpname()", get_context)
+    def safe_tmpname():
+        """Safe os.tmpname() with checkpoint warning - generates unique temporary filenames."""
+        import tempfile
+
+        return tempfile.mktemp()
+
+    return {
+        "time": safe_time,
+        "date": safe_date,
+        "clock": safe_clock,
+        "getenv": safe_getenv,
+        "tmpname": safe_tmpname,
+    }

tactus/validation/LuaLexerBase.py

@@ -0,0 +1,66 @@
+from typing import TextIO
+from antlr4 import *
+from antlr4.Token import CommonToken
+import sys
+from typing import TextIO
+
+
+class LuaLexerBase(Lexer):
+    def __init__(self, input: InputStream, output: TextIO = sys.stdout):
+        super().__init__(input, output)
+        self.start_line = 0
+        self.start_col = 0
+
+    def HandleComment(self):
+        self.start_line = self.line
+        self.start_col = self.column - 2
+        cs = self._input
+
+        if cs.LA(1) == 91:  # '['
+            sep = self.skip_sep(cs)
+            if sep >= 2:
+                self.read_long_string(cs, sep)
+                return
+
+        while cs.LA(1) != 10 and cs.LA(1) != -1:  # '\n'
+            self._interp.consume(cs)
+
+    def read_long_string(self, cs: InputStream, sep: int):
+        done = False
+        self._interp.consume(cs)
+
+        while not done:
+            c = cs.LA(1)
+            if c == -1:
+                done = True
+            elif c == 93:  # ']'
+                if self.skip_sep(cs) == sep:
+                    self._interp.consume(cs)
+                    done = True
+            else:
+                if cs.LA(1) == -1:
+                    done = True
+                else:
+                    self._interp.consume(cs)
+
+    def skip_sep(self, cs: InputStream):
+        count = 0
+        s = cs.LA(1)
+        self._interp.consume(cs)
+
+        while cs.LA(1) == 61:  # '='
+            self._interp.consume(cs)
+            count += 1
+
+        if cs.LA(1) == s:
+            count += 2
+        elif count == 0:
+            count = 1
+        else:
+            count = 0
+
+        return count
+
+    def IsLine1Col0(self):
+        cs = self._input
+        return cs.index == 1

tactus/validation/LuaParserBase.py

@@ -0,0 +1,23 @@
+import sys
+from antlr4 import *
+
+if sys.version_info[1] > 5:
+    from typing import TextIO
+else:
+    from typing.io import TextIO
+
+
+class LuaParserBase(Parser):
+    debug = False
+
+    def __init__(self, input: TokenStream, output: TextIO = sys.stdout):
+        super().__init__(input, output)
+
+    def IsFunctionCall(self) -> bool:
+        la = self._input.LT(1)
+        if la.type != self.NAME:
+            return False
+        la = self._input.LT(2)
+        if la.type == self.OP:
+            return False
+        return True

tactus/validation/README.md

@@ -0,0 +1,224 @@
+# Tactus DSL Validation
+
+This module provides ANTLR-based validation for `.tac` files.
+
+## Architecture
+
+The validation system uses a three-phase approach:
+
+```
+.tac file
+      ↓
+Phase 1: ANTLR Parsing (Lua 5.4 grammar)
+      ↓
+   Parse Tree
+      ↓
+Phase 2: Semantic Visitor (DSL pattern recognition)
+      ↓
+   Registry with Declarations
+      ↓
+Phase 3: Registry Validation (cross-reference checking)
+      ↓
+   ValidationResult
+```
+
+### Key Components
+
+1. **ANTLR Grammar** (`grammar/LuaLexer.g4`, `grammar/LuaParser.g4`)
+   - Standard Lua 5.4 grammar from antlr/grammars-v4
+   - Unmodified - semantic layer added on top
+   - Same grammar generates both Python and TypeScript parsers
+
+2. **Generated Parsers** (`generated/`)
+   - `LuaLexer.py` / `LuaParser.py` - Python parser
+   - `LuaLexer.ts` / `LuaParser.ts` - TypeScript parser
+   - Generated from grammar using ANTLR4
+   - Committed to version control
+
+3. **Semantic Visitor** (`semantic_visitor.py`)
+   - Walks ANTLR parse tree
+   - Recognizes DSL function calls (name, parameter, agent, etc.)
+   - Extracts arguments and builds registry
+   - Does NOT execute code
+
+4. **Validator** (`validator.py`)
+   - Main entry point for validation
+   - Coordinates parsing, semantic analysis, and registry validation
+   - Supports quick (syntax only) and full (semantic) modes
+
+## Validation Modes
+
+### Quick Mode
+- ANTLR parse only
+- Catches syntax errors
+- Fast (suitable for IDE real-time validation)
+- Returns immediately after syntax check
+
+### Full Mode
+- ANTLR parse + semantic analysis + registry validation
+- Catches syntax errors, DSL errors, and semantic errors
+- Slower but thorough
+- Used by CLI and pre-execution validation
+
+## Usage
+
+### Python
+
+```python
+from tactus.validation import TactusValidator, ValidationMode
+
+validator = TactusValidator()
+
+# Quick validation (syntax only)
+result = validator.validate(source, ValidationMode.QUICK)
+
+# Full validation (syntax + semantics)
+result = validator.validate(source, ValidationMode.FULL)
+
+if result.valid:
+    print(f"Valid! Procedure: {result.registry.procedure_name}")
+else:
+    for error in result.errors:
+        print(f"Error at {error.location}: {error.message}")
+```
+
+### CLI
+
+```bash
+# Validate a file
+tactus validate examples/01-basics-hello-world.tac
+
+# Quick validation (syntax only)
+tactus validate examples/01-basics-hello-world.tac --quick
+```
+
+## Parser Generation
+
+### Requirements
+
+**Docker is REQUIRED** for parser generation:
+- ANTLR4 requires Java Runtime
+- We use Docker to avoid Java installation
+- Image: `eclipse-temurin:17-jre`
+
+### Regenerating Parsers
+
+**When to regenerate:**
+- Only when modifying grammar files
+- Generated parsers are committed to repo
+- End users don't need to regenerate
+
+**How to regenerate:**
+
+```bash
+# Ensure Docker is running
+make generate-parsers
+
+# Or individually:
+make generate-python-parser
+make generate-typescript-parser
+```
+
+### Manual Generation
+
+**Python:**
+```bash
+docker run --rm \
+  -v $(pwd):/work \
+  -v /tmp:/tmp \
+  -w /work \
+  eclipse-temurin:17-jre \
+  java -jar /tmp/antlr-4.13.1-complete.jar \
+  -Dlanguage=Python3 \
+  -visitor \
+  -no-listener \
+  -o /work/tactus/validation/generated \
+  /work/tactus/validation/grammar/LuaLexer.g4 \
+  /work/tactus/validation/grammar/LuaParser.g4
+
+# Fix 'this' references (ANTLR bug)
+sed -i 's/this\./self./g' tactus/validation/generated/LuaParser.py
+sed -i 's/this\./self./g' tactus/validation/generated/LuaLexer.py
+```
+
+**TypeScript:**
+```bash
+docker run --rm \
+  -v $(pwd):/work \
+  -w /work/tactus-web \
+  eclipse-temurin:17-jre \
+  bash -c "
+    curl -fsSL https://deb.nodesource.com/setup_20.x | bash - &&
+    apt-get install -y nodejs &&
+    npm install &&
+    npx antlr4ts -visitor -no-listener \
+      -o src/validation/generated \
+      /work/tactus/validation/grammar/LuaLexer.g4 \
+      /work/tactus/validation/grammar/LuaParser.g4
+  "
+```
+
+## Testing
+
+### Python Tests
+
+```bash
+pytest tests/validation/test_antlr_parser.py -v
+```
+
+Tests cover:
+- Valid/invalid Lua syntax
+- Error location reporting
+- DSL function recognition
+- Parameter/output/agent extraction
+- All example files
+- Missing required fields
+- Quick vs full mode
+
+### TypeScript Tests
+
+```bash
+cd tactus-web && npm test
+```
+
+**Note:** TypeScript parser currently has compilation issues due to antlr4ts code generation bugs. This is being addressed.
+
+## Known Issues
+
+### TypeScript Parser
+The antlr4ts code generator has known issues:
+- Generates code with TypeScript compilation errors
+- Base class imports need manual fixes
+- Some generated code references don't match antlr4ts API
+
+**Workaround:** Python parser is fully functional and used for all validation. TypeScript parser is in progress.
+
+## Why ANTLR?
+
+1. **Formal Grammar** - Standard Lua 5.4 grammar, not custom
+2. **Multi-Language** - Same grammar generates Python and TypeScript parsers
+3. **No Execution** - Validates without running code
+4. **IDE Support** - Parse tree enables syntax highlighting, autocomplete, etc.
+5. **Accurate** - Catches all Lua syntax errors
+6. **Maintainable** - Grammar is separate from implementation
+
+## Separation of Concerns
+
+- **Validation (ANTLR)**: Parse tree analysis, no execution
+- **Runtime (lupa)**: Actual Lua execution with primitives
+
+The same `.tac` file works for both:
+- ANTLR validates structure
+- lupa executes the procedure
+
+
+
+
+
+
+
+
+
+
+
+

tactus/validation/__init__.py

@@ -0,0 +1,7 @@
+"""
+Validation module for Tactus DSL files.
+"""
+
+from .validator import TactusValidator, ValidationMode
+
+__all__ = ["TactusValidator", "ValidationMode"]

tactus/validation/error_listener.py

@@ -0,0 +1,21 @@
+"""
+ANTLR error listener for collecting syntax errors.
+"""
+
+from antlr4.error.ErrorListener import ErrorListener
+from tactus.core.registry import ValidationMessage
+
+
+class TactusErrorListener(ErrorListener):
+    """Collects syntax errors from ANTLR parser."""
+
+    def __init__(self):
+        self.errors = []
+
+    def syntaxError(self, recognizer, offendingSymbol, line, column, msg, e):
+        """Called when parser encounters a syntax error."""
+        self.errors.append(
+            ValidationMessage(
+                level="error", message=f"Syntax error: {msg}", location=(line, column)
+            )
+        )