Add Maroon JSON DSL and Bytecode Executor #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Open

AdamEther wants to merge 4 commits into dkorolev:main from AdamEther:patch-2

AdamEther commented May 30, 2025 •

edited

Loading

Summary

This PR introduces step13_maroon_json, a Rust implementation of a stack-based virtual machine that executes JSON bytecode. The VM provides a portable, language-agnostic bytecode format for executing computational tasks with state management, timing control, and output capabilities.

What's New

JSON Bytecode VM: A complete stack machine implementation that executes JSON-formatted bytecode
Expression Evaluation: Support for arithmetic operations (mul, sub) and comparisons (le)
State Machine Architecture: Explicit state transitions with local variable management
Async Execution: Leverages Tokio for non-blocking sleep operations
Variable Interpolation: Dynamic text output with variable substitution

Technical Details

The VM implements a stack-based execution model with three core data types:

State entries for control flow
Retrn entries for function return addresses
Value entries for computational data

Supported operations:

push_stack - Push entries onto the execution stack
write - Output text with variable interpolation
sleep - Async delay with expression-based duration
conditional - Branching based on expression evaluation
return - Return computed values to caller
done - Terminate execution

Example

Running factorial(5) produces timed output showing the recursive execution:
0ms: f(5)
250ms: f(4)
450ms: f(3)
600ms: f(2)
700ms: f(1)
750ms: 5!=120

Architecture Benefits

Portability: JSON bytecode can be generated and executed by any language
Debuggability: Stack state and execution flow are explicit and inspectable
Extensibility: New operations and expression types can be easily added
Performance: Rust implementation with async/await for efficient execution

Files Added

step13_maroon_json/code/src/main.rs - VM implementation
step13_maroon_json/code/Cargo.toml - Rust dependencies
step13_maroon_json/README.md - Documentation
step13_maroon_json/run.sh - Execution script

Testing

cd step13_maroon_json && ./run.sh

This executes the factorial example from factorial_bytecode.json and demonstrates the VM's capabilities.

Ivan added 4 commits

May 30, 2025 23:46


          Maroon json DSL

644c154


          Clean up - keep only Maroon JSON DSL and its (single) Bytecode Executor

1333cdf


          Remove factorial_bytecode_new.json

8e810f9


          Final clean up

6e7a5e2

Author

AdamEther commented Jun 1, 2025

@dkorolev please re-review it.

dkorolev reviewed

View reviewed changes

step13_maroon_json/code/src/main.rs

+              struct MaroonVM {
+                program: Program,
+                stack: Vec<StackEntry>,
+                local_vars: HashMap<String, u64>,

Owner

dkorolev Jun 1, 2025

heap?

dkorolev reviewed

View reviewed changes

step13_maroon_json/code/src/main.rs

+              }
+              impl MaroonVM {
+                fn new(program: Program) -> Self {

Owner

dkorolev Jun 1, 2025

Don't you need the initial state, and perhaps its arguments? So that the invalid states are not representable?

dkorolev reviewed

View reviewed changes

step13_maroon_json/code/src/main.rs

+                fn evaluate_expression(&self, expr: &Expression) -> u64 {
+                  match expr {
+                    Expression::Var { var } => *self.local_vars.get(var).unwrap_or(&0),

Owner

dkorolev Jun 1, 2025

Why not just .unwrap(), this _or(&0) doesn't look safe to me.

dkorolev reviewed

View reviewed changes

step13_maroon_json/code/src/main.rs

+                }
+                fn evaluate_stack_value(&self, value: &StackValue) -> u64 {
+                  match value {

Owner

dkorolev Jun 1, 2025

There got to be some visitor pattern for this in Rust, natively — no?

dkorolev reviewed

View reviewed changes

step13_maroon_json/code/src/main.rs

+                fn interpolate_text(&self, text: &str) -> String {
+                  let mut result = text.to_string();
+                  for (var, value) in &self.local_vars {
+                    result = result.replace(&format!("{{{}}}", var), &value.to_string());

Owner

dkorolev Jun 1, 2025

Me confused. Needs a comment or pls make it more self-descriptive, it's write-only as of now.

dkorolev reviewed

View reviewed changes

step13_maroon_json/code/src/main.rs

+                    .context("Entry point function not found")?;
+                  // Initialize stack with entry state
+                  self.local_vars.insert("n".to_string(), initial_arg);

Owner

dkorolev Jun 1, 2025

This is also making too many assumptions — just a u64, called "n". Need to find a way to do it cleaner, although the code most definitely LGTM.

dkorolev reviewed

View reviewed changes

step13_maroon_json/code/src/main.rs



		// Update local variables based on state
		if current_state_name.contains("PostRecursiveCall") && local_values.len() >= 2 {

Owner

dkorolev Jun 1, 2025

Wait, what?

Author

AdamEther Jun 1, 2025

definitely a bug

dkorolev reviewed

View reviewed changes

step13_maroon_json/code/src/main.rs

+                    let mut continue_to_next_iteration = false;
+                    for op in &state_def.operations {
+                      match &op.op_type[..] {
+                        "push_stack" => {

Owner

dkorolev Jun 1, 2025

Let's avoid this. Parse the JSON into a strongly typed object first pls.

dkorolev reviewed

View reviewed changes

step13_maroon_json/code/src/main.rs

+                            let mut pushed_stack = false;
+                            for exec_op in ops_to_execute {
+                              match &exec_op.op_type[..] {
+                                "return" => {

Owner

dkorolev Jun 1, 2025

This inner part looks redundant to me.

dkorolev approved these changes

View reviewed changes

Owner

dkorolev left a comment

Looks good!

For this to be self-contained, perhaps present it as a command-line tool, which gets three inputs: path to the .json with the code, path to the .json with the "call spec", and the name of the function to execute?

Overall I'd say it's good to merge! And let's stop abusing the rust-experiments repo, it's about time =)

Author

AdamEther commented Jun 1, 2025

Thanks for your time and looking into it!

For this to be self-contained, perhaps present it as a command-line tool, which gets three inputs: path to the .json with the code, path to the .json with the "call spec", and the name of the function to execute?

Sounds right to me.

Overall I'd say it's good to merge! And let's stop abusing the rust-experiments repo, it's about time =)

Noted with thanks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet