Add runnable interpreter cycle hooks

Author: olwang

README.md

@@ -418,7 +418,7 @@ If a lowered package contains `fn main() -> Unit` or `fn main() -> Result<Unit,
 
 `rss verify-rust <file.rss> --out-dir <directory>` keeps the generated package used for backend checking, including `rsscript-source-map.json`, so unmappable rustc diagnostics can be inspected against the generated Rust.
 
-The first observable runtime boundaries are `Log.write(message: read String)`, `Assert.equal(left: read String, right: read String)`, and the core `File`, `Json`, `Csv`, `Image`, `ImageCache`, HTTP handler, DB resource-pool, config reload, and `Counter` APIs, which lower to explicit runtime hooks. `ImageCache` is the first small retained managed-container hook: it stores managed image handles and enforces a capacity limit. Simple core operations such as `String.concat(left: read String, right: read String)` keep RSScript `.rssi` signatures for checking and review, but lower directly to Rust standard-library expressions. Built-in boolean literals, numeric operators, comparison operators, `Option<T>` constructors, and core surface types such as `Bytes`, `Buffer`, `Path`, `List<T>`, `Map<K,V>`, and `Set<T>` lower to the corresponding Rust literals, operators, enum constructors, and standard-library types; user-defined operator overloading remains forbidden.
+The first observable runtime boundaries are `Log.write(message: read String)`, `Assert.equal(left: read String, right: read String)`, and the core `File`, `Json`, `Csv`, `Image`, `ImageCache`, HTTP handler, DB resource-pool, config reload, interpreter object-cycle, and `Counter` APIs, which lower to explicit runtime hooks. `ImageCache` is the first small retained managed-container hook: it stores managed image handles and enforces a capacity limit. The interpreter hooks model `Environment` and `FunctionObject` as managed handles, including an environment/function closure cycle. Simple core operations such as `String.concat(left: read String, right: read String)` keep RSScript `.rssi` signatures for checking and review, but lower directly to Rust standard-library expressions. Built-in boolean literals, numeric operators, comparison operators, `Option<T>` constructors, and core surface types such as `Bytes`, `Buffer`, `Path`, `List<T>`, `Map<K,V>`, and `Set<T>` lower to the corresponding Rust literals, operators, enum constructors, and standard-library types; user-defined operator overloading remains forbidden.
 
 Smallest runnable example:
 

core/interpreter/interpreter.rssi

@@ -0,0 +1,23 @@
+struct Environment
+
+struct FunctionObject
+
+pub fn Environment.root() -> fresh Environment
+
+pub fn Environment.child(parent: read Environment) -> fresh Environment
+    effects(retains(parent))
+
+pub fn Environment.bind_function(
+    env: mut Environment,
+    function: read FunctionObject,
+) -> Unit
+    effects(retains(function))
+
+pub fn Environment.has_parent(env: read Environment) -> Bool
+
+pub fn Environment.has_function(env: read Environment) -> Bool
+
+pub fn FunctionObject.new(closure: read Environment) -> fresh FunctionObject
+    effects(retains(closure))
+
+pub fn FunctionObject.has_closure(function: read FunctionObject) -> Bool

core/prototype/builtins.rssi

@@ -15,5 +15,3 @@ pub fn GlobalConfig.replace(
 pub fn Cache.lookup(cache: read Cache, key: read String)
 
 pub fn Cache.get(cache: read Cache)
-
-pub fn FunctionObject.new(closure: read Environment) -> fresh FunctionObject

examples/interpreter_cycle.rss

@@ -0,0 +1,23 @@
+features: local
+
+fn main() -> Unit {
+    local root_value = Environment.root()
+    let root = manage root_value
+
+    local child_value = Environment.child(parent: read root)
+    let child = manage child_value
+
+    local function_value = FunctionObject.new(closure: read child)
+    let function = manage function_value
+
+    Environment.bind_function(env: mut child, function: read function)
+
+    if Environment.has_parent(env: read child)
+        && Environment.has_function(env: read child)
+        && FunctionObject.has_closure(function: read function)
+    {
+        Log.write(message: read "interpreter cycle linked")
+    }
+
+    return Unit
+}

runtime/src/lib.rs

@@ -45,6 +45,36 @@ pub struct Counter {
     value: i64,
 }
 
+#[derive(Clone)]
+pub struct Environment {
+    parent: Option<Gc<Environment>>,
+    function: Option<Gc<FunctionObject>>,
+}
+
+#[derive(Clone)]
+pub struct FunctionObject {
+    closure: Gc<Environment>,
+}
+
+impl fmt::Debug for Environment {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("Environment")
+            .field("has_parent", &self.parent.is_some())
+            .field("has_function", &self.function.is_some())
+            .finish()
+    }
+}
+
+impl fmt::Debug for FunctionObject {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter
+            .debug_struct("FunctionObject")
+            .field("has_closure", &true)
+            .finish()
+    }
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ConfigError {
     message: String,
@@ -391,6 +421,43 @@ pub fn counter_value(counter: &Counter) -> i64 {
     counter.value
 }
 
+pub fn environment_root() -> Environment {
+    Environment {
+        parent: None,
+        function: None,
+    }
+}
+
+pub fn environment_child(parent: &Gc<Environment>) -> Environment {
+    Environment {
+        parent: Some(parent.clone()),
+        function: None,
+    }
+}
+
+pub fn environment_bind_function(env: &mut Gc<Environment>, function: &Gc<FunctionObject>) {
+    env.write().function = Some(function.clone());
+}
+
+pub fn environment_has_parent(env: &Gc<Environment>) -> bool {
+    env.read().parent.is_some()
+}
+
+pub fn environment_has_function(env: &Gc<Environment>) -> bool {
+    env.read().function.is_some()
+}
+
+pub fn function_object_new(closure: &Gc<Environment>) -> FunctionObject {
+    FunctionObject {
+        closure: closure.clone(),
+    }
+}
+
+pub fn function_object_has_closure(function: &Gc<FunctionObject>) -> bool {
+    let _closure = function.read().closure.clone();
+    true
+}
+
 pub fn db_connection_open(url: &str) -> DbConnection {
     DbConnection {
         url: url.to_string(),
@@ -982,6 +1049,20 @@ mod tests {
         assert_eq!(super::counter_value(&counter), 3);
     }
 
+    #[test]
+    fn interpreter_runtime_hooks_link_environment_function_cycle() {
+        let root = super::manage(super::environment_root());
+        let child = super::manage(super::environment_child(&root));
+        let function = super::manage(super::function_object_new(&child));
+        let mut child_handle = child.clone();
+
+        super::environment_bind_function(&mut child_handle, &function);
+
+        assert!(super::environment_has_parent(&child));
+        assert!(super::environment_has_function(&child));
+        assert!(super::function_object_has_closure(&function));
+    }
+
     #[test]
     fn image_runtime_hooks_load_transform_and_save() {
         let input = std::env::temp_dir().join(format!(

src/interfaces.rs

@@ -22,6 +22,10 @@ pub(crate) const CORE_INTERFACES: &[(&str, &str)] = &[
         "core/http/http.rssi",
         include_str!("../core/http/http.rssi"),
     ),
+    (
+        "core/interpreter/interpreter.rssi",
+        include_str!("../core/interpreter/interpreter.rssi"),
+    ),
     (
         "core/image/image.rssi",
         include_str!("../core/image/image.rssi"),

src/rust_lower.rs

@@ -7,8 +7,8 @@ use crate::analyzer::analyze_source_with_core;
 use crate::diagnostic::{Diagnostic, Severity, Span, code};
 use crate::syntax::ast::{
     BinaryOp, Block, CallArg, Callee, DataEffect, EffectDecl, Expr, FieldDecl, FileFeature,
-    FunctionDecl, GenericBound, GenericParam, Item, LetKind, Param, Program, Stmt, TypeDecl,
-    TypeKind, TypeRef,
+    FunctionDecl, GenericBound, GenericParam, Item, Param, Program, Stmt, TypeDecl, TypeKind,
+    TypeRef,
 };
 use crate::syntax::parse_source;
 
@@ -484,12 +484,11 @@ impl<'a> RustLowerer<'a> {
         self.record_statement_source_map(statement, &marker.generated);
         match statement {
             Stmt::Let(stmt) => {
-                let mutable =
-                    if stmt.kind == LetKind::Local || self.mutated_bindings.contains(&stmt.name) {
-                        "mut "
-                    } else {
-                        ""
-                    };
+                let mutable = if self.mutated_bindings.contains(&stmt.name) {
+                    "mut "
+                } else {
+                    ""
+                };
                 if let Some(value) = &stmt.value {
                     out.push_str(&format!(
                         "{pad}let {mutable}{} = {};\n",
@@ -812,6 +811,8 @@ impl<'a> RustLowerer<'a> {
             "Fd" => "i64".to_string(),
             "Bytes" | "Buffer" => "Vec<u8>".to_string(),
             "Path" => "std::path::PathBuf".to_string(),
+            "Environment" => "rsscript_runtime::Environment".to_string(),
+            "FunctionObject" => "rsscript_runtime::FunctionObject".to_string(),
             "Counter" => "rsscript_runtime::Counter".to_string(),
             "File" => "rsscript_runtime::File".to_string(),
             "FileError" | "IOError" => "std::io::Error".to_string(),
@@ -1214,6 +1215,27 @@ fn lower_callee(callee: &Callee) -> String {
         callee if is_counter_new_callee(callee) => "rsscript_runtime::counter_new".to_string(),
         callee if is_counter_add_callee(callee) => "rsscript_runtime::counter_add".to_string(),
         callee if is_counter_value_callee(callee) => "rsscript_runtime::counter_value".to_string(),
+        callee if is_environment_root_callee(callee) => {
+            "rsscript_runtime::environment_root".to_string()
+        }
+        callee if is_environment_child_callee(callee) => {
+            "rsscript_runtime::environment_child".to_string()
+        }
+        callee if is_environment_bind_function_callee(callee) => {
+            "rsscript_runtime::environment_bind_function".to_string()
+        }
+        callee if is_environment_has_parent_callee(callee) => {
+            "rsscript_runtime::environment_has_parent".to_string()
+        }
+        callee if is_environment_has_function_callee(callee) => {
+            "rsscript_runtime::environment_has_function".to_string()
+        }
+        callee if is_function_object_new_callee(callee) => {
+            "rsscript_runtime::function_object_new".to_string()
+        }
+        callee if is_function_object_has_closure_callee(callee) => {
+            "rsscript_runtime::function_object_has_closure".to_string()
+        }
         callee if is_db_connection_open_callee(callee) => {
             "rsscript_runtime::db_connection_open".to_string()
         }
@@ -1345,6 +1367,34 @@ fn is_counter_value_callee(callee: &Callee) -> bool {
     matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "Counter" && name == "value")
 }
 
+fn is_environment_root_callee(callee: &Callee) -> bool {
+    matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "Environment" && name == "root")
+}
+
+fn is_environment_child_callee(callee: &Callee) -> bool {
+    matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "Environment" && name == "child")
+}
+
+fn is_environment_bind_function_callee(callee: &Callee) -> bool {
+    matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "Environment" && name == "bind_function")
+}
+
+fn is_environment_has_parent_callee(callee: &Callee) -> bool {
+    matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "Environment" && name == "has_parent")
+}
+
+fn is_environment_has_function_callee(callee: &Callee) -> bool {
+    matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "Environment" && name == "has_function")
+}
+
+fn is_function_object_new_callee(callee: &Callee) -> bool {
+    matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "FunctionObject" && name == "new")
+}
+
+fn is_function_object_has_closure_callee(callee: &Callee) -> bool {
+    matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "FunctionObject" && name == "has_closure")
+}
+
 fn is_db_connection_open_callee(callee: &Callee) -> bool {
     matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "DbConnection" && name == "open")
 }

tests/checker.rs

@@ -97,6 +97,11 @@ fn bundled_core_interfaces_are_available_to_checker() {
             .iter()
             .any(|(path, _)| *path == "core/counter/counter.rssi")
     );
+    assert!(
+        core_interfaces()
+            .iter()
+            .any(|(path, _)| *path == "core/interpreter/interpreter.rssi")
+    );
 
     let source = r#"
 fn check_label(actual: read String, expected: read String) -> Unit {
@@ -540,6 +545,37 @@ fn main() -> Unit {
     assert!(rust.contains("if value == 3 {"));
 }
 
+#[test]
+fn rust_lowering_maps_interpreter_cycle_core_calls_to_runtime_hooks() {
+    let source = r#"
+features: local
+
+fn main() -> Unit {
+    local root_value = Environment.root()
+    let root = manage root_value
+    local child_value = Environment.child(parent: read root)
+    let child = manage child_value
+    local function_value = FunctionObject.new(closure: read child)
+    let function = manage function_value
+    Environment.bind_function(env: mut child, function: read function)
+    if Environment.has_function(env: read child) && FunctionObject.has_closure(function: read function) {
+        Log.write(message: read "linked")
+    }
+    return Unit
+}
+"#;
+    let rust = lower_source_to_rust("interpreter-cycle.rss", source).expect("source should lower");
+
+    assert!(rust.contains("let root_value = rsscript_runtime::environment_root();"));
+    assert!(rust.contains("let root = rsscript_runtime::manage_at(root_value,"));
+    assert!(rust.contains("let child_value = rsscript_runtime::environment_child(&root);"));
+    assert!(rust.contains("let mut child = rsscript_runtime::manage_at(child_value,"));
+    assert!(rust.contains("let function_value = rsscript_runtime::function_object_new(&child);"));
+    assert!(rust.contains("let function = rsscript_runtime::manage_at(function_value,"));
+    assert!(rust.contains("rsscript_runtime::environment_bind_function(&mut child, &function);"));
+    assert!(rust.contains("rsscript_runtime::function_object_has_closure(&function)"));
+}
+
 #[test]
 fn rust_lowering_decodes_string_escape_sequences() {
     let source = r#"
@@ -881,7 +917,7 @@ pub fn make_session(id: Int) -> Session {
 
     assert!(rust.contains("pub struct Session"));
     assert!(rust.contains("pub fn make_session(id: i64) -> rsscript_runtime::Gc<Session>"));
-    assert!(rust.contains("let mut session = Session { id: id };"));
+    assert!(rust.contains("let session = Session { id: id };"));
     assert!(rust.contains("return rsscript_runtime::manage_at(session, rsscript_runtime::SourceSpan::new(\"session.rss\", 10, 12, 6));"));
 }