"""
CSSL Built-in Functions
Provides standard functions available in all CSSL scripts
"""

import os
import sys
import time
import random
import hashlib
import json
import re
import math
from typing import Any, Dict, List, Optional, Callable, Union
from datetime import datetime


class CSSLBuiltinError(Exception):
    """Error in builtin function execution"""
    pass


class CSSLBuiltins:
    """
    Built-in functions for CSSL runtime
    These functions are available in all CSSL scripts without imports
    """

    def __init__(self, runtime=None):
        self.runtime = runtime
        self._functions: Dict[str, Callable] = {}
        self._register_all()

    def _register_all(self):
        """Register all built-in functions"""
        # Output functions
        self._functions['print'] = self.builtin_print
        self._functions['println'] = self.builtin_println
        self._functions['debug'] = self.builtin_debug
        self._functions['error'] = self.builtin_error
        self._functions['warn'] = self.builtin_warn
        self._functions['log'] = self.builtin_log

        # Type conversion
        self._functions['int'] = self.builtin_int
        self._functions['float'] = self.builtin_float
        self._functions['str'] = self.builtin_str
        self._functions['bool'] = self.builtin_bool
        self._functions['list'] = self.builtin_list
        self._functions['dict'] = self.builtin_dict

        # Type checking
        self._functions['typeof'] = self.builtin_typeof
        self._functions['isinstance'] = self.builtin_isinstance
        self._functions['isint'] = self.builtin_isint
        self._functions['isfloat'] = self.builtin_isfloat
        self._functions['isstr'] = self.builtin_isstr
        self._functions['isbool'] = self.builtin_isbool
        self._functions['islist'] = self.builtin_islist
        self._functions['isdict'] = self.builtin_isdict
        self._functions['isnull'] = self.builtin_isnull

        # String functions
        self._functions['len'] = self.builtin_len
        self._functions['upper'] = self.builtin_upper
        self._functions['lower'] = self.builtin_lower
        self._functions['trim'] = self.builtin_trim
        self._functions['ltrim'] = self.builtin_ltrim
        self._functions['rtrim'] = self.builtin_rtrim
        self._functions['split'] = self.builtin_split
        self._functions['join'] = self.builtin_join
        self._functions['replace'] = self.builtin_replace
        self._functions['substr'] = self.builtin_substr
        self._functions['contains'] = self.builtin_contains
        self._functions['startswith'] = self.builtin_startswith
        self._functions['endswith'] = self.builtin_endswith
        self._functions['format'] = self.builtin_format
        self._functions['concat'] = self.builtin_concat
        self._functions['repeat'] = self.builtin_repeat
        self._functions['reverse'] = self.builtin_reverse
        self._functions['indexof'] = self.builtin_indexof
        self._functions['lastindexof'] = self.builtin_lastindexof
        self._functions['padleft'] = self.builtin_padleft
        self._functions['padright'] = self.builtin_padright

        # List functions
        self._functions['push'] = self.builtin_push
        self._functions['pop'] = self.builtin_pop
        self._functions['shift'] = self.builtin_shift
        self._functions['unshift'] = self.builtin_unshift
        self._functions['slice'] = self.builtin_slice
        self._functions['sort'] = self.builtin_sort
        self._functions['rsort'] = self.builtin_rsort
        self._functions['unique'] = self.builtin_unique
        self._functions['flatten'] = self.builtin_flatten
        self._functions['filter'] = self.builtin_filter
        self._functions['map'] = self.builtin_map
        self._functions['reduce'] = self.builtin_reduce
        self._functions['find'] = self.builtin_find
        self._functions['findindex'] = self.builtin_findindex
        self._functions['every'] = self.builtin_every
        self._functions['some'] = self.builtin_some
        self._functions['range'] = self.builtin_range

        # Dict functions
        self._functions['keys'] = self.builtin_keys
        self._functions['values'] = self.builtin_values
        self._functions['items'] = self.builtin_items
        self._functions['haskey'] = self.builtin_haskey
        self._functions['getkey'] = self.builtin_getkey
        self._functions['setkey'] = self.builtin_setkey
        self._functions['delkey'] = self.builtin_delkey
        self._functions['merge'] = self.builtin_merge

        # Math functions
        self._functions['abs'] = self.builtin_abs
        self._functions['min'] = self.builtin_min
        self._functions['max'] = self.builtin_max
        self._functions['sum'] = self.builtin_sum
        self._functions['avg'] = self.builtin_avg
        self._functions['round'] = self.builtin_round
        self._functions['floor'] = self.builtin_floor
        self._functions['ceil'] = self.builtin_ceil
        self._functions['pow'] = self.builtin_pow
        self._functions['sqrt'] = self.builtin_sqrt
        self._functions['mod'] = self.builtin_mod
        self._functions['random'] = self.builtin_random
        self._functions['randint'] = self.builtin_randint
        # Extended math functions
        self._functions['sin'] = self.builtin_sin
        self._functions['cos'] = self.builtin_cos
        self._functions['tan'] = self.builtin_tan
        self._functions['asin'] = self.builtin_asin
        self._functions['acos'] = self.builtin_acos
        self._functions['atan'] = self.builtin_atan
        self._functions['atan2'] = self.builtin_atan2
        self._functions['log'] = self.builtin_log
        self._functions['log10'] = self.builtin_log10
        self._functions['exp'] = self.builtin_exp
        self._functions['pi'] = lambda: math.pi
        self._functions['e'] = lambda: math.e
        self._functions['radians'] = self.builtin_radians
        self._functions['degrees'] = self.builtin_degrees

        # Time functions
        self._functions['now'] = self.builtin_now
        self._functions['timestamp'] = self.builtin_timestamp
        self._functions['sleep'] = self.builtin_sleep
        self._functions['date'] = self.builtin_date
        self._functions['time'] = self.builtin_time
        self._functions['datetime'] = self.builtin_datetime
        self._functions['strftime'] = self.builtin_strftime

        # File/Path functions
        self._functions['pathexists'] = self.builtin_pathexists
        self._functions['isfile'] = self.builtin_isfile
        self._functions['isdir'] = self.builtin_isdir
        self._functions['basename'] = self.builtin_basename
        self._functions['dirname'] = self.builtin_dirname
        self._functions['joinpath'] = self.builtin_joinpath
        self._functions['splitpath'] = self.builtin_splitpath
        self._functions['abspath'] = self.builtin_abspath
        self._functions['normpath'] = self.builtin_normpath
        # File I/O functions
        self._functions['readfile'] = self.builtin_readfile
        self._functions['writefile'] = self.builtin_writefile
        self._functions['appendfile'] = self.builtin_appendfile
        self._functions['readlines'] = self.builtin_readlines
        self._functions['listdir'] = self.builtin_listdir
        self._functions['makedirs'] = self.builtin_makedirs
        self._functions['removefile'] = self.builtin_removefile
        self._functions['removedir'] = self.builtin_removedir
        self._functions['copyfile'] = self.builtin_copyfile
        self._functions['movefile'] = self.builtin_movefile
        self._functions['filesize'] = self.builtin_filesize

        # JSON functions
        self._functions['tojson'] = self.builtin_tojson
        self._functions['fromjson'] = self.builtin_fromjson

        # Regex functions
        self._functions['match'] = self.builtin_match
        self._functions['search'] = self.builtin_search
        self._functions['findall'] = self.builtin_findall
        self._functions['sub'] = self.builtin_sub

        # Hash functions
        self._functions['md5'] = self.builtin_md5
        self._functions['sha1'] = self.builtin_sha1
        self._functions['sha256'] = self.builtin_sha256

        # Utility functions
        self._functions['copy'] = self.builtin_copy
        self._functions['deepcopy'] = self.builtin_deepcopy
        self._functions['assert'] = self.builtin_assert
        self._functions['exit'] = self.builtin_exit
        self._functions['env'] = self.builtin_env
        self._functions['setenv'] = self.builtin_setenv
        self._functions['input'] = self.builtin_input
        self._functions['clear'] = self.builtin_clear
        self._functions['cls'] = self.builtin_clear  # Alias
        self._functions['color'] = self.builtin_color
        self._functions['delay'] = self.builtin_delay
        self._functions['pyimport'] = self.builtin_pyimport

        # Extended string functions
        self._functions['sprintf'] = self.builtin_sprintf
        self._functions['chars'] = self.builtin_chars
        self._functions['ord'] = self.builtin_ord
        self._functions['chr'] = self.builtin_chr
        self._functions['capitalize'] = self.builtin_capitalize
        self._functions['title'] = self.builtin_title
        self._functions['swapcase'] = self.builtin_swapcase
        self._functions['center'] = self.builtin_center
        self._functions['zfill'] = self.builtin_zfill
        self._functions['isalpha'] = self.builtin_isalpha
        self._functions['isdigit'] = self.builtin_isdigit
        self._functions['isalnum'] = self.builtin_isalnum
        self._functions['isspace'] = self.builtin_isspace

        # Extended list functions
        self._functions['enumerate'] = self.builtin_enumerate
        self._functions['zip'] = self.builtin_zip
        self._functions['reversed'] = self.builtin_reversed
        self._functions['sorted'] = self.builtin_sorted
        self._functions['count'] = self.builtin_count
        self._functions['first'] = self.builtin_first
        self._functions['last'] = self.builtin_last
        self._functions['take'] = self.builtin_take
        self._functions['drop'] = self.builtin_drop
        self._functions['chunk'] = self.builtin_chunk
        self._functions['groupby'] = self.builtin_groupby
        self._functions['shuffle'] = self.builtin_shuffle
        self._functions['sample'] = self.builtin_sample

        # Extended dict functions
        self._functions['update'] = self.builtin_update
        self._functions['fromkeys'] = self.builtin_fromkeys
        self._functions['invert'] = self.builtin_invert
        self._functions['pick'] = self.builtin_pick
        self._functions['omit'] = self.builtin_omit

        # CSSL-specific system functions
        self._functions['createcmd'] = self.builtin_createcmd
        self._functions['signal'] = self.builtin_signal
        self._functions['appexec'] = self.builtin_appexec
        self._functions['initpy'] = self.builtin_initpy
        self._functions['initsh'] = self.builtin_initsh
        self._functions['wait_for'] = self.builtin_wait_for
        self._functions['wait_for_event'] = self.builtin_wait_for_event
        self._functions['wait_for_booted'] = self.builtin_wait_for_booted
        self._functions['emit'] = self.builtin_emit
        self._functions['on_event'] = self.builtin_on_event

        # CSSL Import System Functions
        self._functions['cso_root'] = self.builtin_cso_root
        self._functions['include'] = self.builtin_include
        self._functions['get'] = self.builtin_get

        # NEW: Extended OS Functions
        self._functions['Listdir'] = self.builtin_listdir  # Alias with capital L
        self._functions['ReadFile'] = self.builtin_readfile  # Alias with capitals
        self._functions['WriteFile'] = self.builtin_writefile  # Alias with capitals
        self._functions['isLinux'] = self.builtin_islinux
        self._functions['isWindows'] = self.builtin_iswindows
        self._functions['isMac'] = self.builtin_ismac

        # NEW: Extended Time Functions
        self._functions['CurrentTime'] = self.builtin_currenttime

        # NEW: Scope/Global Functions
        self._functions['global'] = self.builtin_global

        # CSSL Data Type Constructors
        self._functions['datastruct'] = self.builtin_datastruct
        self._functions['shuffled'] = self.builtin_shuffled
        self._functions['iterator'] = self.builtin_iterator
        self._functions['combo'] = self.builtin_combo
        self._functions['dataspace'] = self.builtin_dataspace
        self._functions['openquote'] = self.builtin_openquote
        self._functions['OpenFind'] = self.builtin_openfind

        # Print aliases for CSSL
        self._functions['printl'] = self.builtin_println  # CSSL uses printl for println

    def get_function(self, name: str) -> Optional[Callable]:
        """Get a built-in function by name"""
        return self._functions.get(name)

    def has_function(self, name: str) -> bool:
        """Check if a built-in function exists"""
        return name in self._functions

    def call(self, name: str, *args, **kwargs) -> Any:
        """Call a built-in function"""
        func = self._functions.get(name)
        if not func:
            raise CSSLBuiltinError(f"Unknown builtin function: {name}")
        return func(*args, **kwargs)

    def list_functions(self) -> List[str]:
        """List all available built-in functions"""
        return sorted(self._functions.keys())

    # ============= Output Functions =============

    def builtin_print(self, *args, **kwargs) -> None:
        """Print without newline"""
        sep = kwargs.get('sep', ' ')
        end = kwargs.get('end', '')
        output = sep.join(str(a) for a in args) + end
        if self.runtime and hasattr(self.runtime, 'output'):
            self.runtime.output(output)
        else:
            print(output, end='')

    def builtin_println(self, *args, **kwargs) -> None:
        """Print with newline"""
        sep = kwargs.get('sep', ' ')
        output = sep.join(str(a) for a in args)
        if self.runtime and hasattr(self.runtime, 'output'):
            self.runtime.output(output + '\n')
        else:
            print(output)

    def builtin_debug(self, *args) -> None:
        """Debug output"""
        msg = ' '.join(str(a) for a in args)
        if self.runtime and hasattr(self.runtime, 'debug'):
            self.runtime.debug(msg)
        else:
            print(f"[DEBUG] {msg}")

    def builtin_error(self, *args) -> None:
        """Error output"""
        msg = ' '.join(str(a) for a in args)
        if self.runtime and hasattr(self.runtime, 'error'):
            self.runtime.error(msg)
        else:
            print(f"[ERROR] {msg}")

    def builtin_warn(self, *args) -> None:
        """Warning output"""
        msg = ' '.join(str(a) for a in args)
        if self.runtime and hasattr(self.runtime, 'warn'):
            self.runtime.warn(msg)
        else:
            print(f"[WARN] {msg}")

    def builtin_log(self, level: str, *args) -> None:
        """Log with level"""
        msg = ' '.join(str(a) for a in args)
        if self.runtime and hasattr(self.runtime, 'log'):
            self.runtime.log(level, msg)
        else:
            print(f"[{level.upper()}] {msg}")

    # ============= Type Conversion =============

    def builtin_int(self, value: Any, base: int = 10) -> int:
        """Convert to integer"""
        if isinstance(value, str):
            return int(value, base)
        return int(value)

    def builtin_float(self, value: Any) -> float:
        """Convert to float"""
        return float(value)

    def builtin_str(self, value: Any) -> str:
        """Convert to string"""
        return str(value)

    def builtin_bool(self, value: Any) -> bool:
        """Convert to boolean"""
        if isinstance(value, str):
            return value.lower() not in ('', '0', 'false', 'no', 'null', 'none')
        return bool(value)

    def builtin_list(self, value: Any = None) -> list:
        """Convert to list"""
        if value is None:
            return []
        if isinstance(value, (list, tuple)):
            return list(value)
        if isinstance(value, dict):
            return list(value.items())
        if isinstance(value, str):
            return list(value)
        return [value]

    def builtin_dict(self, value: Any = None) -> dict:
        """Convert to dict"""
        if value is None:
            return {}
        if isinstance(value, dict):
            return dict(value)
        if isinstance(value, (list, tuple)):
            return dict(value)
        raise CSSLBuiltinError(f"Cannot convert {type(value).__name__} to dict")

    # ============= Type Checking =============

    def builtin_typeof(self, value: Any) -> str:
        """Get type name"""
        if value is None:
            return 'null'
        type_map = {
            int: 'int',
            float: 'float',
            str: 'str',
            bool: 'bool',
            list: 'list',
            dict: 'dict',
            tuple: 'tuple'
        }
        return type_map.get(type(value), type(value).__name__)

    def builtin_isinstance(self, value: Any, type_name: str) -> bool:
        """Check if value is of type"""
        type_map = {
            'int': int,
            'float': float,
            'str': str,
            'bool': bool,
            'list': list,
            'dict': dict,
            'tuple': tuple,
            'null': type(None)
        }
        check_type = type_map.get(type_name)
        if check_type:
            return isinstance(value, check_type)
        return False

    def builtin_isint(self, value: Any) -> bool:
        return isinstance(value, int) and not isinstance(value, bool)

    def builtin_isfloat(self, value: Any) -> bool:
        return isinstance(value, float)

    def builtin_isstr(self, value: Any) -> bool:
        return isinstance(value, str)

    def builtin_isbool(self, value: Any) -> bool:
        return isinstance(value, bool)

    def builtin_islist(self, value: Any) -> bool:
        return isinstance(value, list)

    def builtin_isdict(self, value: Any) -> bool:
        return isinstance(value, dict)

    def builtin_isnull(self, value: Any) -> bool:
        return value is None

    # ============= String Functions =============

    def builtin_len(self, value: Union[str, list, dict]) -> int:
        """Get length"""
        return len(value)

    def builtin_upper(self, s: str) -> str:
        return str(s).upper()

    def builtin_lower(self, s: str) -> str:
        return str(s).lower()

    def builtin_trim(self, s: str, chars: str = None) -> str:
        return str(s).strip(chars)

    def builtin_ltrim(self, s: str, chars: str = None) -> str:
        return str(s).lstrip(chars)

    def builtin_rtrim(self, s: str, chars: str = None) -> str:
        return str(s).rstrip(chars)

    def builtin_split(self, s: str, sep: str = None, maxsplit: int = -1) -> list:
        return str(s).split(sep, maxsplit)

    def builtin_join(self, sep: str, items: list) -> str:
        return str(sep).join(str(i) for i in items)

    def builtin_replace(self, s: str, old: str, new: str, count: int = -1) -> str:
        return str(s).replace(old, new, count)

    def builtin_substr(self, s: str, start: int, length: int = None) -> str:
        s = str(s)
        if length is None:
            return s[start:]
        return s[start:start + length]

    def builtin_contains(self, s: str, sub: str) -> bool:
        return sub in str(s)

    def builtin_startswith(self, s: str, prefix: str) -> bool:
        return str(s).startswith(prefix)

    def builtin_endswith(self, s: str, suffix: str) -> bool:
        return str(s).endswith(suffix)

    def builtin_format(self, template: str, *args, **kwargs) -> str:
        return template.format(*args, **kwargs)

    def builtin_concat(self, *args) -> str:
        return ''.join(str(a) for a in args)

    def builtin_repeat(self, s: str, count: int) -> str:
        return str(s) * count

    def builtin_reverse(self, value: Union[str, list]) -> Union[str, list]:
        if isinstance(value, str):
            return value[::-1]
        if isinstance(value, list):
            return value[::-1]
        raise CSSLBuiltinError("reverse requires string or list")

    def builtin_indexof(self, s: str, sub: str, start: int = 0) -> int:
        return str(s).find(sub, start)

    def builtin_lastindexof(self, s: str, sub: str) -> int:
        return str(s).rfind(sub)

    def builtin_padleft(self, s: str, width: int, char: str = ' ') -> str:
        return str(s).rjust(width, char)

    def builtin_padright(self, s: str, width: int, char: str = ' ') -> str:
        return str(s).ljust(width, char)

    # ============= List Functions =============

    def builtin_push(self, lst: list, *items) -> list:
        lst = list(lst)
        lst.extend(items)
        return lst

    def builtin_pop(self, lst: list, index: int = -1) -> Any:
        lst = list(lst)
        return lst.pop(index)

    def builtin_shift(self, lst: list) -> Any:
        lst = list(lst)
        return lst.pop(0) if lst else None

    def builtin_unshift(self, lst: list, *items) -> list:
        lst = list(lst)
        for item in reversed(items):
            lst.insert(0, item)
        return lst

    def builtin_slice(self, value: Union[str, list], start: int, end: int = None) -> Union[str, list]:
        if end is None:
            return value[start:]
        return value[start:end]

    def builtin_sort(self, lst: list, key: str = None) -> list:
        lst = list(lst)
        if key:
            lst.sort(key=lambda x: x.get(key) if isinstance(x, dict) else x)
        else:
            lst.sort()
        return lst

    def builtin_rsort(self, lst: list, key: str = None) -> list:
        lst = list(lst)
        if key:
            lst.sort(key=lambda x: x.get(key) if isinstance(x, dict) else x, reverse=True)
        else:
            lst.sort(reverse=True)
        return lst

    def builtin_unique(self, lst: list) -> list:
        seen = []
        result = []
        for item in lst:
            key = json.dumps(item, sort_keys=True) if isinstance(item, (dict, list)) else item
            if key not in seen:
                seen.append(key)
                result.append(item)
        return result

    def builtin_flatten(self, lst: list, depth: int = 1) -> list:
        result = []
        for item in lst:
            if isinstance(item, list) and depth > 0:
                result.extend(self.builtin_flatten(item, depth - 1))
            else:
                result.append(item)
        return result

    def builtin_filter(self, lst: list, condition: Callable) -> list:
        return [item for item in lst if condition(item)]

    def builtin_map(self, lst: list, func: Callable) -> list:
        return [func(item) for item in lst]

    def builtin_reduce(self, lst: list, func: Callable, initial: Any = None) -> Any:
        from functools import reduce
        if initial is not None:
            return reduce(func, lst, initial)
        return reduce(func, lst)

    def builtin_find(self, lst: list, condition: Callable) -> Any:
        for item in lst:
            if condition(item):
                return item
        return None

    def builtin_findindex(self, lst: list, condition: Callable) -> int:
        for i, item in enumerate(lst):
            if condition(item):
                return i
        return -1

    def builtin_every(self, lst: list, condition: Callable) -> bool:
        return all(condition(item) for item in lst)

    def builtin_some(self, lst: list, condition: Callable) -> bool:
        return any(condition(item) for item in lst)

    def builtin_range(self, *args) -> list:
        return list(range(*args))

    # ============= Dict Functions =============

    def builtin_keys(self, d: dict) -> list:
        return list(d.keys())

    def builtin_values(self, d: dict) -> list:
        return list(d.values())

    def builtin_items(self, d: dict) -> list:
        return list(d.items())

    def builtin_haskey(self, d: dict, key: str) -> bool:
        return key in d

    def builtin_getkey(self, d: dict, key: str, default: Any = None) -> Any:
        return d.get(key, default)

    def builtin_setkey(self, d: dict, key: str, value: Any) -> dict:
        d = dict(d)
        d[key] = value
        return d

    def builtin_delkey(self, d: dict, key: str) -> dict:
        d = dict(d)
        d.pop(key, None)
        return d

    def builtin_merge(self, *dicts) -> dict:
        result = {}
        for d in dicts:
            if isinstance(d, dict):
                result.update(d)
        return result

    # ============= Math Functions =============

    def builtin_abs(self, x: Union[int, float]) -> Union[int, float]:
        return abs(x)

    def builtin_min(self, *args) -> Any:
        if len(args) == 1 and isinstance(args[0], (list, tuple)):
            return min(args[0])
        return min(args)

    def builtin_max(self, *args) -> Any:
        if len(args) == 1 and isinstance(args[0], (list, tuple)):
            return max(args[0])
        return max(args)

    def builtin_sum(self, items: list, start: Union[int, float] = 0) -> Union[int, float]:
        return sum(items, start)

    def builtin_avg(self, items: list) -> float:
        if not items:
            return 0.0
        return sum(items) / len(items)

    def builtin_round(self, x: float, digits: int = 0) -> float:
        return round(x, digits)

    def builtin_floor(self, x: float) -> int:
        import math
        return math.floor(x)

    def builtin_ceil(self, x: float) -> int:
        import math
        return math.ceil(x)

    def builtin_pow(self, base: Union[int, float], exp: Union[int, float]) -> Union[int, float]:
        return pow(base, exp)

    def builtin_sqrt(self, x: Union[int, float]) -> float:
        import math
        return math.sqrt(x)

    def builtin_mod(self, a: int, b: int) -> int:
        return a % b

    def builtin_random(self) -> float:
        return random.random()

    def builtin_randint(self, a: int, b: int) -> int:
        return random.randint(a, b)

    def builtin_sin(self, x: float) -> float:
        return math.sin(x)

    def builtin_cos(self, x: float) -> float:
        return math.cos(x)

    def builtin_tan(self, x: float) -> float:
        return math.tan(x)

    def builtin_asin(self, x: float) -> float:
        return math.asin(x)

    def builtin_acos(self, x: float) -> float:
        return math.acos(x)

    def builtin_atan(self, x: float) -> float:
        return math.atan(x)

    def builtin_atan2(self, y: float, x: float) -> float:
        return math.atan2(y, x)

    def builtin_log(self, x: float, base: float = math.e) -> float:
        return math.log(x, base)

    def builtin_log10(self, x: float) -> float:
        return math.log10(x)

    def builtin_exp(self, x: float) -> float:
        return math.exp(x)

    def builtin_radians(self, degrees: float) -> float:
        return math.radians(degrees)

    def builtin_degrees(self, radians: float) -> float:
        return math.degrees(radians)

    # ============= Time Functions =============

    def builtin_now(self) -> float:
        return time.time()

    def builtin_timestamp(self) -> int:
        return int(time.time())

    def builtin_sleep(self, seconds: float) -> None:
        time.sleep(seconds)

    def builtin_date(self, format_str: str = '%Y-%m-%d') -> str:
        return datetime.now().strftime(format_str)

    def builtin_time(self, format_str: str = '%H:%M:%S') -> str:
        return datetime.now().strftime(format_str)

    def builtin_datetime(self, format_str: str = '%Y-%m-%d %H:%M:%S') -> str:
        return datetime.now().strftime(format_str)

    def builtin_strftime(self, format_str: str, timestamp: float = None) -> str:
        if timestamp is None:
            return datetime.now().strftime(format_str)
        return datetime.fromtimestamp(timestamp).strftime(format_str)

    # ============= File/Path Functions =============

    def builtin_pathexists(self, path: str) -> bool:
        return os.path.exists(path)

    def builtin_isfile(self, path: str) -> bool:
        return os.path.isfile(path)

    def builtin_isdir(self, path: str) -> bool:
        return os.path.isdir(path)

    def builtin_basename(self, path: str) -> str:
        return os.path.basename(path)

    def builtin_dirname(self, path: str) -> str:
        return os.path.dirname(path)

    def builtin_joinpath(self, *parts) -> str:
        return os.path.join(*parts)

    def builtin_splitpath(self, path: str) -> list:
        return list(os.path.split(path))

    def builtin_abspath(self, path: str) -> str:
        return os.path.abspath(path)

    def builtin_normpath(self, path: str) -> str:
        return os.path.normpath(path)

    # ============= File I/O Functions =============

    def builtin_readfile(self, path: str, encoding: str = 'utf-8') -> str:
        """Read entire file content"""
        with open(path, 'r', encoding=encoding) as f:
            return f.read()

    def builtin_writefile(self, path: str, content: str, encoding: str = 'utf-8') -> int:
        """Write content to file, returns bytes written"""
        with open(path, 'w', encoding=encoding) as f:
            return f.write(content)

    def builtin_appendfile(self, path: str, content: str, encoding: str = 'utf-8') -> int:
        """Append content to file, returns bytes written"""
        with open(path, 'a', encoding=encoding) as f:
            return f.write(content)

    def builtin_readlines(self, path: str, encoding: str = 'utf-8') -> list:
        """Read file lines into list"""
        with open(path, 'r', encoding=encoding) as f:
            return f.readlines()

    def builtin_listdir(self, path: str = '.') -> list:
        """List directory contents"""
        return os.listdir(path)

    def builtin_makedirs(self, path: str, exist_ok: bool = True) -> bool:
        """Create directories recursively"""
        os.makedirs(path, exist_ok=exist_ok)
        return True

    def builtin_removefile(self, path: str) -> bool:
        """Remove a file"""
        os.remove(path)
        return True

    def builtin_removedir(self, path: str) -> bool:
        """Remove an empty directory"""
        os.rmdir(path)
        return True

    def builtin_copyfile(self, src: str, dst: str) -> str:
        """Copy a file, returns destination path"""
        import shutil
        return shutil.copy2(src, dst)

    def builtin_movefile(self, src: str, dst: str) -> str:
        """Move a file, returns destination path"""
        import shutil
        return shutil.move(src, dst)

    def builtin_filesize(self, path: str) -> int:
        """Get file size in bytes"""
        return os.path.getsize(path)

    # ============= JSON Functions =============

    def builtin_tojson(self, value: Any, indent: int = None) -> str:
        return json.dumps(value, indent=indent, ensure_ascii=False)

    def builtin_fromjson(self, s: str) -> Any:
        return json.loads(s)

    # ============= Regex Functions =============

    def builtin_match(self, pattern: str, string: str) -> Optional[dict]:
        m = re.match(pattern, string)
        if m:
            return {'match': m.group(), 'groups': m.groups(), 'start': m.start(), 'end': m.end()}
        return None

    def builtin_search(self, pattern: str, string: str) -> Optional[dict]:
        m = re.search(pattern, string)
        if m:
            return {'match': m.group(), 'groups': m.groups(), 'start': m.start(), 'end': m.end()}
        return None

    def builtin_findall(self, pattern: str, string: str) -> list:
        return re.findall(pattern, string)

    def builtin_sub(self, pattern: str, repl: str, string: str, count: int = 0) -> str:
        return re.sub(pattern, repl, string, count)

    # ============= Hash Functions =============

    def builtin_md5(self, s: str) -> str:
        return hashlib.md5(s.encode()).hexdigest()

    def builtin_sha1(self, s: str) -> str:
        return hashlib.sha1(s.encode()).hexdigest()

    def builtin_sha256(self, s: str) -> str:
        return hashlib.sha256(s.encode()).hexdigest()

    # ============= Utility Functions =============

    def builtin_copy(self, value: Any) -> Any:
        import copy
        return copy.copy(value)

    def builtin_deepcopy(self, value: Any) -> Any:
        import copy
        return copy.deepcopy(value)

    def builtin_assert(self, condition: bool, message: str = "Assertion failed") -> None:
        if not condition:
            raise CSSLBuiltinError(message)

    def builtin_exit(self, code: int = 0) -> None:
        if self.runtime and hasattr(self.runtime, 'exit'):
            self.runtime.exit(code)
        else:
            raise SystemExit(code)

    def builtin_env(self, name: str, default: str = None) -> Optional[str]:
        return os.environ.get(name, default)

    def builtin_setenv(self, name: str, value: str) -> None:
        """Set environment variable"""
        os.environ[name] = value

    def builtin_input(self, prompt: str = '') -> str:
        """Read user input"""
        return input(prompt)

    def builtin_clear(self) -> None:
        """Clear console screen"""
        if os.name == 'nt':
            os.system('cls')
        else:
            print('\033[2J\033[H', end='')

    def builtin_color(self, text: str, color: str) -> str:
        """Apply ANSI color to text"""
        colors = {
            'black': '30', 'red': '31', 'green': '32', 'yellow': '33',
            'blue': '34', 'magenta': '35', 'cyan': '36', 'white': '37',
            'bright_black': '90', 'bright_red': '91', 'bright_green': '92',
            'bright_yellow': '93', 'bright_blue': '94', 'bright_magenta': '95',
            'bright_cyan': '96', 'bright_white': '97',
            'reset': '0', 'bold': '1', 'dim': '2', 'italic': '3',
            'underline': '4', 'blink': '5', 'reverse': '7'
        }
        code = colors.get(color.lower(), color)
        return f'\033[{code}m{text}\033[0m'

    def builtin_delay(self, ms: float) -> None:
        """Delay execution by milliseconds"""
        time.sleep(ms / 1000.0)

    def builtin_pyimport(self, module_name: str) -> Any:
        """Import a Python module for use in CSSL"""
        return __import__(module_name)

    # ============= Extended String Functions =============

    def builtin_sprintf(self, fmt: str, *args) -> str:
        """C-style format string"""
        return fmt % args

    def builtin_chars(self, s: str) -> list:
        """Convert string to list of characters"""
        return list(s)

    def builtin_ord(self, c: str) -> int:
        """Get ASCII/Unicode code of character"""
        return ord(c[0] if c else '\0')

    def builtin_chr(self, n: int) -> str:
        """Convert ASCII/Unicode code to character"""
        return chr(n)

    def builtin_capitalize(self, s: str) -> str:
        return str(s).capitalize()

    def builtin_title(self, s: str) -> str:
        return str(s).title()

    def builtin_swapcase(self, s: str) -> str:
        return str(s).swapcase()

    def builtin_center(self, s: str, width: int, fillchar: str = ' ') -> str:
        return str(s).center(width, fillchar)

    def builtin_zfill(self, s: str, width: int) -> str:
        return str(s).zfill(width)

    def builtin_isalpha(self, s: str) -> bool:
        return str(s).isalpha()

    def builtin_isdigit(self, s: str) -> bool:
        return str(s).isdigit()

    def builtin_isalnum(self, s: str) -> bool:
        return str(s).isalnum()

    def builtin_isspace(self, s: str) -> bool:
        return str(s).isspace()

    # ============= Extended List Functions =============

    def builtin_enumerate(self, lst: list, start: int = 0) -> list:
        """Return list of (index, value) pairs"""
        return list(enumerate(lst, start))

    def builtin_zip(self, *lists) -> list:
        """Zip multiple lists together"""
        return list(zip(*lists))

    def builtin_reversed(self, lst: list) -> list:
        """Return reversed list"""
        return list(reversed(lst))

    def builtin_sorted(self, lst: list, key: str = None, reverse: bool = False) -> list:
        """Return sorted list"""
        if key:
            return sorted(lst, key=lambda x: x.get(key) if isinstance(x, dict) else x, reverse=reverse)
        return sorted(lst, reverse=reverse)

    def builtin_count(self, collection: Union[list, str], item: Any) -> int:
        """Count occurrences of item"""
        return collection.count(item)

    def builtin_first(self, lst: list, default: Any = None) -> Any:
        """Get first element or default"""
        return lst[0] if lst else default

    def builtin_last(self, lst: list, default: Any = None) -> Any:
        """Get last element or default"""
        return lst[-1] if lst else default

    def builtin_take(self, lst: list, n: int) -> list:
        """Take first n elements"""
        return lst[:n]

    def builtin_drop(self, lst: list, n: int) -> list:
        """Drop first n elements"""
        return lst[n:]

    def builtin_chunk(self, lst: list, size: int) -> list:
        """Split list into chunks of given size"""
        return [lst[i:i + size] for i in range(0, len(lst), size)]

    def builtin_groupby(self, lst: list, key: str) -> dict:
        """Group list of dicts by key"""
        result = {}
        for item in lst:
            k = item.get(key) if isinstance(item, dict) else getattr(item, key, None)
            if k not in result:
                result[k] = []
            result[k].append(item)
        return result

    def builtin_shuffle(self, lst: list) -> list:
        """Return shuffled copy of list"""
        result = list(lst)
        random.shuffle(result)
        return result

    def builtin_sample(self, lst: list, k: int) -> list:
        """Return k random elements from list"""
        return random.sample(lst, min(k, len(lst)))

    # ============= Extended Dict Functions =============

    def builtin_update(self, d: dict, other: dict) -> dict:
        """Update dict with another dict, return new dict"""
        result = dict(d)
        result.update(other)
        return result

    def builtin_fromkeys(self, keys: list, value: Any = None) -> dict:
        """Create dict from keys with default value"""
        return dict.fromkeys(keys, value)

    def builtin_invert(self, d: dict) -> dict:
        """Swap keys and values"""
        return {v: k for k, v in d.items()}

    def builtin_pick(self, d: dict, *keys) -> dict:
        """Pick only specified keys from dict"""
        return {k: d[k] for k in keys if k in d}

    def builtin_omit(self, d: dict, *keys) -> dict:
        """Omit specified keys from dict"""
        return {k: v for k, v in d.items() if k not in keys}

    # ============= CSSL System Functions =============

    def builtin_createcmd(self, cmd_name: str, handler: Callable = None) -> bool:
        """
        Create a custom console command
        Usage: createcmd('mycommand') <== { ... handler code ... }
        """
        if not self.runtime:
            print(f"Cannot create command '{cmd_name}': No runtime available")
            return False

        # Store the command handler in runtime
        if not hasattr(self.runtime, '_custom_commands'):
            self.runtime._custom_commands = {}

        self.runtime._custom_commands[cmd_name] = handler

        # Find Console via multiple paths
        console = None

        # Try 1: Direct _console reference on runtime
        if hasattr(self.runtime, '_console') and self.runtime._console:
            console = self.runtime._console

        # Try 2: Via service_engine.Console
        elif self.runtime.service_engine and hasattr(self.runtime.service_engine, 'Console'):
            console = self.runtime.service_engine.Console

        # Register with Console if found
        if console and hasattr(console, 'register_custom_command'):
            console.register_custom_command(cmd_name, handler)
        else:
            print(f"Custom command '{cmd_name}' stored (Console not yet available)")

        return True

    def builtin_signal(self, event_ref: Any, action: str = '+') -> bool:
        """
        Send or register a signal/event
        Usage: signal(@event.CustomEvent, '+') to emit, '-' to unregister
        """
        try:
            from .cssl_events import get_event_manager, EventType

            event_manager = get_event_manager()

            # Handle event reference (could be string or module ref)
            event_name = str(event_ref) if not isinstance(event_ref, str) else event_ref

            if action == '+':
                # Emit the event
                event_manager.emit_custom(event_name, source="cssl_signal")
                print(f"Signal emitted: {event_name}")
                return True
            elif action == '-':
                # Unregister handlers for this event
                # This would need custom implementation
                print(f"Signal handlers cleared: {event_name}")
                return True
            else:
                print(f"Unknown signal action: {action}")
                return False

        except Exception as e:
            print(f"Signal error: {e}")
            return False

    def builtin_appexec(self, app_name: str, *args) -> bool:
        """
        Start a desktop application (visually)
        Usage: appexec('xface')
        """
        if not self.runtime or not self.runtime.service_engine:
            print(f"Cannot execute app '{app_name}': No service engine available")
            return False

        try:
            kernel = self.runtime.service_engine.KernelClient

            # Check if desktop environment is available
            if hasattr(kernel, 'start_desktop_app'):
                return kernel.start_desktop_app(app_name, *args)

            # Try to find and launch the app
            app_paths = [
                os.path.join(kernel.RootDirectory, 'apps', app_name),
                os.path.join(kernel.RootDirectory, 'apps', f'{app_name}.py'),
                os.path.join(kernel.RootDirectory, 'desktop', 'apps', app_name),
                os.path.join(kernel.RootDirectory, 'desktop', 'apps', f'{app_name}.py'),
            ]

            for app_path in app_paths:
                if os.path.exists(app_path):
                    print(f"Launching app: {app_name}")
                    if app_path.endswith('.py'):
                        return self.builtin_initpy(app_path)
                    return True

            print(f"App not found: {app_name}")
            return False

        except Exception as e:
            print(f"App execution error: {e}")
            return False

    def builtin_initpy(self, path: str, *args, **kwargs) -> Any:
        """
        Execute a Python file
        Usage: initpy('/path/to/script.py')
        """
        if not os.path.isabs(path) and self.runtime and self.runtime.service_engine:
            path = os.path.join(self.runtime.service_engine.KernelClient.RootDirectory, path)

        if not os.path.exists(path):
            raise CSSLBuiltinError(f"Python file not found: {path}")

        try:
            # Prepare execution context
            exec_globals = {
                '__file__': path,
                '__name__': '__main__',
            }

            # Add kernel and service engine if available
            if self.runtime and self.runtime.service_engine:
                exec_globals['kernel'] = self.runtime.service_engine.KernelClient
                exec_globals['service'] = self.runtime.service_engine
                exec_globals['args'] = args
                exec_globals['kwargs'] = kwargs

            with open(path, 'r', encoding='utf-8') as f:
                code = f.read()

            exec(compile(code, path, 'exec'), exec_globals)
            return exec_globals.get('result', True)

        except Exception as e:
            print(f"Python execution error [{path}]: {e}")
            raise CSSLBuiltinError(f"initpy failed: {e}")

    def builtin_initsh(self, path: str, *args) -> int:
        """
        Execute a shell script
        Usage: initsh('/path/to/script.sh')
        """
        import subprocess

        if not os.path.isabs(path) and self.runtime and self.runtime.service_engine:
            path = os.path.join(self.runtime.service_engine.KernelClient.RootDirectory, path)

        if not os.path.exists(path):
            raise CSSLBuiltinError(f"Shell script not found: {path}")

        try:
            # Determine shell based on platform
            import platform
            if platform.system() == 'Windows':
                # Use cmd or powershell on Windows
                cmd = ['cmd', '/c', path] + list(args)
            else:
                cmd = ['bash', path] + list(args)

            result = subprocess.run(cmd, capture_output=True, text=True)

            if result.stdout:
                print(result.stdout)
            if result.stderr:
                print(f"STDERR: {result.stderr}")

            return result.returncode

        except Exception as e:
            print(f"Shell execution error [{path}]: {e}")
            raise CSSLBuiltinError(f"initsh failed: {e}")

    def builtin_wait_for(self, condition: Callable, timeout: float = 30.0, interval: float = 0.1) -> bool:
        """
        Wait for a condition to become true
        Usage: wait_for(lambda: some_condition, timeout=30)
        """
        import time
        start = time.time()

        while time.time() - start < timeout:
            try:
                if callable(condition):
                    if condition():
                        return True
                elif condition:
                    return True
            except Exception:
                pass
            time.sleep(interval)

        return False

    def builtin_wait_for_event(self, event_name: str, timeout: float = 30.0) -> bool:
        """
        Wait for a specific event to occur
        Usage: wait_for_event('@event.Booted', timeout=60)
        """
        try:
            from .cssl_events import get_event_manager

            event_manager = get_event_manager()
            event_occurred = [False]

            def handler(event_data):
                event_occurred[0] = True

            # Register temporary handler
            handler_id = event_manager.register_custom(
                event_name,
                handler,
                once=True
            )

            # Wait for event
            import time
            start = time.time()
            while not event_occurred[0] and (time.time() - start) < timeout:
                time.sleep(0.1)

            # Cleanup if not occurred
            if not event_occurred[0]:
                event_manager.unregister(handler_id)

            return event_occurred[0]

        except Exception as e:
            print(f"wait_for_event error: {e}")
            return False

    def builtin_wait_for_booted(self, timeout: float = 60.0) -> bool:
        """
        Wait until the system is fully booted
        Usage: await wait_for_booted()
        """
        if not self.runtime or not self.runtime.service_engine:
            return False

        import time
        start = time.time()

        while time.time() - start < timeout:
            try:
                wheel = self.runtime.service_engine.KernelClient.WheelKernel
                booted = wheel.ReadWheelParam('boot', 'BOOTED')
                if booted == '1':
                    return True
            except Exception:
                pass
            time.sleep(0.5)

        return False

    def builtin_emit(self, event_name: str, data: Any = None) -> bool:
        """
        Emit a custom event
        Usage: emit('MyCustomEvent', {data: 'value'})
        """
        try:
            from .cssl_events import get_event_manager

            event_manager = get_event_manager()
            event_manager.emit_custom(event_name, source="cssl", data=data or {})
            return True

        except Exception as e:
            print(f"emit error: {e}")
            return False

    def builtin_on_event(self, event_name: str, handler: Callable) -> str:
        """
        Register an event handler
        Usage: on_event('MyEvent', handler_function)
        Returns: handler_id for later removal
        """
        try:
            from .cssl_events import get_event_manager

            event_manager = get_event_manager()
            handler_id = event_manager.register_custom(event_name, handler)
            return handler_id

        except Exception as e:
            print(f"on_event error: {e}")
            return ""

    # ============= CSSL Import System Functions =============

    def builtin_cso_root(self, path: str = "") -> str:
        """
        Get absolute path relative to CSO root directory
        Usage: cso_root('/services/myservice.cssl')
        Returns: Full absolute path to the file
        """
        base = os.getcwd()

        # Try to get base from kernel parameters
        if self.runtime and self.runtime.service_engine:
            try:
                kernel = self.runtime.service_engine.KernelClient
                if hasattr(kernel, 'WheelKernel'):
                    wheel = kernel.WheelKernel
                    if hasattr(wheel, 'KernelParam'):
                        base = wheel.KernelParam.get('@base', base)
                if hasattr(kernel, 'RootDirectory'):
                    base = kernel.RootDirectory
            except Exception:
                pass

        # Clean path and join
        if path:
            clean_path = path.lstrip('/').lstrip('\\')
            return os.path.normpath(os.path.join(base, clean_path))

        return base

    def builtin_include(self, filepath: str) -> Any:
        """
        Load and execute a CSSL file, returning its ServiceDefinition
        Usage: include(cso_root('/services/utils.cssl'))
        Returns: ServiceDefinition with structs, functions, etc.
        """
        if not self.runtime:
            raise CSSLBuiltinError("include requires runtime context")

        # Resolve relative paths
        if not os.path.isabs(filepath):
            filepath = self.builtin_cso_root(filepath)

        # Check file exists
        if not os.path.exists(filepath):
            raise CSSLBuiltinError(f"Include file not found: {filepath}")

        # Check include cache to prevent circular imports
        if not hasattr(self.runtime, '_include_cache'):
            self.runtime._include_cache = {}

        if filepath in self.runtime._include_cache:
            return self.runtime._include_cache[filepath]

        try:
            # Read and parse the file
            with open(filepath, 'r', encoding='utf-8') as f:
                source = f.read()

            from .cssl_parser import parse_cssl

            ast = parse_cssl(source)

            # Execute the service to get definitions
            service_def = self.runtime._exec_service(ast)

            # Cache the result
            self.runtime._include_cache[filepath] = service_def

            return service_def

        except Exception as e:
            raise CSSLBuiltinError(f"Failed to include '{filepath}': {e}")

    def builtin_get(self, source: Any, key: str = None) -> Any:
        """
        Get value from module, ServiceDefinition, or dict
        Usage:
          get('list')                   - Get list module (returns empty list creator)
          get('os')                     - Get OS module
          get('time')                   - Get Time module
          get(@Time)                    - Get standard module
          get(service_def, 'funcName')  - Get function from included service
          get(dict_obj, 'key')          - Get key from dict
        Returns: The requested value or None
        """
        # Single argument - return module reference directly
        if key is None:
            if isinstance(source, str):
                # NEW: Handle standard module names
                module_map = {
                    'list': self._get_list_module(),
                    'dict': self._get_dict_module(),
                    'os': self._get_os_module(),
                    'time': self._get_time_module(),
                    'vsramsdk': self._get_vsram_module(),
                    'kernel': self._get_kernel_module(),
                }
                if source.lower() in module_map:
                    return module_map[source.lower()]

                # Treat as module path
                if self.runtime:
                    return self.runtime.get_module(source)
            return source

        # Two arguments - extract from source
        if hasattr(source, key):
            return getattr(source, key)

        if isinstance(source, dict):
            return source.get(key)

        # Check if source is a ServiceDefinition-like object
        if hasattr(source, 'structs') and key in source.structs:
            return source.structs[key]

        if hasattr(source, 'functions') and key in source.functions:
            return source.functions[key]

        return None

    # NEW: Module factories for get()
    def _get_list_module(self):
        """Return a list module proxy"""
        class ListModule:
            @staticmethod
            def create():
                return []
            @staticmethod
            def add(lst, item):
                if isinstance(lst, list):
                    lst.append(item)
                return lst
        return ListModule()

    def _get_dict_module(self):
        """Return a dict module proxy"""
        class DictModule:
            @staticmethod
            def create():
                return {}
        return DictModule()

    def _get_os_module(self):
        """Return OS module proxy"""
        class OSModule:
            @staticmethod
            def Listdir(path='.'):
                return os.listdir(path)
            @staticmethod
            def ReadFile(path, encoding='utf-8'):
                with open(path, 'r', encoding=encoding) as f:
                    return f.read()
            @staticmethod
            def WriteFile(path, content, encoding='utf-8'):
                with open(path, 'w', encoding=encoding) as f:
                    return f.write(content)
            @staticmethod
            def isLinux():
                import platform
                return platform.system() == 'Linux'
            @staticmethod
            def isWindows():
                import platform
                return platform.system() == 'Windows'
            @staticmethod
            def isMac():
                import platform
                return platform.system() == 'Darwin'
        return OSModule()

    def _get_time_module(self):
        """Return Time module proxy"""
        class TimeModule:
            @staticmethod
            def CurrentTime(format_str='%Y-%m-%d %H:%M:%S'):
                return datetime.now().strftime(format_str)
            @staticmethod
            def Now():
                return time.time()
            @staticmethod
            def Sleep(seconds):
                time.sleep(seconds)
        return TimeModule()

    def _get_vsram_module(self):
        """Return VSRAM module proxy from runtime"""
        if self.runtime and hasattr(self.runtime, '_modules'):
            return self.runtime._modules.get('VSRam') or self.runtime._modules.get('VSRAM')
        return None

    def _get_kernel_module(self):
        """Return Kernel module proxy from runtime"""
        if self.runtime and hasattr(self.runtime, '_modules'):
            return self.runtime._modules.get('Kernel') or self.runtime._modules.get('KernelClient')
        return None

    # NEW: Platform Detection Functions
    def builtin_islinux(self) -> bool:
        """Check if running on Linux"""
        import platform
        return platform.system() == 'Linux'

    def builtin_iswindows(self) -> bool:
        """Check if running on Windows"""
        import platform
        return platform.system() == 'Windows'

    def builtin_ismac(self) -> bool:
        """Check if running on macOS"""
        import platform
        return platform.system() == 'Darwin'

    # NEW: CurrentTime function
    def builtin_currenttime(self, format_str: str = '%Y-%m-%d %H:%M:%S') -> str:
        """Get current time as formatted string"""
        return datetime.now().strftime(format_str)

    # NEW: Global function for scope promotion
    def builtin_global(self, s_ref: Any) -> None:
        """
        Promote s@<name> to @<name> (make globally accessible)
        Usage: global(s@cache) - makes @cache available

        This takes the value referenced by s@<name> and registers it
        as a module reference accessible via @<name>
        """
        if not self.runtime:
            return

        # The argument could be:
        # 1. A direct value from s@<name> reference
        # 2. A string path like "MyStruct.cache"

        if isinstance(s_ref, str):
            # It's a path - promote it
            self.runtime.promote_to_global(s_ref)
        else:
            # It's a value - we need the original s@<name> reference
            # This is handled by the runtime which passes the path
            pass

    # ============= CSSL Data Type Constructors =============

    def builtin_datastruct(self, element_type: str = 'dynamic') -> Any:
        """Create a datastruct container.

        Usage: datastruct<string> myData; or datastruct('string')
        """
        from .cssl_types import DataStruct
        return DataStruct(element_type)

    def builtin_shuffled(self, element_type: str = 'dynamic') -> Any:
        """Create a shuffled container for multiple returns.

        Usage: shuffled<string> results;
        """
        from .cssl_types import Shuffled
        return Shuffled(element_type)

    def builtin_iterator(self, element_type: str = 'int', size: int = 16) -> Any:
        """Create an advanced iterator.

        Usage: iterator<int, 16> Map;
        """
        from .cssl_types import Iterator
        return Iterator(element_type, size)

    def builtin_combo(self, element_type: str = 'dynamic') -> Any:
        """Create a combo filter/search space.

        Usage: combo<open&string> myCombo;
        """
        from .cssl_types import Combo
        return Combo(element_type)

    def builtin_dataspace(self, space_type: str = 'dynamic') -> Any:
        """Create a dataspace for SQL/structured data.

        Usage: dataspace<sql::table> table;
        """
        from .cssl_types import DataSpace
        return DataSpace(space_type)

    def builtin_openquote(self, db_ref: Any = None) -> Any:
        """Create an openquote container for SQL operations.

        Usage: openquote<datastruct<dynamic>&@sql::db.oqt(@db)> Queue;
        """
        from .cssl_types import OpenQuote
        return OpenQuote(db_ref)

    def builtin_openfind(self, combo_or_type: Any, index: int = 0) -> Any:
        """Find open parameter by type or combo space.

        Usage: OpenFind<string>(0) or OpenFind(&@comboSpace)
        """
        from .cssl_types import Combo

        if isinstance(combo_or_type, Combo):
            return combo_or_type.find_match([])
        return None


# Module-level convenience functions
_default_builtins: Optional[CSSLBuiltins] = None


def get_builtins(runtime=None) -> CSSLBuiltins:
    """Get default builtins instance"""
    global _default_builtins
    if _default_builtins is None or runtime is not None:
        _default_builtins = CSSLBuiltins(runtime)
    return _default_builtins


def call_builtin(name: str, *args, **kwargs) -> Any:
    """Call a builtin function"""
    return get_builtins().call(name, *args, **kwargs)
