tinyvm-Flaxot 0.1.0__tar.gz

tinyvm_flaxot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tinyvm contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tinyvm_flaxot-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+recursive-include src *.c *.h
+recursive-include tests *.c *.py

tinyvm_flaxot-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: tinyvm-Flaxot
+Version: 0.1.0
+Summary: A small C-powered stack-based bytecode virtual machine.
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file

tinyvm_flaxot-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tinyvm-Flaxot"
+version = "0.1.0"
+description = "A small C-powered stack-based bytecode virtual machine."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: C",
+  "Programming Language :: Python :: Implementation :: CPython"
+]
+
+
+[tool.cibuildwheel]
+build = "cp311-* cp312-* cp313-* cp314-*"
+skip = "*-win32 *-manylinux_i686 *-musllinux_*"
+test-requires = ["pytest"]
+test-command = "pytest {project}/tests"
+build-verbosity = 1
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tinyvm_flaxot-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tinyvm_flaxot-0.1.0/setup.py

@@ -0,0 +1,17 @@
+from setuptools import Extension, setup
+
+extension = Extension(
+    name="tinyvm._native",
+    sources=[
+        "src/python/module.c",
+        "src/core/value.c",
+        "src/core/stack.c",
+        "src/core/vm.c",
+    ],
+    include_dirs=["src/core"],
+)
+
+setup(
+    packages=["tinyvm"],
+    ext_modules=[extension],
+)

tinyvm_flaxot-0.1.0/src/core/main.c

@@ -0,0 +1,26 @@
+#include <stdio.h>
+
+#include "stack.h"
+#include "value.h"
+
+int main(void)
+{
+    TinyStack stack;
+    TinyValue value;
+
+    if (tiny_stack_init(&stack, 8) != TINY_STACK_OK) {
+        fprintf(stderr, "Could not initialize stack.\n");
+        return 1;
+    }
+
+    tiny_stack_push(&stack, tiny_value_from_i64(10));
+    tiny_stack_push(&stack, tiny_value_from_i64(20));
+    tiny_stack_dup(&stack);
+
+    while (tiny_stack_pop(&stack, &value) == TINY_STACK_OK) {
+        printf("%lld\n", (long long)tiny_value_as_i64(value));
+    }
+
+    tiny_stack_destroy(&stack);
+    return 0;
+}

tinyvm_flaxot-0.1.0/src/core/opcode.h

@@ -0,0 +1,27 @@
+#ifndef TINYVM_OPCODE_H
+#define TINYVM_OPCODE_H
+
+#include <stdint.h>
+
+typedef enum {
+    TINY_OP_PUSH_I64 = 0x01,
+    TINY_OP_POP      = 0x02,
+    TINY_OP_DUP      = 0x03,
+    TINY_OP_ADD      = 0x10,
+    TINY_OP_SUB      = 0x11,
+    TINY_OP_MUL      = 0x12,
+    TINY_OP_DIV      = 0x13,
+    TINY_OP_MOD      = 0x14,
+    TINY_OP_EQ       = 0x20,
+    TINY_OP_GT       = 0x21,
+    TINY_OP_LT       = 0x22,
+    TINY_OP_JMP      = 0x30,
+    TINY_OP_JZ       = 0x31,
+    TINY_OP_PRINT    = 0x40,
+    TINY_OP_HALT     = 0xFF
+} TinyOpcode;
+
+#define TINYVM_I64_OPERAND_SIZE 8u
+#define TINYVM_JUMP_OPERAND_SIZE 4u
+
+#endif

tinyvm_flaxot-0.1.0/src/core/stack.c

@@ -0,0 +1,79 @@
+#include "stack.h"
+
+#include <stdlib.h>
+
+TinyStackStatus tiny_stack_init(TinyStack *stack, size_t capacity)
+{
+    if (stack == NULL || capacity == 0) {
+        return TINY_STACK_INVALID_ARGUMENT;
+    }
+
+    stack->items = (TinyValue *)calloc(capacity, sizeof(TinyValue));
+    if (stack->items == NULL) {
+        stack->size = 0;
+        stack->capacity = 0;
+        return TINY_STACK_INVALID_ARGUMENT;
+    }
+
+    stack->size = 0;
+    stack->capacity = capacity;
+    return TINY_STACK_OK;
+}
+
+void tiny_stack_destroy(TinyStack *stack)
+{
+    if (stack == NULL) {
+        return;
+    }
+    free(stack->items);
+    stack->items = NULL;
+    stack->size = 0;
+    stack->capacity = 0;
+}
+
+TinyStackStatus tiny_stack_push(TinyStack *stack, TinyValue value)
+{
+    if (stack == NULL || stack->items == NULL) {
+        return TINY_STACK_INVALID_ARGUMENT;
+    }
+    if (stack->size >= stack->capacity) {
+        return TINY_STACK_OVERFLOW;
+    }
+    stack->items[stack->size++] = value;
+    return TINY_STACK_OK;
+}
+
+TinyStackStatus tiny_stack_pop(TinyStack *stack, TinyValue *out_value)
+{
+    if (stack == NULL || out_value == NULL || stack->items == NULL) {
+        return TINY_STACK_INVALID_ARGUMENT;
+    }
+    if (stack->size == 0) {
+        return TINY_STACK_UNDERFLOW;
+    }
+    *out_value = stack->items[--stack->size];
+    return TINY_STACK_OK;
+}
+
+TinyStackStatus tiny_stack_peek(const TinyStack *stack, TinyValue *out_value)
+{
+    if (stack == NULL || out_value == NULL || stack->items == NULL) {
+        return TINY_STACK_INVALID_ARGUMENT;
+    }
+    if (stack->size == 0) {
+        return TINY_STACK_UNDERFLOW;
+    }
+    *out_value = stack->items[stack->size - 1];
+    return TINY_STACK_OK;
+}
+
+TinyStackStatus tiny_stack_dup(TinyStack *stack)
+{
+    TinyValue value;
+    TinyStackStatus status = tiny_stack_peek(stack, &value);
+
+    if (status != TINY_STACK_OK) {
+        return status;
+    }
+    return tiny_stack_push(stack, value);
+}

tinyvm_flaxot-0.1.0/src/core/stack.h

@@ -0,0 +1,27 @@
+#ifndef TINYVM_STACK_H
+#define TINYVM_STACK_H
+
+#include <stddef.h>
+#include "value.h"
+
+typedef enum {
+    TINY_STACK_OK = 0,
+    TINY_STACK_UNDERFLOW,
+    TINY_STACK_OVERFLOW,
+    TINY_STACK_INVALID_ARGUMENT
+} TinyStackStatus;
+
+typedef struct {
+    TinyValue *items;
+    size_t size;
+    size_t capacity;
+} TinyStack;
+
+TinyStackStatus tiny_stack_init(TinyStack *stack, size_t capacity);
+void tiny_stack_destroy(TinyStack *stack);
+TinyStackStatus tiny_stack_push(TinyStack *stack, TinyValue value);
+TinyStackStatus tiny_stack_pop(TinyStack *stack, TinyValue *out_value);
+TinyStackStatus tiny_stack_peek(const TinyStack *stack, TinyValue *out_value);
+TinyStackStatus tiny_stack_dup(TinyStack *stack);
+
+#endif

tinyvm_flaxot-0.1.0/src/core/value.c

@@ -0,0 +1,13 @@
+#include "value.h"
+
+TinyValue tiny_value_from_i64(int64_t value)
+{
+    TinyValue result;
+    result.integer = value;
+    return result;
+}
+
+int64_t tiny_value_as_i64(TinyValue value)
+{
+    return value.integer;
+}

tinyvm_flaxot-0.1.0/src/core/value.h

@@ -0,0 +1,13 @@
+#ifndef TINYVM_VALUE_H
+#define TINYVM_VALUE_H
+
+#include <stdint.h>
+
+typedef struct {
+    int64_t integer;
+} TinyValue;
+
+TinyValue tiny_value_from_i64(int64_t value);
+int64_t tiny_value_as_i64(TinyValue value);
+
+#endif

tinyvm_flaxot-0.1.0/src/core/vm.c

@@ -0,0 +1,468 @@
+#include "vm.h"
+#include "opcode.h"
+#include "stack.h"
+#include "value.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+
+
+
+
+
+
+static int checked_add(int64_t a, int64_t b, int64_t *out)
+{
+    if ((b > 0 && a > INT64_MAX - b) ||
+        (b < 0 && a < INT64_MIN - b)) {
+        return 0;
+    }
+    *out = a + b;
+    return 1;
+}
+
+static int checked_sub(int64_t a, int64_t b, int64_t *out)
+{
+    if ((b < 0 && a > INT64_MAX + b) ||
+        (b > 0 && a < INT64_MIN + b)) {
+        return 0;
+    }
+    *out = a - b;
+    return 1;
+}
+
+static int checked_mul(int64_t a, int64_t b, int64_t *out)
+{
+    if (a == 0 || b == 0) {
+        *out = 0;
+        return 1;
+    }
+    if ((a == -1 && b == INT64_MIN) || (b == -1 && a == INT64_MIN)) {
+        return 0;
+    }
+    if (a > 0) {
+        if ((b > 0 && a > INT64_MAX / b) ||
+            (b < 0 && b < INT64_MIN / a)) {
+            return 0;
+        }
+    } else {
+        if ((b > 0 && a < INT64_MIN / b) ||
+            (b < 0 && a < INT64_MAX / b)) {
+            return 0;
+        }
+    }
+    *out = a * b;
+    return 1;
+}
+
+
+static void set_error(TinyVMError *error, TinyVMStatus code,
+                      size_t offset, const char *message)
+{
+    if (error == NULL) {
+        return;
+    }
+    error->code = code;
+    error->byte_offset = offset;
+    snprintf(error->message, sizeof(error->message), "%s", message);
+}
+
+TinyVMConfig tinyvm_default_config(void)
+{
+    TinyVMConfig config;
+    config.max_stack = 256;
+    config.max_instructions = 100000;
+    return config;
+}
+
+void tinyvm_result_free(TinyVMResult *result)
+{
+    if (result == NULL) {
+        return;
+    }
+    free(result->values);
+    result->values = NULL;
+    result->count = 0;
+}
+
+static size_t operand_size(uint8_t opcode)
+{
+    switch (opcode) {
+        case TINY_OP_PUSH_I64:
+            return TINYVM_I64_OPERAND_SIZE;
+        case TINY_OP_JMP:
+        case TINY_OP_JZ:
+            return TINYVM_JUMP_OPERAND_SIZE;
+        case TINY_OP_POP:
+        case TINY_OP_DUP:
+        case TINY_OP_ADD:
+        case TINY_OP_SUB:
+        case TINY_OP_MUL:
+        case TINY_OP_DIV:
+        case TINY_OP_MOD:
+        case TINY_OP_EQ:
+        case TINY_OP_GT:
+        case TINY_OP_LT:
+        case TINY_OP_PRINT:
+        case TINY_OP_HALT:
+            return 0;
+        default:
+            return (size_t)-1;
+    }
+}
+
+static uint32_t read_u32_le(const uint8_t *p)
+{
+    return (uint32_t)p[0]
+        | ((uint32_t)p[1] << 8)
+        | ((uint32_t)p[2] << 16)
+        | ((uint32_t)p[3] << 24);
+}
+
+static int64_t read_i64_le(const uint8_t *p)
+{
+    uint64_t raw = 0;
+    size_t i;
+
+    for (i = 0; i < 8; i++) {
+        raw |= ((uint64_t)p[i]) << (i * 8);
+    }
+    return (int64_t)raw;
+}
+
+static TinyVMStatus validate_bytecode(const uint8_t *code, size_t length,
+                                      uint8_t **map_out, TinyVMError *error)
+{
+    size_t offset = 0;
+    uint8_t *map;
+
+    if (code == NULL || length == 0 || map_out == NULL) {
+        set_error(error, TINYVM_ERROR_INVALID_ARGUMENT, 0,
+                  "Bytecode must not be empty.");
+        return TINYVM_ERROR_INVALID_ARGUMENT;
+    }
+
+    map = (uint8_t *)calloc(length + 1, 1);
+    if (map == NULL) {
+        set_error(error, TINYVM_ERROR_OUT_OF_MEMORY, 0,
+                  "Could not allocate validation map.");
+        return TINYVM_ERROR_OUT_OF_MEMORY;
+    }
+
+    /* Pass 1: find instruction boundaries, reject bad or truncated ones. */
+    while (offset < length) {
+        size_t extra;
+
+        map[offset] = 1;
+        extra = operand_size(code[offset]);
+
+        if (extra == (size_t)-1) {
+            free(map);
+            set_error(error, TINYVM_ERROR_INVALID_OPCODE, offset,
+                      "Unknown opcode.");
+            return TINYVM_ERROR_INVALID_OPCODE;
+        }
+        if (extra > length - offset - 1) {
+            free(map);
+            set_error(error, TINYVM_ERROR_TRUNCATED_BYTECODE, offset,
+                      "Instruction operand is truncated.");
+            return TINYVM_ERROR_TRUNCATED_BYTECODE;
+        }
+        offset += 1 + extra;
+    }
+
+    /* Pass 2: every jump must land on an instruction boundary. */
+    offset = 0;
+    while (offset < length) {
+        uint8_t op = code[offset];
+
+        if (op == TINY_OP_JMP || op == TINY_OP_JZ) {
+            uint32_t target = read_u32_le(code + offset + 1);
+
+            if ((size_t)target >= length || map[target] == 0) {
+                free(map);
+                set_error(error, TINYVM_ERROR_INVALID_JUMP, offset,
+                          "Jump target is not an instruction boundary.");
+                return TINYVM_ERROR_INVALID_JUMP;
+            }
+        }
+        offset += 1 + operand_size(op);
+    }
+
+    *map_out = map;
+    return TINYVM_OK;
+}
+
+
+
+static int append_output(TinyVMResult *result, size_t *capacity, int64_t value)
+{
+    int64_t *grown;
+    size_t next;
+
+    if (result->count == *capacity) {
+        next = (*capacity == 0) ? 8 : (*capacity * 2);
+        if (next < *capacity || next > ((size_t)-1) / sizeof(int64_t)) {
+            return 0;
+        }
+        grown = (int64_t *)realloc(result->values, next * sizeof(int64_t));
+        if (grown == NULL) {
+            return 0;
+        }
+        result->values = grown;
+        *capacity = next;
+    }
+
+    result->values[result->count++] = value;
+    return 1;
+}
+
+TinyVMStatus tinyvm_execute(
+    const uint8_t *bytecode,
+    size_t bytecode_length,
+    const TinyVMConfig *config_input,
+    TinyVMResult *result,
+    TinyVMError *error
+)
+{
+    TinyVMConfig defaults = tinyvm_default_config();
+    const TinyVMConfig *config = config_input != NULL ? config_input : &defaults;
+    TinyStack stack;
+    uint8_t *boundaries = NULL;
+    size_t ip = 0;
+    size_t output_capacity = 0;
+    uint64_t steps = 0;
+    TinyVMStatus status;
+
+    if (result == NULL) {
+        set_error(error, TINYVM_ERROR_INVALID_ARGUMENT, 0,
+                  "Result pointer is required.");
+        return TINYVM_ERROR_INVALID_ARGUMENT;
+    }
+    result->values = NULL;
+    result->count = 0;
+
+    if (config->max_stack == 0 || config->max_instructions == 0) {
+        set_error(error, TINYVM_ERROR_INVALID_ARGUMENT, 0,
+                  "VM limits must be greater than zero.");
+        return TINYVM_ERROR_INVALID_ARGUMENT;
+    }
+
+    status = validate_bytecode(bytecode, bytecode_length, &boundaries, error);
+    if (status != TINYVM_OK) {
+        return status;
+    }
+
+    if (tiny_stack_init(&stack, config->max_stack) != TINY_STACK_OK) {
+        free(boundaries);
+        set_error(error, TINYVM_ERROR_OUT_OF_MEMORY, 0,
+                  "Could not initialize operand stack.");
+        return TINYVM_ERROR_OUT_OF_MEMORY;
+    }
+
+    while (ip < bytecode_length) {
+        uint8_t op;
+        size_t instruction_offset = ip;
+        TinyValue value;
+
+        if (steps >= config->max_instructions) {
+            status = TINYVM_ERROR_INSTRUCTION_LIMIT;
+            set_error(error, status, ip, "Instruction limit exceeded.");
+            goto failed;
+        }
+        steps++;
+        op = bytecode[ip++];
+
+        switch (op) {
+            case TINY_OP_PUSH_I64:
+                value = tiny_value_from_i64(read_i64_le(bytecode + ip));
+                ip += TINYVM_I64_OPERAND_SIZE;
+                if (tiny_stack_push(&stack, value) != TINY_STACK_OK) {
+                    status = TINYVM_ERROR_STACK_OVERFLOW;
+                    set_error(error, status, instruction_offset,
+                              "Operand stack overflow.");
+                    goto failed;
+                }
+                break;
+
+            case TINY_OP_POP:
+                if (tiny_stack_pop(&stack, &value) != TINY_STACK_OK) {
+                    status = TINYVM_ERROR_STACK_UNDERFLOW;
+                    set_error(error, status, instruction_offset,
+                              "Operand stack underflow.");
+                    goto failed;
+                }
+                break;
+
+            case TINY_OP_DUP:
+                if (tiny_stack_dup(&stack) != TINY_STACK_OK) {
+                    status = stack.size >= stack.capacity
+                        ? TINYVM_ERROR_STACK_OVERFLOW
+                        : TINYVM_ERROR_STACK_UNDERFLOW;
+                    set_error(error, status, instruction_offset,
+                              "DUP failed.");
+                    goto failed;
+                }
+                break;
+
+            case TINY_OP_PRINT:
+                if (tiny_stack_pop(&stack, &value) != TINY_STACK_OK) {
+                    status = TINYVM_ERROR_STACK_UNDERFLOW;
+                    set_error(error, status, instruction_offset,
+                              "PRINT needs a value.");
+                    goto failed;
+                }
+                if (!append_output(result, &output_capacity,
+                                   tiny_value_as_i64(value))) {
+                    status = TINYVM_ERROR_OUT_OF_MEMORY;
+                    set_error(error, status, instruction_offset,
+                              "Output allocation failed.");
+                    goto failed;
+                }
+                break;
+                
+                            case TINY_OP_ADD:
+            case TINY_OP_SUB:
+            case TINY_OP_MUL:
+            case TINY_OP_DIV:
+            case TINY_OP_MOD: {
+                TinyValue left, right;
+                int64_t a, b, answer = 0;
+                int ok = 1;
+
+                if (tiny_stack_pop(&stack, &right) != TINY_STACK_OK ||
+                    tiny_stack_pop(&stack, &left) != TINY_STACK_OK) {
+                    status = TINYVM_ERROR_STACK_UNDERFLOW;
+                    set_error(error, status, instruction_offset,
+                              "Arithmetic needs two values.");
+                    goto failed;
+                }
+
+                a = left.integer;
+                b = right.integer;
+
+                if (op == TINY_OP_ADD) {
+                    ok = checked_add(a, b, &answer);
+                } else if (op == TINY_OP_SUB) {
+                    ok = checked_sub(a, b, &answer);
+                } else if (op == TINY_OP_MUL) {
+                    ok = checked_mul(a, b, &answer);
+                } else if (op == TINY_OP_DIV) {
+                    if (b == 0) {
+                        status = TINYVM_ERROR_DIVISION_BY_ZERO;
+                        set_error(error, status, instruction_offset,
+                                  "Division by zero.");
+                        goto failed;
+                    }
+                    if (a == INT64_MIN && b == -1) {
+                        ok = 0;
+                    } else {
+                        answer = a / b;
+                    }
+                } else {
+                    if (b == 0) {
+                        status = TINYVM_ERROR_DIVISION_BY_ZERO;
+                        set_error(error, status, instruction_offset,
+                                  "Modulo by zero.");
+                        goto failed;
+                    }
+                    answer = (a == INT64_MIN && b == -1) ? 0 : a % b;
+                }
+
+                if (!ok) {
+                    status = TINYVM_ERROR_ARITHMETIC_OVERFLOW;
+                    set_error(error, status, instruction_offset,
+                              "Signed integer overflow.");
+                    goto failed;
+                }
+                if (tiny_stack_push(&stack, tiny_value_from_i64(answer))
+                    != TINY_STACK_OK) {
+                    status = TINYVM_ERROR_STACK_OVERFLOW;
+                    set_error(error, status, instruction_offset,
+                              "Operand stack overflow.");
+                    goto failed;
+                }
+                break;
+            }
+
+            case TINY_OP_EQ:
+            case TINY_OP_GT:
+            case TINY_OP_LT: {
+                TinyValue left, right;
+                int64_t answer;
+
+                if (tiny_stack_pop(&stack, &right) != TINY_STACK_OK ||
+                    tiny_stack_pop(&stack, &left) != TINY_STACK_OK) {
+                    status = TINYVM_ERROR_STACK_UNDERFLOW;
+                    set_error(error, status, instruction_offset,
+                              "Comparison needs two values.");
+                    goto failed;
+                }
+
+                if (op == TINY_OP_EQ) {
+                    answer = (left.integer == right.integer);
+                } else if (op == TINY_OP_GT) {
+                    answer = (left.integer > right.integer);
+                } else {
+                    answer = (left.integer < right.integer);
+                }
+
+                if (tiny_stack_push(&stack, tiny_value_from_i64(answer))
+                    != TINY_STACK_OK) {
+                    status = TINYVM_ERROR_STACK_OVERFLOW;
+                    set_error(error, status, instruction_offset,
+                              "Operand stack overflow.");
+                    goto failed;
+                }
+                break;
+            }
+
+            case TINY_OP_JMP:
+                ip = (size_t)read_u32_le(bytecode + ip);
+                break;
+
+            case TINY_OP_JZ: {
+                uint32_t target = read_u32_le(bytecode + ip);
+
+                if (tiny_stack_pop(&stack, &value) != TINY_STACK_OK) {
+                    status = TINYVM_ERROR_STACK_UNDERFLOW;
+                    set_error(error, status, instruction_offset,
+                              "JZ needs a condition value.");
+                    goto failed;
+                }
+
+                if (value.integer == 0) {
+                    ip = (size_t)target;
+                } else {
+                    ip += TINYVM_JUMP_OPERAND_SIZE;
+                }
+                break;
+            }
+
+
+
+            case TINY_OP_HALT:
+                free(boundaries);
+                tiny_stack_destroy(&stack);
+                return TINYVM_OK;
+
+            default:
+                /* Arithmetic, comparisons and jumps come in later lessons. */
+                status = TINYVM_ERROR_INVALID_OPCODE;
+                set_error(error, status, instruction_offset,
+                          "Instruction not implemented yet.");
+                goto failed;
+        }
+    }
+
+    free(boundaries);
+    tiny_stack_destroy(&stack);
+    return TINYVM_OK;
+
+failed:
+    free(boundaries);
+    tiny_stack_destroy(&stack);
+    tinyvm_result_free(result);
+    return status;
+}
+

tinyvm_flaxot-0.1.0/src/core/vm.h

@@ -0,0 +1,49 @@
+#ifndef TINYVM_VM_H
+#define TINYVM_VM_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+typedef enum {
+    TINYVM_OK = 0,
+    TINYVM_ERROR_INVALID_ARGUMENT,
+    TINYVM_ERROR_INVALID_OPCODE,
+    TINYVM_ERROR_TRUNCATED_BYTECODE,
+    TINYVM_ERROR_INVALID_JUMP,
+    TINYVM_ERROR_STACK_UNDERFLOW,
+    TINYVM_ERROR_STACK_OVERFLOW,
+    TINYVM_ERROR_DIVISION_BY_ZERO,
+    TINYVM_ERROR_ARITHMETIC_OVERFLOW,
+    TINYVM_ERROR_INSTRUCTION_LIMIT,
+    TINYVM_ERROR_OUT_OF_MEMORY
+} TinyVMStatus;
+
+typedef struct {
+    TinyVMStatus code;
+    size_t byte_offset;
+    char message[128];
+} TinyVMError;
+
+typedef struct {
+    int64_t *values;
+    size_t count;
+} TinyVMResult;
+
+typedef struct {
+    size_t max_stack;
+    uint64_t max_instructions;
+} TinyVMConfig;
+
+TinyVMConfig tinyvm_default_config(void);
+
+TinyVMStatus tinyvm_execute(
+    const uint8_t *bytecode,
+    size_t bytecode_length,
+    const TinyVMConfig *config,
+    TinyVMResult *result,
+    TinyVMError *error
+);
+
+void tinyvm_result_free(TinyVMResult *result);
+
+#endif

tinyvm_flaxot-0.1.0/src/python/module.c

@@ -0,0 +1,99 @@
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+
+#include "vm.h"
+
+static PyObject *native_execute(PyObject *self, PyObject *args,
+                                PyObject *kwargs)
+{
+    const char *bytecode = NULL;
+    Py_ssize_t length = 0;
+    Py_ssize_t max_stack = 256;
+    unsigned long long max_instructions = 100000;
+    static char *names[] = {"bytecode", "max_stack", "max_instructions", NULL};
+    TinyVMConfig config;
+    TinyVMResult result = {0};
+    TinyVMError error = {0};
+    TinyVMStatus status;
+    PyObject *output;
+    size_t i;
+
+    (void)self;
+
+    if (!PyArg_ParseTupleAndKeywords(args, kwargs, "y#|nK", names,
+                                     &bytecode, &length,
+                                     &max_stack, &max_instructions)) {
+        return NULL;
+    }
+
+    if (max_stack <= 0 || max_instructions == 0) {
+        PyErr_SetString(PyExc_ValueError, "VM limits must be positive.");
+        return NULL;
+    }
+
+    config.max_stack = (size_t)max_stack;
+    config.max_instructions = (uint64_t)max_instructions;
+
+    status = tinyvm_execute((const uint8_t *)bytecode, (size_t)length,
+                            &config, &result, &error);
+
+    if (status != TINYVM_OK) {
+        PyObject *exception = PyExc_RuntimeError;
+
+        if (status == TINYVM_ERROR_INVALID_ARGUMENT ||
+            status == TINYVM_ERROR_INVALID_OPCODE ||
+            status == TINYVM_ERROR_TRUNCATED_BYTECODE ||
+            status == TINYVM_ERROR_INVALID_JUMP) {
+            exception = PyExc_ValueError;
+        } else if (status == TINYVM_ERROR_DIVISION_BY_ZERO) {
+            exception = PyExc_ZeroDivisionError;
+        } else if (status == TINYVM_ERROR_ARITHMETIC_OVERFLOW) {
+            exception = PyExc_OverflowError;
+        } else if (status == TINYVM_ERROR_OUT_OF_MEMORY) {
+            exception = PyExc_MemoryError;
+        }
+
+        PyErr_Format(exception, "%s (byte offset %zu)",
+                     error.message, error.byte_offset);
+        tinyvm_result_free(&result);
+        return NULL;
+    }
+
+    output = PyList_New((Py_ssize_t)result.count);
+    if (output == NULL) {
+        tinyvm_result_free(&result);
+        return NULL;
+    }
+
+    for (i = 0; i < result.count; i++) {
+        PyObject *number = PyLong_FromLongLong((long long)result.values[i]);
+        if (number == NULL) {
+            Py_DECREF(output);
+            tinyvm_result_free(&result);
+            return NULL;
+        }
+        PyList_SET_ITEM(output, (Py_ssize_t)i, number);
+    }
+
+    tinyvm_result_free(&result);
+    return output;
+}
+
+static PyMethodDef methods[] = {
+    {"execute", (PyCFunction)native_execute, METH_VARARGS | METH_KEYWORDS,
+     "Execute encoded TinyVM bytecode."},
+    {NULL, NULL, 0, NULL}
+};
+
+static struct PyModuleDef module = {
+    PyModuleDef_HEAD_INIT,
+    "_native",
+    "TinyVM native module.",
+    -1,
+    methods
+};
+
+PyMODINIT_FUNC PyInit__native(void)
+{
+    return PyModule_Create(&module);
+}

tinyvm_flaxot-0.1.0/tests/test_python_api.py

@@ -0,0 +1,54 @@
+import pytest
+
+import tinyvm
+
+
+def run(program, **kwargs):
+    return tinyvm.VirtualMachine(**kwargs).execute(program)
+
+
+def test_add():
+    assert run([("PUSH", 10), ("PUSH", 20), ("ADD",), ("PRINT",), ("HALT",)]) == [30]
+
+
+def test_subtraction_order():
+    assert run([("PUSH", 20), ("PUSH", 5), ("SUB",), ("PRINT",), ("HALT",)]) == [15]
+
+
+def test_comparison():
+    assert run([("PUSH", 10), ("PUSH", 3), ("GT",), ("PRINT",), ("HALT",)]) == [1]
+
+
+def test_jump_if_zero():
+    assert run([
+        ("PUSH", 0),
+        ("JZ", "zero_case"),
+        ("PUSH", 999), ("PRINT",), ("HALT",),
+        ("LABEL", "zero_case"),
+        ("PUSH", 42), ("PRINT",), ("HALT",),
+    ]) == [42]
+
+
+def test_division_by_zero():
+    with pytest.raises(ZeroDivisionError):
+        run([("PUSH", 8), ("PUSH", 0), ("DIV",), ("HALT",)])
+
+
+def test_stack_underflow():
+    with pytest.raises(RuntimeError):
+        run([("POP",), ("HALT",)])
+
+
+def test_unknown_instruction():
+    with pytest.raises(ValueError):
+        run([("NOT_AN_OPCODE",)])
+
+
+def test_unknown_label():
+    with pytest.raises(ValueError):
+        run([("JMP", "nowhere")])
+
+
+def test_instruction_limit():
+    with pytest.raises(RuntimeError):
+        run([("LABEL", "again"), ("JMP", "again")], max_instructions=10)

tinyvm_flaxot-0.1.0/tests/test_vm.c

@@ -0,0 +1,64 @@
+#include <assert.h>
+#include <stdint.h>
+#include <stdio.h>
+
+#include "vm.h"
+#include "opcode.h"
+
+static void test_add_and_print(void)
+{
+    const uint8_t code[] = {
+        TINY_OP_PUSH_I64, 10, 0, 0, 0, 0, 0, 0, 0,
+        TINY_OP_PUSH_I64, 20, 0, 0, 0, 0, 0, 0, 0,
+        TINY_OP_ADD,
+        TINY_OP_PRINT,
+        TINY_OP_HALT
+    };
+    TinyVMConfig config = tinyvm_default_config();
+    TinyVMResult result = {0};
+    TinyVMError error = {0};
+
+    assert(tinyvm_execute(code, sizeof(code), &config, &result, &error)
+           == TINYVM_OK);
+    assert(result.count == 1);
+    assert(result.values[0] == 30);
+    tinyvm_result_free(&result);
+}
+
+static void test_division_by_zero(void)
+{
+    const uint8_t code[] = {
+        TINY_OP_PUSH_I64, 10, 0, 0, 0, 0, 0, 0, 0,
+        TINY_OP_PUSH_I64, 0, 0, 0, 0, 0, 0, 0, 0,
+        TINY_OP_DIV,
+        TINY_OP_HALT
+    };
+    TinyVMConfig config = tinyvm_default_config();
+    TinyVMResult result = {0};
+    TinyVMError error = {0};
+
+    assert(tinyvm_execute(code, sizeof(code), &config, &result, &error)
+           == TINYVM_ERROR_DIVISION_BY_ZERO);
+    tinyvm_result_free(&result);
+}
+
+static void test_invalid_opcode(void)
+{
+    const uint8_t code[] = { 0x77 };
+    TinyVMConfig config = tinyvm_default_config();
+    TinyVMResult result = {0};
+    TinyVMError error = {0};
+
+    assert(tinyvm_execute(code, sizeof(code), &config, &result, &error)
+           == TINYVM_ERROR_INVALID_OPCODE);
+    tinyvm_result_free(&result);
+}
+
+int main(void)
+{
+    test_add_and_print();
+    test_division_by_zero();
+    test_invalid_opcode();
+    puts("All TinyVM C tests passed.");
+    return 0;
+}

tinyvm_flaxot-0.1.0/tinyvm/__init__.py

@@ -0,0 +1,7 @@
+"""TinyVM: a small bytecode virtual machine."""
+
+from .assembler import assemble
+from .engine import VirtualMachine
+
+__all__ = ["VirtualMachine", "assemble"]
+__version__ = "0.1.0"

tinyvm_flaxot-0.1.0/tinyvm/assembler.py

@@ -0,0 +1,75 @@
+import struct
+
+OPCODES = {
+    "PUSH": 0x01, "POP": 0x02, "DUP": 0x03,
+    "ADD": 0x10, "SUB": 0x11, "MUL": 0x12,
+    "DIV": 0x13, "MOD": 0x14,
+    "EQ": 0x20, "GT": 0x21, "LT": 0x22,
+    "JMP": 0x30, "JZ": 0x31,
+    "PRINT": 0x40, "HALT": 0xFF,
+}
+
+
+def _is_integer(value):
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def assemble(instructions):
+    """Convert instruction tuples (with labels) into TinyVM bytecode."""
+    instructions = list(instructions)
+    labels = {}
+    offset = 0
+
+    # Pass 1: validate shapes, compute byte offsets, record labels.
+    for item in instructions:
+        if not isinstance(item, tuple) or not item:
+            raise ValueError("Instructions must be non-empty tuples.")
+        name = item[0]
+        if not isinstance(name, str):
+            raise ValueError("Instruction names must be strings.")
+        name = name.upper()
+
+        if name == "LABEL":
+            if len(item) != 2 or not isinstance(item[1], str):
+                raise ValueError("LABEL requires one string name.")
+            if item[1] in labels:
+                raise ValueError(f"Duplicate label: {item[1]}")
+            labels[item[1]] = offset
+        elif name == "PUSH":
+            if len(item) != 2 or not _is_integer(item[1]):
+                raise ValueError("PUSH requires one integer.")
+            if not -(2**63) <= item[1] <= 2**63 - 1:
+                raise ValueError("PUSH value must fit in signed 64 bits.")
+            offset += 9
+        elif name in ("JMP", "JZ"):
+            if len(item) != 2:
+                raise ValueError(f"{name} requires one target.")
+            offset += 5
+        elif name in OPCODES:
+            if len(item) != 1:
+                raise ValueError(f"{name} takes no operands.")
+            offset += 1
+        else:
+            raise ValueError(f"Unknown instruction: {name}")
+
+    # Pass 2: encode, now that label offsets are known.
+    output = bytearray()
+    for item in instructions:
+        name = item[0].upper()
+        if name == "LABEL":
+            continue
+
+        output.append(OPCODES[name])
+        if name == "PUSH":
+            output.extend(struct.pack("<q", item[1]))
+        elif name in ("JMP", "JZ"):
+            target = item[1]
+            if isinstance(target, str):
+                if target not in labels:
+                    raise ValueError(f"Unknown label: {target}")
+                target = labels[target]
+            if not _is_integer(target) or not 0 <= target <= 0xFFFFFFFF:
+                raise ValueError(f"{name} target must be a valid byte offset.")
+            output.extend(struct.pack("<I", target))
+
+    return bytes(output)

tinyvm_flaxot-0.1.0/tinyvm/engine.py

@@ -0,0 +1,25 @@
+from . import _native
+from .assembler import assemble
+
+
+class VirtualMachine:
+    """Python interface to the TinyVM native execution engine."""
+
+    def __init__(self, max_stack=256, max_instructions=100_000):
+        for name, value in (("max_stack", max_stack),
+                            ("max_instructions", max_instructions)):
+            if not isinstance(value, int) or isinstance(value, bool):
+                raise TypeError(f"{name} must be an integer.")
+            if value <= 0:
+                raise ValueError(f"{name} must be greater than zero.")
+        self.max_stack = max_stack
+        self.max_instructions = max_instructions
+
+    def execute(self, instructions):
+        """Assemble and run instruction tuples; return the PRINT output."""
+        bytecode = assemble(instructions)
+        return _native.execute(
+            bytecode,
+            max_stack=self.max_stack,
+            max_instructions=self.max_instructions,
+        )

tinyvm_flaxot-0.1.0/tinyvm_Flaxot.egg-info/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: tinyvm-Flaxot
+Version: 0.1.0
+Summary: A small C-powered stack-based bytecode virtual machine.
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file

tinyvm_flaxot-0.1.0/tinyvm_Flaxot.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+LICENSE
+MANIFEST.in
+pyproject.toml
+setup.py
+src/core/main.c
+src/core/opcode.h
+src/core/stack.c
+src/core/stack.h
+src/core/value.c
+src/core/value.h
+src/core/vm.c
+src/core/vm.h
+src/python/module.c
+tests/test_python_api.py
+tests/test_vm.c
+tinyvm/__init__.py
+tinyvm/assembler.py
+tinyvm/engine.py
+tinyvm_Flaxot.egg-info/PKG-INFO
+tinyvm_Flaxot.egg-info/SOURCES.txt
+tinyvm_Flaxot.egg-info/dependency_links.txt
+tinyvm_Flaxot.egg-info/top_level.txt

tinyvm_flaxot-0.1.0/tinyvm_Flaxot.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tinyvm_flaxot-0.1.0/tinyvm_Flaxot.egg-info/top_level.txt

@@ -0,0 +1 @@
+tinyvm