Add runnable Image runtime 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`, and `Csv` 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`, and `Image` 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.
 
 Smallest runnable example:
 

examples/image_pipeline.rss

@@ -0,0 +1,20 @@
+features: local
+
+fn main() -> Result<Unit, ImageError> {
+    let input = "rsscript-image-input.bin"
+    let output = "rsscript-image-output.bin"
+
+    with File.open_write(path: read input) as file {
+        File.write(file: mut file, data: read "raw image bytes")?
+    }
+
+    local image = Image.load(path: read input)?
+    Image.resize(image: mut image, width: 320, height: 240)
+    Image.normalize(image: mut image)
+    Image.sharpen(image: mut image)
+    Image.inspect(image: read image)
+    Image.save(image: read image, path: read output)?
+
+    Log.write(message: read "image pipeline ran")
+    return Ok(Unit)
+}

runtime/src/lib.rs

@@ -18,6 +18,41 @@ pub struct File {
 
 impl Resource for File {}
 
+#[derive(Debug, Clone)]
+pub struct Image {
+    bytes: Vec<u8>,
+    width: Option<i64>,
+    height: Option<i64>,
+    operations: Vec<&'static str>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ImageError {
+    message: String,
+}
+
+impl ImageError {
+    fn new(message: impl Into<String>) -> Self {
+        Self {
+            message: message.into(),
+        }
+    }
+}
+
+impl fmt::Display for ImageError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(formatter, "{}", self.message)
+    }
+}
+
+impl std::error::Error for ImageError {}
+
+impl From<std::io::Error> for ImageError {
+    fn from(error: std::io::Error) -> Self {
+        Self::new(error.to_string())
+    }
+}
+
 #[derive(Debug, Clone)]
 pub struct JsonValue {
     inner: serde_json::Value,
@@ -171,6 +206,55 @@ pub fn file_write<B: RuntimeBytes + ?Sized>(file: &mut File, data: &B) -> std::i
     file.inner.write_all(data.as_bytes_slice())
 }
 
+pub fn image_load<P: RuntimePath + ?Sized>(path: &P) -> Result<Image, ImageError> {
+    let bytes = std::fs::read(path.as_path())?;
+    Ok(Image {
+        bytes,
+        width: None,
+        height: None,
+        operations: vec!["load"],
+    })
+}
+
+pub fn image_resize(image: &mut Image, width: i64, height: i64) {
+    image.width = Some(width);
+    image.height = Some(height);
+    image.operations.push("resize");
+}
+
+pub fn image_normalize(image: &mut Image) {
+    image.operations.push("normalize");
+}
+
+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());
+    }
+    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 json_parse(text: &str) -> Result<JsonValue, JsonError> {
     serde_json::from_str(text)
         .map(|inner| JsonValue { inner })
@@ -640,4 +724,29 @@ mod tests {
         assert_eq!(name, "RSScript");
         let _ = std::fs::remove_file(path);
     }
+
+    #[test]
+    fn image_runtime_hooks_load_transform_and_save() {
+        let input = std::env::temp_dir().join(format!(
+            "rsscript-runtime-image-input-{}.bin",
+            std::process::id()
+        ));
+        let output = std::env::temp_dir().join(format!(
+            "rsscript-runtime-image-output-{}.bin",
+            std::process::id()
+        ));
+        std::fs::write(&input, b"image-bytes").expect("input image should be writable");
+
+        let mut image = super::image_load(&input).expect("image should load");
+        super::image_resize(&mut image, 320, 240);
+        super::image_normalize(&mut image);
+        super::image_sharpen(&mut image);
+        super::image_save(&image, &output).expect("image should save");
+
+        let saved = std::fs::read_to_string(&output).expect("saved image should be readable");
+        assert!(saved.contains("rsscript-image-ops:load,resize,normalize,sharpen;size=320x240"));
+
+        let _ = std::fs::remove_file(input);
+        let _ = std::fs::remove_file(output);
+    }
 }

src/rust_lower.rs

@@ -783,6 +783,8 @@ impl<'a> RustLowerer<'a> {
             "Path" => "std::path::PathBuf".to_string(),
             "File" => "rsscript_runtime::File".to_string(),
             "FileError" | "IOError" => "std::io::Error".to_string(),
+            "Image" => "rsscript_runtime::Image".to_string(),
+            "ImageError" => "rsscript_runtime::ImageError".to_string(),
             "JsonValue" => "rsscript_runtime::JsonValue".to_string(),
             "JsonError" => "rsscript_runtime::JsonError".to_string(),
             "RowBuffer" => "rsscript_runtime::RowBuffer".to_string(),
@@ -1064,6 +1066,14 @@ fn lower_callee(callee: &Callee) -> String {
         }
         callee if is_file_read_all_callee(callee) => "rsscript_runtime::file_read_all".to_string(),
         callee if is_file_write_callee(callee) => "rsscript_runtime::file_write".to_string(),
+        callee if is_image_load_callee(callee) => "rsscript_runtime::image_load".to_string(),
+        callee if is_image_resize_callee(callee) => "rsscript_runtime::image_resize".to_string(),
+        callee if is_image_normalize_callee(callee) => {
+            "rsscript_runtime::image_normalize".to_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_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) => {
@@ -1119,6 +1129,30 @@ fn is_file_write_callee(callee: &Callee) -> bool {
     matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "File" && name == "write")
 }
 
+fn is_image_load_callee(callee: &Callee) -> bool {
+    matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "Image" && name == "load")
+}
+
+fn is_image_resize_callee(callee: &Callee) -> bool {
+    matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "Image" && name == "resize")
+}
+
+fn is_image_normalize_callee(callee: &Callee) -> bool {
+    matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "Image" && name == "normalize")
+}
+
+fn is_image_sharpen_callee(callee: &Callee) -> bool {
+    matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "Image" && name == "sharpen")
+}
+
+fn is_image_save_callee(callee: &Callee) -> bool {
+    matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "Image" && name == "save")
+}
+
+fn is_image_inspect_callee(callee: &Callee) -> bool {
+    matches!(callee, Callee::Qualified { namespace, name } if type_root_name(namespace) == "Image" && name == "inspect")
+}
+
 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

@@ -379,6 +379,32 @@ fn read_name(path: read Path) -> Result<String, CsvError> {
     assert!(rust.contains("return rsscript_runtime::row_field_string(&row, 0);"));
 }
 
+#[test]
+fn rust_lowering_maps_image_core_calls_to_runtime_hooks() {
+    let source = r#"
+features: local
+
+fn process(input: read Path, output: read Path) -> Result<Unit, ImageError> {
+    local image = Image.load(path: read input)?
+    Image.resize(image: mut image, width: 320, height: 240)
+    Image.normalize(image: mut image)
+    Image.sharpen(image: mut image)
+    Image.inspect(image: read image)
+    Image.save(image: read image, path: read output)?
+    return Ok(Unit)
+}
+"#;
+    let rust = lower_source_to_rust("image.rss", source).expect("source should lower");
+
+    assert!(rust.contains("-> Result<(), rsscript_runtime::ImageError>"));
+    assert!(rust.contains("let mut image = rsscript_runtime::image_load(&input)?;"));
+    assert!(rust.contains("rsscript_runtime::image_resize(&mut image, 320, 240);"));
+    assert!(rust.contains("rsscript_runtime::image_normalize(&mut image);"));
+    assert!(rust.contains("rsscript_runtime::image_sharpen(&mut image);"));
+    assert!(rust.contains("rsscript_runtime::image_inspect(&image);"));
+    assert!(rust.contains("rsscript_runtime::image_save(&image, &output)?;"));
+}
+
 #[test]
 fn rust_lowering_decodes_string_escape_sequences() {
     let source = r#"