Add runnable ImageCache runtime hooks

Author: olwang

README.md

@@ -412,13 +412,13 @@ rss verify-rust [--json] <file.rss> --out-dir <directory>
 
 `rss check` loads bundled core `.rssi` signatures by default. Use `--no-core` only when testing a file against user-supplied interfaces in isolation.
 
-The checker prototype also keeps a small `core/prototype` interface bundle for real-scenario fixtures such as CSV, DB, cache, and config examples. Those signatures are still `.rssi` sources, not a second Rust-side builtin table.
+The checker prototype also keeps a small `core/prototype` interface bundle for real-scenario fixtures that have not yet moved into `core/`. Those signatures are still `.rssi` sources, not a second Rust-side builtin table.
 
 If a lowered package contains `fn main() -> Unit` or `fn main() -> Result<Unit, E>`, `rss lower --rust --out-dir` also emits a Rust `src/main.rs` harness. `rss run <file.rss>` uses the same lowering path, writes a temporary Rust package, and delegates execution to `cargo run`. Use `rss run <file.rss> --out-dir <directory>` to keep the generated Rust package for inspection.
 
 `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`, HTTP handler, DB resource-pool, config reload, and `Counter` APIs, which lower to explicit runtime hooks. 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, 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.
 
 Smallest runnable example:
 

core/cache/image_cache.rssi

@@ -0,0 +1,11 @@
+struct ImageCache
+
+pub fn ImageCache.new(capacity: Int) -> fresh ImageCache
+
+pub fn ImageCache.store(
+    cache: mut ImageCache,
+    image: read Image,
+) -> Unit
+    effects(retains(image))
+
+pub fn ImageCache.len(cache: read ImageCache) -> Int

core/prototype/builtins.rssi

@@ -1,11 +1,5 @@
 pub fn OS.close(fd: Fd) -> Unit
 
-pub fn ImageCache.store(
-    cache: mut ImageCache,
-    image: read Image,
-) -> Unit
-    effects(retains(image))
-
 pub fn List.consume(list: take List) -> Unit
 
 pub fn Buffer.consume(buffer: take Buffer) -> Unit

examples/image_cache.rss

@@ -0,0 +1,25 @@
+features: local
+
+fn main() -> Result<Unit, ImageError> {
+    let input = "rsscript-cache-image-input.bin"
+    let output = "rsscript-cache-image-output.bin"
+
+    with File.open_write(path: read input) as file {
+        File.write(file: mut file, data: read "cached image bytes")?
+    }
+
+    local cache = ImageCache.new(capacity: 1)
+    local image = Image.load(path: read input)?
+    Image.resize(image: mut image, width: 128, height: 128)
+
+    let shared = manage image
+    ImageCache.store(cache: mut cache, image: read shared)
+    Image.save(image: read shared, path: read output)?
+
+    let count = ImageCache.len(cache: read cache)
+    if count == 1 {
+        Log.write(message: read "image cache retained managed image")
+    }
+
+    return Ok(Unit)
+}

runtime/src/lib.rs

@@ -1,4 +1,5 @@
 use std::cell::{BorrowError, BorrowMutError, Ref, RefCell, RefMut};
+use std::collections::VecDeque;
 use std::fmt;
 use std::io::{Read, Write};
 use std::ops::{Deref, DerefMut};
@@ -121,6 +122,12 @@ pub struct Image {
     operations: Vec<&'static str>,
 }
 
+#[derive(Debug, Clone)]
+pub struct ImageCache {
+    capacity: usize,
+    entries: VecDeque<Gc<Image>>,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ImageError {
     message: String,
@@ -148,6 +155,23 @@ impl From<std::io::Error> for ImageError {
     }
 }
 
+pub trait RuntimeImageRef {
+    fn with_image<R>(&self, f: impl FnOnce(&Image) -> R) -> R;
+}
+
+impl RuntimeImageRef for Image {
+    fn with_image<R>(&self, f: impl FnOnce(&Image) -> R) -> R {
+        f(self)
+    }
+}
+
+impl RuntimeImageRef for Gc<Image> {
+    fn with_image<R>(&self, f: impl FnOnce(&Image) -> R) -> R {
+        let image = self.read();
+        f(&image)
+    }
+}
+
 #[derive(Debug, Clone)]
 pub struct JsonValue {
     inner: serde_json::Value,
@@ -411,29 +435,59 @@ pub fn image_sharpen(image: &mut Image) {
     image.operations.push("sharpen");
 }
 
-pub fn image_save<P: RuntimePath + ?Sized>(image: &Image, path: &P) -> Result<(), ImageError> {
-    let mut bytes = image.bytes.clone();
-    bytes.extend_from_slice(b"\n# rsscript-image-ops:");
-    bytes.extend_from_slice(image.operations.join(",").as_bytes());
-    if let (Some(width), Some(height)) = (image.width, image.height) {
-        bytes.extend_from_slice(format!(";size={width}x{height}").as_bytes());
-    }
+pub fn image_save<I: RuntimeImageRef + ?Sized, P: RuntimePath + ?Sized>(
+    image: &I,
+    path: &P,
+) -> Result<(), ImageError> {
+    let bytes = image.with_image(|image| {
+        let mut bytes = image.bytes.clone();
+        bytes.extend_from_slice(b"\n# rsscript-image-ops:");
+        bytes.extend_from_slice(image.operations.join(",").as_bytes());
+        if let (Some(width), Some(height)) = (image.width, image.height) {
+            bytes.extend_from_slice(format!(";size={width}x{height}").as_bytes());
+        }
+        bytes
+    });
     std::fs::write(path.as_path(), bytes)?;
     Ok(())
 }
 
-pub fn image_inspect(image: &Image) {
-    let size = image
-        .width
-        .zip(image.height)
-        .map(|(width, height)| format!("{width}x{height}"))
-        .unwrap_or_else(|| "unknown".to_string());
-    println!(
-        "image bytes={} size={} ops={}",
-        image.bytes.len(),
-        size,
-        image.operations.join(",")
-    );
+pub fn image_inspect<I: RuntimeImageRef + ?Sized>(image: &I) {
+    let summary = image.with_image(|image| {
+        let size = image
+            .width
+            .zip(image.height)
+            .map(|(width, height)| format!("{width}x{height}"))
+            .unwrap_or_else(|| "unknown".to_string());
+        format!(
+            "image bytes={} size={} ops={}",
+            image.bytes.len(),
+            size,
+            image.operations.join(",")
+        )
+    });
+    println!("{summary}");
+}
+
+pub fn image_cache_new(capacity: i64) -> ImageCache {
+    ImageCache {
+        capacity: capacity.max(0) as usize,
+        entries: VecDeque::new(),
+    }
+}
+
+pub fn image_cache_store(cache: &mut ImageCache, image: &Gc<Image>) {
+    if cache.capacity == 0 {
+        return;
+    }
+    while cache.entries.len() >= cache.capacity {
+        cache.entries.pop_front();
+    }
+    cache.entries.push_back(image.clone());
+}
+
+pub fn image_cache_len(cache: &ImageCache) -> i64 {
+    cache.entries.len() as i64
 }
 
 pub fn json_parse(text: &str) -> Result<JsonValue, JsonError> {
@@ -953,6 +1007,28 @@ mod tests {
         let _ = std::fs::remove_file(output);
     }
 
+    #[test]
+    fn image_cache_runtime_hooks_retain_managed_images_with_capacity() {
+        let mut cache = super::image_cache_new(1);
+        let first = super::manage(super::Image {
+            bytes: b"first".to_vec(),
+            width: None,
+            height: None,
+            operations: vec!["test"],
+        });
+        let second = super::manage(super::Image {
+            bytes: b"second".to_vec(),
+            width: None,
+            height: None,
+            operations: vec!["test"],
+        });
+
+        super::image_cache_store(&mut cache, &first);
+        super::image_cache_store(&mut cache, &second);
+
+        assert_eq!(super::image_cache_len(&cache), 1);
+    }
+
     #[test]
     fn http_runtime_hooks_create_request_and_response() {
         let request = super::request_new("/users");

src/interfaces.rs

@@ -1,4 +1,8 @@
 pub(crate) const CORE_INTERFACES: &[(&str, &str)] = &[
+    (
+        "core/cache/image_cache.rssi",
+        include_str!("../core/cache/image_cache.rssi"),
+    ),
     (
         "core/collections/map.rssi",
         include_str!("../core/collections/map.rssi"),

src/rust_lower.rs

@@ -824,6 +824,7 @@ impl<'a> RustLowerer<'a> {
             "DbConnection" => "rsscript_runtime::DbConnection".to_string(),
             "DbError" => "rsscript_runtime::DbError".to_string(),
             "Image" => "rsscript_runtime::Image".to_string(),
+            "ImageCache" => "rsscript_runtime::ImageCache".to_string(),
             "ImageError" => "rsscript_runtime::ImageError".to_string(),
             "JsonValue" => "rsscript_runtime::JsonValue".to_string(),
             "JsonError" => "rsscript_runtime::JsonError".to_string(),
@@ -1228,6 +1229,15 @@ fn lower_callee(callee: &Callee) -> String {
         callee if is_image_sharpen_callee(callee) => "rsscript_runtime::image_sharpen".to_string(),
         callee if is_image_save_callee(callee) => "rsscript_runtime::image_save".to_string(),
         callee if is_image_inspect_callee(callee) => "rsscript_runtime::image_inspect".to_string(),
+        callee if is_image_cache_new_callee(callee) => {
+            "rsscript_runtime::image_cache_new".to_string()
+        }
+        callee if is_image_cache_store_callee(callee) => {
+            "rsscript_runtime::image_cache_store".to_string()
+        }
+        callee if is_image_cache_len_callee(callee) => {
+            "rsscript_runtime::image_cache_len".to_string()
+        }
         callee if is_json_parse_callee(callee) => "rsscript_runtime::json_parse".to_string(),
         callee if is_json_field_callee(callee) => "rsscript_runtime::json_field".to_string(),
         callee if is_json_field_string_callee(callee) => {
@@ -1371,6 +1381,18 @@ fn is_image_inspect_callee(callee: &Callee) -> bool {
     matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "Image" && name == "inspect")
 }
 
+fn is_image_cache_new_callee(callee: &Callee) -> bool {
+    matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "ImageCache" && name == "new")
+}
+
+fn is_image_cache_store_callee(callee: &Callee) -> bool {
+    matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "ImageCache" && name == "store")
+}
+
+fn is_image_cache_len_callee(callee: &Callee) -> bool {
+    matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "ImageCache" && name == "len")
+}
+
 fn is_json_parse_callee(callee: &Callee) -> bool {
     matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "Json" && name == "parse")
 }

tests/checker.rs

@@ -87,6 +87,11 @@ fn bundled_core_interfaces_are_available_to_checker() {
             .iter()
             .any(|(path, _)| *path == "core/log/log.rssi")
     );
+    assert!(
+        core_interfaces()
+            .iter()
+            .any(|(path, _)| *path == "core/cache/image_cache.rssi")
+    );
     assert!(
         core_interfaces()
             .iter()
@@ -410,6 +415,33 @@ fn process(input: read Path, output: read Path) -> Result<Unit, ImageError> {
     assert!(rust.contains("rsscript_runtime::image_save(&image, &output)?;"));
 }
 
+#[test]
+fn rust_lowering_maps_image_cache_core_calls_to_runtime_hooks() {
+    let source = r#"
+features: local
+
+fn cache_image(input: read Path, output: read Path) -> Result<Unit, ImageError> {
+    local cache = ImageCache.new(capacity: 1)
+    local image = Image.load(path: read input)?
+    let shared = manage image
+    ImageCache.store(cache: mut cache, image: read shared)
+    Image.save(image: read shared, path: read output)?
+    let count = ImageCache.len(cache: read cache)
+    if count == 1 {
+        Log.write(message: read "cached")
+    }
+    return Ok(Unit)
+}
+"#;
+    let rust = lower_source_to_rust("image-cache.rss", source).expect("source should lower");
+
+    assert!(rust.contains("let mut cache = rsscript_runtime::image_cache_new(1);"));
+    assert!(rust.contains("let shared = rsscript_runtime::manage_at(image,"));
+    assert!(rust.contains("rsscript_runtime::image_cache_store(&mut cache, &shared);"));
+    assert!(rust.contains("rsscript_runtime::image_save(&shared, &output)?;"));
+    assert!(rust.contains("let count = rsscript_runtime::image_cache_len(&cache);"));
+}
+
 #[test]
 fn rust_lowering_maps_http_handler_core_calls_to_runtime_hooks() {
     let source = r#"