joyfl 0.4__tar.gz

joyfl-0.4/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.3
+Name: joyfl
+Version: 0.4
+Summary: A minimal but elegant dialect of Joy, a functional / concatenative stack language.
+Requires-Dist: click
+Requires-Dist: lark
+Requires-Dist: pytest ; extra == 'test'
+Requires-Python: >=3.10
+Provides-Extra: test
+Description-Content-Type: text/x-rst
+
+``joyfl`` (pronounced *ˈjȯi-fəl*) is a dialect of the programming language Joy.
+
+Joy is a stack-based programming environment that's both functional and concatenative, which results in highly expressive but short programs.  ``joyfl`` is an implementation of Joy in Python in its early stages; it's not entirely backwards compatible by design. 
+
+
+EXAMPLES
+========
+
+You can run a simple REPL (read-eval-print loop) by typing: ``python3 joyfl.py repl``.  From there, try typing these statements:
+
+.. code-block:: bash
+
+    # Take the number one, the number two, add them. Then the number three and add it to the
+    # previous result. Is six equal to that?
+    1 2 + 3 +
+        6 equal? .
+    >>> true
+
+    # Take the list of numbers seven eight nine. Take a program that subtracts one. Map the
+    # program onto the list, then reverse it.
+    [7 8 9] [1 -] map reverse .
+    >>> [8 7 6]
+
+    # Take a list of symbols 'a 'b 'c. Take the symbol 'd. Swap the symbol with the list. Get
+    # the "rest" of the list omitting the first item. Construct a new list with "cons" that
+    # uses 'd as the new head.
+    ['a 'b 'c] 'd swap rest cons .
+    >>> ['d 'b 'c]
+
+Also look at the ``#/examples/`` folder and run them with ``python3 joyfl.py <filename>``.
+
+
+MOTIVATION
+==========
+
+While it's fun to implement languages, this project has particular #ML / #LLM research questions in mind...
+
+    **“ What if there was a language for a 'micro-controller' able to process 99% of tokens? ”**
+
+📥 TRAINING: To produce training data, what's the middle ground between a web-template (gasp!) and a synthetic theorem generator (whew!)?  The answer looks more like another language than a hacked-together Python script.
+
+📤 INFERENCE: For output tokens, how can we make sure prompts are followed, any arithmetic is correct, no items are missed, and formatting is right?  The solution isn't more Python but special tokens that can be interpreted as instructions...
+
+The research goal of this project is to find out where and how Joy can shine in these cases!
+
+
+DIFFERENCES
+===========
+
+While some of the tests from the original Joy pass, many also do not.  Here are the design decisions at play:
+
+1. **Symbols vs. Characters** — Individual byte characters are not supported, so it's not possible to extract or combine them with strings.  Instead, the single quote denotes symbols (e.g. ``'alpha``) that can only be compared and added to containers.
+
+2. **Data-Structures** — Sets are not implemented yet, but will be. When they are, the sets will have the functionality of the underlying Python sets. Lists too behave like Python lists.  Dictionaries will likely follow too at some point.
+
+3. **Conditionals** — Functions that return booleans are encouraged to use the ``?`` suffix, for example ``equal?`` or ``list?``.  This change is inspired by Factor, and makes the code more readable so you know when to expect a boolean.
+
+4. **Stackless** - The interpreter does not use the Python callstack: state is stored entirely in data-structures. There's a stack (for data created in the past) and a queue (for code to be executed in the future).  Certain advanced combinators may feel a bit different to write because of this!
+
+
+REFERENCES
+==========
+
+* The `official documentation <https://hypercubed.github.io/joy/joy.html>`__ for Joy by Manfred van Thun.
+
+* The `various C implementations <https://github.com/Wodan58>`__ (joy0, joy1) by Ruurd Wiersma.
+
+* Python implementations, specifically `Joypy <https://github.com/ghosthamlet/Joypy>`__ by @ghosthamlet.
+
+* An entire `book chapter <https://github.com/nickelsworth/sympas/blob/master/text/18-minijoy.org>`_ implementing Joy in Pascal.

joyfl-0.4/README.rst

@@ -0,0 +1,70 @@
+``joyfl`` (pronounced *ˈjȯi-fəl*) is a dialect of the programming language Joy.
+
+Joy is a stack-based programming environment that's both functional and concatenative, which results in highly expressive but short programs.  ``joyfl`` is an implementation of Joy in Python in its early stages; it's not entirely backwards compatible by design. 
+
+
+EXAMPLES
+========
+
+You can run a simple REPL (read-eval-print loop) by typing: ``python3 joyfl.py repl``.  From there, try typing these statements:
+
+.. code-block:: bash
+
+    # Take the number one, the number two, add them. Then the number three and add it to the
+    # previous result. Is six equal to that?
+    1 2 + 3 +
+        6 equal? .
+    >>> true
+
+    # Take the list of numbers seven eight nine. Take a program that subtracts one. Map the
+    # program onto the list, then reverse it.
+    [7 8 9] [1 -] map reverse .
+    >>> [8 7 6]
+
+    # Take a list of symbols 'a 'b 'c. Take the symbol 'd. Swap the symbol with the list. Get
+    # the "rest" of the list omitting the first item. Construct a new list with "cons" that
+    # uses 'd as the new head.
+    ['a 'b 'c] 'd swap rest cons .
+    >>> ['d 'b 'c]
+
+Also look at the ``#/examples/`` folder and run them with ``python3 joyfl.py <filename>``.
+
+
+MOTIVATION
+==========
+
+While it's fun to implement languages, this project has particular #ML / #LLM research questions in mind...
+
+    **“ What if there was a language for a 'micro-controller' able to process 99% of tokens? ”**
+
+📥 TRAINING: To produce training data, what's the middle ground between a web-template (gasp!) and a synthetic theorem generator (whew!)?  The answer looks more like another language than a hacked-together Python script.
+
+📤 INFERENCE: For output tokens, how can we make sure prompts are followed, any arithmetic is correct, no items are missed, and formatting is right?  The solution isn't more Python but special tokens that can be interpreted as instructions...
+
+The research goal of this project is to find out where and how Joy can shine in these cases!
+
+
+DIFFERENCES
+===========
+
+While some of the tests from the original Joy pass, many also do not.  Here are the design decisions at play:
+
+1. **Symbols vs. Characters** — Individual byte characters are not supported, so it's not possible to extract or combine them with strings.  Instead, the single quote denotes symbols (e.g. ``'alpha``) that can only be compared and added to containers.
+
+2. **Data-Structures** — Sets are not implemented yet, but will be. When they are, the sets will have the functionality of the underlying Python sets. Lists too behave like Python lists.  Dictionaries will likely follow too at some point.
+
+3. **Conditionals** — Functions that return booleans are encouraged to use the ``?`` suffix, for example ``equal?`` or ``list?``.  This change is inspired by Factor, and makes the code more readable so you know when to expect a boolean.
+
+4. **Stackless** - The interpreter does not use the Python callstack: state is stored entirely in data-structures. There's a stack (for data created in the past) and a queue (for code to be executed in the future).  Certain advanced combinators may feel a bit different to write because of this!
+
+
+REFERENCES
+==========
+
+* The `official documentation <https://hypercubed.github.io/joy/joy.html>`__ for Joy by Manfred van Thun.
+
+* The `various C implementations <https://github.com/Wodan58>`__ (joy0, joy1) by Ruurd Wiersma.
+
+* Python implementations, specifically `Joypy <https://github.com/ghosthamlet/Joypy>`__ by @ghosthamlet.
+
+* An entire `book chapter <https://github.com/nickelsworth/sympas/blob/master/text/18-minijoy.org>`_ implementing Joy in Pascal.

joyfl-0.4/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires=["uv_build"]
+build-backend = "uv_build"
+
+[project]
+name = "joyfl"
+version = "0.4"
+description = "A minimal but elegant dialect of Joy, a functional / concatenative stack language."
+readme = { file = "README.rst", content-type = "text/x-rst" }
+requires-python = ">=3.10"
+dependencies = [
+    "click",
+    "lark",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+]
+
+[project.scripts]
+joyfl = "joyfl.__main__:main"

joyfl-0.4/src/joyfl/__init__.py

@@ -0,0 +1,3 @@
+## Copyright © 2025, Alex J. Champandard.  Licensed under AGPLv3; see LICENSE! ⚘
+
+__version__ = "0.4"

joyfl-0.4/src/joyfl/__main__.py

@@ -0,0 +1,124 @@
+## Copyright © 2025, Alex J. Champandard.  Licensed under AGPLv3; see LICENSE! ⚘
+#
+# joyfl — A minimal but elegant dialect of Joy, functional / concatenative stack language.
+#
+
+import sys
+import time
+import traceback
+from pathlib import Path
+
+import click
+
+from .types import nil
+from .errors import JoyError, JoyParseError, JoyNameError, JoyIncompleteParse, JoyAssertionError, JoyImportError
+from .parser import format_parse_error_context, print_source_lines, format_source_lines
+from .formatting import write_without_ansi, format_item, show_stack
+
+from . import api as J
+
+
+@click.command()
+@click.argument('files', nargs=-1, type=click.File('r'))
+@click.option('--command', '-c', 'commands', multiple=True, type=str, help='Execute Joy code from command line.')
+@click.option('--repl', is_flag=True, help='Start REPL after executing commands and files.')
+@click.option('--verbose', '-v', default=0, count=True, help='Enable verbose interpreter execution.')
+@click.option('--validate', is_flag=True, help='Enable type and stack validation before each operation.')
+@click.option('--ignore', '-i', is_flag=True, help='Ignore errors and continue executing.')
+@click.option('--stats', is_flag=True, help='Display execution statistics (e.g., number of steps).')
+@click.option('--plain', '-p', is_flag=True, help='Strip ANSI color codes and redirect stderr to stdout.')
+def main(files: tuple, commands: tuple, repl: bool, verbose: int, validate: bool, ignore: bool, stats: bool, plain: bool):
+
+    if plain is True:
+        writer = write_without_ansi(sys.stdout.write)
+        sys.stdout.write, sys.stderr.write = writer, writer
+    failure = False
+
+    def _maybe_fatal_error(message: str, detail: str, exc_type: str = None, context: str = '', is_repl=False):
+        header = detail if not exc_type else f"{detail} (Exception: \033[33m{exc_type}\033[0m)"
+        print(f'\033[30;43m {message} \033[0m {header}\n{context}', file=sys.stderr)
+        if not is_repl and not ignore: sys.exit(1)
+
+    def _handle_exception(exc, filename, source, is_repl=False):
+        if isinstance(exc, JoyParseError):
+            if is_repl and isinstance(exc, JoyIncompleteParse): return True
+            context = format_parse_error_context(filename, exc.line, exc.column, exc.token, source=source)
+            context += f"\n\033[90m{str(exc).replace(chr(10), ' ').replace(chr(9), ' ')}\033[0m\n"
+            _maybe_fatal_error("SYNTAX ERROR.", f"Parsing `\033[97m{filename}\033[0m` caused a problem!", type(exc).__name__, context, is_repl)
+        elif isinstance(exc, JoyNameError):
+            detail = f"Term `\033[1;97m{exc.joy_op}\033[0m` from `\033[97m{filename}\033[0m` was not found in library!"
+            context = '\n' + format_source_lines(exc.joy_meta, exc.joy_op)
+            _maybe_fatal_error("LINKER ERROR.", detail, type(exc).__name__, context, is_repl)
+        elif isinstance(exc, JoyAssertionError):
+            print(f'\033[30;43m ASSERTION FAILED. \033[0m Function \033[1;97m`{exc.joy_op}`\033[0m raised an error.\n', file=sys.stderr)
+            print_source_lines(exc.joy_op, J.library.quotations, file=sys.stderr)
+            print(f'\033[1;33m  Stack content is\033[0;33m\n    ', end='', file=sys.stderr)
+            show_stack(exc.joy_stack, width=None, file=sys.stderr); print('\033[0m', file=sys.stderr)
+            if not is_repl and not ignore: sys.exit(1)
+        elif isinstance(exc, JoyImportError):
+            detail = f"Importing library module failed while resolving `{exc.joy_op}`: \033[97m{exc.filename}\033[0m"
+            context = '\n' + format_source_lines(exc.joy_meta, exc.joy_op)
+            _maybe_fatal_error("IMPORT ERROR.", detail, type(exc).__name__, context, is_repl)
+        elif isinstance(exc, Exception):
+            print(f'\033[30;43m RUNTIME ERROR. \033[0m Function \033[1;97m`{exc.joy_op}`\033[0m caused an error in interpret! (Exception: \033[33m{type(exc).__name__}\033[0m)\n', file=sys.stderr)
+            tb_lines = traceback.format_exc().split('\n')
+            print(*[line for line in tb_lines if 'lambda' in line], sep='\n', end='\n', file=sys.stderr)
+            print_source_lines(exc.joy_op, J.library.quotations, file=sys.stderr)
+            traceback.print_exc()
+            if not is_repl and not ignore: sys.exit(1)
+        return False
+
+    base = Path(__file__).resolve().parent
+    candidates = (d / 'libs' / 'stdlib.joy' for d in (base, *base.parents[:2]))
+    stdlib_path = next((p for p in candidates if p.exists()), Path('libs/stdlib.joy'))
+    J.load(stdlib_path.read_text(encoding='utf-8'), filename='libs/stdlib.joy', validate=validate)
+
+    # Build execution list: files first, then commands.
+    items = [(f.read(), f.name) for f in files]
+    items += [(cmd, f'<INPUT_{i+1}>') for i, cmd in enumerate(commands)]
+
+    total_stats = {'steps': 0, 'start': time.time()} if stats else None
+    for source, filename in items:
+        try:
+            r = J.run(source, filename=filename, verbosity=verbose, validate=validate, stats=total_stats)
+            (r is None and ((failure := True) or (not ignore and sys.exit(1))))
+        except (JoyError, Exception) as exc:
+            _handle_exception(exc, filename, source, is_repl=False)
+
+    if total_stats and len(items) > 0:
+        elapsed_time = time.time() - total_stats['start']
+        print(f"\n\033[97m\033[48;5;30m STATISTICS. \033[0m")
+        print(f"step\t\033[97m{total_stats['steps']:,}\033[0m")
+        print(f"time\t\033[97m{elapsed_time:.3f}s\033[0m")
+
+    # Start REPL if no items were provided or --repl flag was set
+    if len(items) == 0 or repl:
+        if sys.platform != "win32": import readline
+
+        print('joyfl - Functional stack language REPL; type Ctrl+C to exit.')
+        source = ""
+
+        while True:
+            try:
+                prompt = "\033[36m<<< \033[0m" if not source.strip() else "\033[36m... \033[0m"
+                line = input(prompt)
+                if len(line.strip()) == 0: continue
+                if line.strip() in ('quit', 'exit'): break
+                source += line + " "
+
+                try:
+                    stack = J.run(source, filename='<REPL>', verbosity=verbose, validate=validate)
+                    if stack is not nil: print("\033[90m>>>\033[0m", format_item(stack[-1]))
+                    source = ""
+                except (JoyError, Exception) as exc:
+                    if not _handle_exception(exc, '<REPL>', source, is_repl=True):
+                        source = ""
+
+            except (KeyboardInterrupt, EOFError):
+                print(""); break
+
+    sys.exit(failure)
+
+
+if __name__ == "__main__":
+    main()

joyfl-0.4/src/joyfl/api.py

@@ -0,0 +1,10 @@
+## joyfl — Copyright © 2025, Alex J. Champandard.  Licensed under AGPLv3; see LICENSE! ⚘
+
+from .types import Operation, Stack, nil
+from .errors import *
+from .runtime import Runtime
+
+_RUNTIME = Runtime()
+
+def __getattr__(name):
+    return getattr(_RUNTIME, name)

joyfl-0.4/src/joyfl/builtins.py

@@ -0,0 +1,44 @@
+## Copyright © 2025, Alex J. Champandard.  Licensed under AGPLv3; see LICENSE! ⚘
+
+from .library import Library
+from . import operators
+from .combinators import comb_i, comb_dip, comb_step, comb_cont
+
+
+def _joy_name_from_python(py_name: str) -> str:
+    # py_name like 'op_equal_q' -> 'equal?'; 'op_put_b' -> 'put!'; underscores -> dashes
+    base = py_name[3:]
+    base = base.replace('_q', '?').replace('_b', '!')
+    return base.replace('_', '-')
+
+
+def load_builtins_library():
+    # Combinators
+    combinators = {
+        'i': comb_i,
+        'dip': comb_dip,
+        'step': comb_step,
+        ',,,': comb_cont,
+    }
+    quotations = {}
+    constants = {'true': True, 'false': False}
+    factories = {}
+    aliases = {
+        '+': 'add', '-': 'sub', '*': 'mul', '/': 'div', '%': 'rem',
+        '>': 'gt', '>=': 'gte', '<': 'lt', '<=': 'lte',
+        '=': 'equal?', '!=': 'differ?', 'size': 'length',
+    }
+
+    lib = Library(functions={}, combinators=combinators, quotations=quotations, constants=constants, factories=factories, aliases=aliases)
+
+    # Functions (wrapped via Library helper)
+    for k in dir(operators):
+        if not k.startswith('op_'):
+            continue
+        joy = _joy_name_from_python(k)
+        lib.add_function(joy, getattr(operators, k))
+
+    lib.ensure_consistent()
+    return lib
+
+

joyfl-0.4/src/joyfl/combinators.py

@@ -0,0 +1,58 @@
+## Copyright © 2025, Alex J. Champandard.  Licensed under AGPLv3; see LICENSE! ⚘
+#
+# joyfl — A minimal but elegant dialect of Joy, functional / concatenative stack language.
+#
+
+from .types import Operation
+from .parser import parse
+from .formatting import show_stack
+
+
+def comb_i(_, queue, tail, head, lib):
+    """Takes a program as quotation on the top of the stack, and puts it into the queue for execution."""
+    assert isinstance(head, (list, tuple))
+    queue.extendleft(reversed(head))
+    return tail
+
+def comb_dip(_, queue, *stack, lib):
+    """Schedules a program for execution like `i`, but removes the second top-most item from the stack too
+    and then restores it after the program is done.  This is like running `i` one level lower in the stack.
+    """
+    ((tail, item), head) = stack
+    assert isinstance(head, list)
+    queue.appendleft(item)
+    queue.extendleft(reversed(head))
+
+    return tail
+
+def comb_step(this: Operation, queue, *stack, lib):
+    """Applies a program to every item in a list in a recursive fashion.  `step` expands into another
+    quotation that includes itself to run on the rest of the list, after the program was applied to the
+    head of the list.
+    """
+    (tail, values), program = stack
+    assert isinstance(program, list) and isinstance(values, list)
+    if len(values) == 0: return tail
+    queue.extendleft(reversed([values[0]] + program + [values[1:], program, this]))
+    return tail
+
+def comb_cont(this: Operation, queue, *stack, lib):
+    from .linker import link_body
+
+    print(f"\033[97m  ~ :\033[0m  ", end=''); show_stack(stack, width=72, end='')
+    try:
+        program = []
+        value = input("\033[4 q\033[36m  ...  \033[0m")
+        if value.strip():
+            for typ, data in parse(value, start='term'):
+                program, _ = link_body(data, meta={'filename': '<REPL>', 'lines': (1, 1)}, globals_=lib)
+    except Exception as e:
+        print('EXCEPTION: comb_cont could not parse or compile the text.', e)
+        import traceback; traceback.print_exc(limit=2)
+    finally:
+        print("\033[0 q", end='')
+
+    if program:
+        queue.extendleft(reversed(program + [this]))
+    return stack
+

joyfl-0.4/src/joyfl/errors.py

@@ -0,0 +1,40 @@
+## Copyright © 2025, Alex J. Champandard.  Licensed under AGPLv3; see LICENSE! ⚘
+
+import lark
+
+
+class JoyError(Exception):
+    def __init__(self, message: str = "", *, joy_op=None, joy_meta=None):
+        super().__init__(message)
+        self.joy_op = joy_op
+        self.joy_meta = joy_meta
+
+class JoyParseError(JoyError):
+    def __init__(self, message, *, filename=None, line=None, column=None, token=None):
+        super().__init__(message)
+        self.filename = filename
+        self.line = line
+        self.column = column
+        self.token = token
+
+class JoyIncompleteParse(JoyParseError, lark.exceptions.ParseError):
+    def __init__(self, message, *, filename=None, line=None, column=None, token=None):
+        super().__init__(message, filename=filename, line=line, column=column, token=token)
+
+class JoyNameError(JoyError, NameError):
+    pass
+
+class JoyRuntimeError(JoyError, RuntimeError):
+    pass
+
+class JoyAssertionError(JoyError, AssertionError):
+    pass
+
+
+class JoyImportError(JoyError, ImportError):
+    def __init__(self, message, *, joy_op=None, filename=None, joy_meta=None):
+        super().__init__(message, joy_op=joy_op, joy_meta=joy_meta)
+        self.filename = filename
+
+class JoyModuleError(JoyImportError):
+    pass

joyfl-0.4/src/joyfl/formatting.py

@@ -0,0 +1,62 @@
+## Copyright © 2025, Alex J. Champandard.  Licensed under AGPLv3; see LICENSE! ⚘
+#
+# joyfl — A minimal but elegant dialect of Joy, functional / concatenative stack language.
+#
+
+import re
+import sys
+
+from .types import stack_list, Stack, nil
+
+
+def stack_to_list(stk: Stack) -> stack_list:
+    result = []
+    while stk is not nil:
+        stk, head = stk
+        result.append(head)
+    return stack_list(result)
+
+def list_to_stack(values: list, base=None) -> Stack:
+    stack = nil if base is None else base
+    for value in reversed(values):
+        stack = Stack(stack, value)
+    return stack
+
+
+def write_without_ansi(write_fn):
+    """Wrapper function that strips ANSI codes before calling the original writer."""
+    ansi_re = re.compile(r'\033\[[0-9;]*m')
+    return lambda text: write_fn(ansi_re.sub('', text))
+
+def format_item(it, width=None, indent=0):
+    if (is_stack := isinstance(it, stack_list)) or isinstance(it, list):
+        items = reversed(it) if is_stack else it
+        lhs, rhs = ('<', '>') if is_stack else ('[', ']')
+        formatted_items = [format_item(i, width, indent + 4) for i in items]
+        single_line = lhs + ' '.join(formatted_items) + rhs
+        # If it fits on one line, use single line format.
+        if width is None or len(single_line) + indent <= width: return single_line
+        # Otherwise use multi-line format...
+        result = lhs + '   '
+        for i, item in enumerate(formatted_items):
+            if i > 0: result += '\n' + (' ' * (indent + 4))
+            result += item
+        result += '\n' + (' ' * indent) + rhs
+        return result
+    if isinstance(it, str) and indent > 0: return f'"{it.replace(chr(34), chr(92)+chr(34))}"'
+    if isinstance(it, bool): return str(it).lower()
+    if isinstance(it, bytes): return str(it)[1:-1]
+    return str(it)
+
+def show_stack(stack, width=72, end='\n', file=None):
+    stack_str = ' '.join(format_item(s) for s in reversed(stack_to_list(stack))) if stack is not nil else '∅'
+    if len(stack_str) > (width or sys.maxsize):
+        stack_str = '… ' + stack_str[-width+2:]
+    print(f"{stack_str:>{width}}" if width else stack_str, end=end, file=file)
+
+def show_program_and_stack(program, stack, width=72):
+    prog_str = ' '.join(format_item(p) for p in program) if program else '∅'
+    if len(prog_str) > width:
+        prog_str = prog_str[:+width-2] + ' …'
+    show_stack(stack, end='')
+    print(f" \033[36m <=> \033[0m {prog_str:<{width}}")

joyfl-0.4/src/joyfl/interpreter.py

@@ -0,0 +1,123 @@
+## Copyright © 2025, Alex J. Champandard.  Licensed under AGPLv3; see LICENSE! ⚘
+#
+# joyfl — A minimal but elegant dialect of Joy, functional / concatenative stack language.
+#
+
+import sys
+import traceback
+import collections
+
+from typing import Any, TypeVar
+
+from .types import Operation, Stack, nil
+from .parser import print_source_lines
+from .library import Library
+from .formatting import show_stack, show_program_and_stack, stack_to_list
+
+
+def can_execute(op: Operation, stack: Stack) -> tuple[bool, str]:
+    """Check if operation can execute on stack using inferred stack effects."""
+    # Special cases for combinators and runtime hazards that don't come from signature
+    if op.type == Operation.COMBINATOR and op.name in ("i", "dip"):
+        if stack is nil:
+            return False, f"`{op.name}` needs at least 1 item on the stack, but stack is empty."
+        _, head = stack
+        if not isinstance(head, (list, tuple)):
+            return False, f"`{op.name}` requires a quotation as list as top item on the stack."
+        return True, ""
+
+    # Division by zero guard for division, as binary int/float op.
+    if op.name in ('div', '/') and stack is not nil:
+        _, head = stack
+        if head == 0:
+            return False, f"`{op.name}` would divide by zero and cause a runtime exception."
+
+    if op.type != Operation.FUNCTION: return True, ""
+
+    eff = getattr(op.ptr, '__joy_meta__')
+    inputs = eff['inputs']
+    items = stack_to_list(stack)
+    depth = len(items)
+    if depth < len(inputs):
+        need = len(inputs)
+        return False, f"`{op.name}` needs at least {need} item(s) on the stack, but {depth} available."
+
+    # Type checks from top downward
+    for i, expected_type in enumerate(inputs):
+        if isinstance(expected_type, TypeVar): expected_type = expected_type.__bound__
+        if expected_type in (Any, None): continue
+        actual = items[i]
+        if not isinstance(actual, expected_type):
+            type_name = expected_type.__name__ if hasattr(expected_type, '__name__') else str(expected_type)
+            return False, f"`{op.name}` expects {type_name} at position {i+1} from top, got {type(actual).__name__}."
+
+    # Extra semantic guard for 'index' bounds when types look correct
+    if op.name == 'index' and len(items) >= 2 and isinstance(items[0], (list, str)) and isinstance(items[1], int):
+        idx, seq = items[1], items[0]
+        if not (0 <= int(idx) < len(seq)):
+            return False, f"`{op.name}` would index a list out ouf bounds."
+
+    return True, ""
+
+
+def interpret_step(program, stack, lib: Library):
+    op = program.popleft()
+    if isinstance(op, bytes) and op in (b'ABORT', b'BREAK'):
+        print(f"\033[97m  ~ :\033[0m  ", end=''); show_program_and_stack(program, stack)
+        if op == b'ABORT': sys.exit(-1)
+        if op == b'BREAK': input()
+
+    if not isinstance(op, Operation):
+        stack = Stack(stack, op)
+        return stack, program
+
+    match op.type:
+        case Operation.FUNCTION:
+            stack = op.ptr(stack)
+        case Operation.COMBINATOR:
+            stack = op.ptr(op, program, *stack, lib=lib)
+        case Operation.EXECUTE:
+            program.extendleft(reversed(op.ptr))
+
+    return stack, program
+
+
+def interpret(program: list, stack=None, lib: Library = None, verbosity=0, validate=False, stats=None):
+    stack = nil if stack is None else stack
+    program = collections.deque(program)
+
+    def is_notable(op):
+        if not isinstance(op, Operation): return False
+        return isinstance(op.ptr, list) or op.type == Operation.COMBINATOR
+
+    step = 0
+    while program:
+        if validate and isinstance(program[0], Operation):
+            if (check := can_execute(program[0], stack)) and not check[0]:
+                print(f'\033[30;43m TYPE ERROR. \033[0m {check[1]}\n', file=sys.stderr)
+                print(f'\033[1;33m  Stack content is\033[0;33m\n    ', end='', file=sys.stderr)
+                show_stack(stack, width=None, file=sys.stderr)
+                print('\033[0m', file=sys.stderr)
+                print_source_lines(program[0], lib.quotations, file=sys.stderr)
+                break
+        
+        if verbosity == 2 or (verbosity == 1 and (is_notable(program[0]) or step == 0)):
+            print(f"\033[90m{step:>3} :\033[0m  ", end='')
+            show_program_and_stack(program, stack)
+
+        step += 1
+        try:
+            op = program[0]
+            stack, program = interpret_step(program, stack, lib)
+        except Exception as exc:
+            exc.joy_op = op
+            exc.joy_stack = stack
+            raise
+
+    if verbosity > 0:
+        print(f"\033[90m{step:>3} :\033[0m  ", end='')
+        show_program_and_stack(program, stack)
+    if stats is not None:
+        stats['steps'] = stats.get('steps', 0) + step
+
+    return stack