Add Rust lowering source map artifacts

Author: olwang

README.md

@@ -358,6 +358,10 @@ parser
 semantic checking
 structured diagnostics
 review-oriented rules
+review map metadata
+Rust source lowering
+runtime crate type surface
+source map JSON for generated Rust packages
 ```
 
 The first milestone is not a production runtime.
@@ -437,220 +441,3 @@ compiled through Rust
 ```
 
 RSScript is a language for building software that AI can help write and humans can still trust.
-
-# RSScript
-
-**RSScript is a managed systems language for AI-era software.**
-
-It is designed for a world where code is often generated by AI, but still reviewed, maintained, and operated by humans.
-
-The goal is simple:
-
-```text
-Easy by default.
-Fast where it matters.
-Reviewable at scale.
-```
-
-## Why RSScript exists
-
-AI can generate code much faster than humans can review it.
-
-This changes the bottleneck of software development:
-
-```text
-Before AI:
-  writing code was expensive
-
-After AI:
-  reviewing generated code is expensive
-```
-
-Most existing languages were designed for a world where humans wrote and reviewed code using roughly the same cognitive process.
-
-RSScript is designed for a different workflow:
-
-```text
-AI writes code.
-Humans review semantic changes.
-Tools explain risk.
-```
-
-RSScript aims to make generated code easier to trust by making important behavior visible:
-
-```text
-mutation
-retention
-resource lifetime
-local performance boundaries
-managed/local transitions
-public API changes
-```
-
-## What RSScript is
-
-RSScript is not a “GC Rust” or a “faster Python”.
-
-It is a managed-first language with explicit local control.
-
-Most code should feel simple and managed. Performance-sensitive code can opt into local values. Resources have clear scopes. Public APIs are designed to be easy to review.
-
-The guiding principle is:
-
-```text
-Managed at the surface.
-Local in the engine.
-Reviewable at the boundary.
-```
-
-## Core ideas
-
-RSScript is built around a small set of concepts:
-
-```text
-managed values      default values for ordinary application code
-local values        local exclusive values for performance-sensitive code
-scoped resources    files, sockets, sessions, devices, sandboxes
-parameter effects   visible read / mutation / consumption behavior
-semantic review     tool-assisted review of meaning, not just text diff
-```
-
-The intent is to keep normal code approachable while still giving experts a clear performance path.
-
-## What RSScript optimizes for
-
-RSScript optimizes for three things at once:
-
-### 1. Ease of use
-
-Ordinary code should not require users to think about ownership, lifetimes, or memory management.
-
-Most application state, object graphs, agent memory, configuration, caches, and request/response objects should be managed by default.
-
-### 2. Performance control
-
-Hot paths should have an explicit local-performance path.
-
-Temporary buffers, parser scratch space, JSON decoding, CSV processing, prompt rendering, tool arguments, and similar workloads should be optimizable without rewriting the program in another language.
-
-### 3. Reviewability
-
-Review should focus on semantic changes:
-
-```text
-What now mutates?
-What now retains data?
-What resource scope changed?
-What local value now crosses into managed state?
-What public API changed?
-What new native or unsafe boundary was introduced?
-```
-
-RSScript is designed so tools can answer these questions directly.
-
-## Intended workflow
-
-The intended workflow is:
-
-```sh
-rss check
-rss fmt
-rss review
-rss lower --rust
-rss test
-```
-
-The long-term goal is that a reviewer should not need to read hundreds of lines of AI-generated code line by line.
-
-Instead, RSScript tooling should summarize the semantic risk first, and let humans drill into the code only where necessary.
-
-## Current status
-
-RSScript is experimental.
-
-The current implementation is a Rust-based front-end prototype focused on:
-
-```text
-lexer
-parser
-semantic checking
-structured diagnostics
-review-oriented rules
-```
-
-The first milestone is not a production runtime.
-
-The first milestone is a strong review-first checker that can validate the core language model against real examples.
-
-## Roadmap
-
-Planned stages:
-
-```text
-1. Checker prototype
-2. Real AST parser
-3. HIR and symbol table
-4. Semantic checker
-5. Rust lowering shape contract
-6. Runtime crate type surface
-7. Rust source generation with source maps
-8. rustc diagnostic mapping
-9. Core library signatures
-10. Runnable MVP through rustc
-```
-
-The project will grow by testing the language against real scenarios:
-
-```text
-agent loops
-tool calling
-file and stream processing
-JSON parsing
-configuration loading
-cache updates
-resource pools
-compiler front-end code
-```
-
-## Non-goals
-
-RSScript is not trying to maximize syntax cleverness or type-system expressiveness.
-
-It deliberately avoids:
-
-```text
-implicit conversions
-user-defined operator overloading
-hidden allocation boundaries
-hidden retention behavior
-macro-heavy metaprogramming
-complex public signatures
-Rust-style lifetime syntax
-C++-style implicit magic
-TypeScript-style type gymnastics
-```
-
-The goal is not to make code as short as possible.
-
-The goal is to make code clear enough that humans and tools can review it reliably.
-
-## Long-term vision
-
-RSScript should become a language for building AI-era systems:
-
-```text
-agent runtimes
-developer tools
-automation systems
-reviewable services
-long-running managed applications
-performance-sensitive libraries
-```
-
-It should be easy enough for ordinary application code, explicit enough for systems work, and structured enough for AI-assisted development.
-
-RSScript exists because AI can write code now.
-
-Humans still need to understand it.
-
-```

src/diagnostic.rs

@@ -79,7 +79,7 @@ impl Severity {
     }
 }
 
-#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize)]
 pub struct Span {
     pub file: String,
     pub line: usize,

src/lib.rs

@@ -19,5 +19,7 @@ pub use review::{
     review_sources,
 };
 pub use rust_lower::{
-    GeneratedRustPackage, lower_program_to_rust, lower_source_to_rust, lower_source_to_rust_package,
+    GeneratedRustPackage, LoweredRust, RustSourceMapEntry, lower_program_to_rust,
+    lower_program_to_rust_with_map, lower_source_to_rust, lower_source_to_rust_package,
+    lower_source_to_rust_with_map,
 };

src/main.rs

@@ -192,6 +192,16 @@ fn run_lower_rust_package(path: &str, source: &str, out_dir: &str) -> ExitCode {
         );
         return ExitCode::from(2);
     }
+    if let Err(error) = fs::write(
+        out_dir.join("rsscript-source-map.json"),
+        package.source_map_json,
+    ) {
+        eprintln!(
+            "failed to write {}: {error}",
+            out_dir.join("rsscript-source-map.json").display()
+        );
+        return ExitCode::from(2);
+    }
 
     println!(
         "wrote Rust package `{}` to {}",