Add package semantic lock output

Author: olwang

Cargo.lock

@@ -15,6 +15,7 @@ path = "src/main.rs"
 [dependencies]
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+sha2 = "0.10"
 toml = "0.8"
 
 [dev-dependencies]

Cargo.toml

@@ -9,7 +9,7 @@ Reviewable by design.
 Compiled through Rust.
 ```
 
-I like Rust. But AI-generated Rust is hard to review at speed: lifetimes, ownership shapes, trait-heavy APIs, mutation boundaries, retention — all technically correct, all expensive to audit when a single PR drops hundreds of new lines on you.
+I like Rust, and that is where this project starts. AI-generated Rust can be hard to review at speed: lifetimes, ownership shapes, trait-heavy APIs, mutation boundaries, retention — all technically correct, all expensive to audit when a single PR drops hundreds of new lines on you.
 
 RSScript is an experiment in putting a smaller, review-first semantic layer in front of Rust. It keeps rustc, Cargo, and the crate ecosystem; it just makes mutation, retention, resources, native boundaries, and managed/local transitions explicit *before* the Rust gets generated.
 
@@ -23,7 +23,7 @@ One question drives the design:
 
 Before AI, writing code was expensive and reviewing was manageable. That ratio has flipped — generating code is now cheap, reviewing generated code is the bottleneck.
 
-Existing languages were designed for humans writing code by hand. RSScript is designed for a workflow where AI writes, the compiler checks semantic boundaries, and humans review the *risk*, not every line. So the things that actually matter to a reviewer — what mutates, what gets retained, who owns a resource, where you cross into native or unsafe, what changed in a public API — are pushed into source and machine-readable diagnostics instead of being inferred from context.
+Existing languages were designed for humans writing code by hand. RSScript is designed for a workflow where AI writes, the compiler checks semantic boundaries, and humans review the *risk profile first*. So the things that actually matter to a reviewer — what mutates, what gets retained, who owns a resource, where you cross into native or unsafe, what changed in a public API — are pushed into source and machine-readable diagnostics instead of being inferred from context.
 
 ---
 
@@ -38,11 +38,11 @@ let user = User.load(id: read user_id)
 let response = Response.ok(body: read user)
 ```
 
-Managed values are easy to share, store, and drop into long-lived graphs. This is the default for business logic, agent memory, configuration, caches, ASTs, request/response objects — anything that isn't a hot path.
+Managed values are easy to share, store, and drop into long-lived graphs. This is the default for business logic, agent memory, configuration, caches, ASTs, request/response objects — the broad layer outside hot paths.
 
 ### Local when it matters
 
-Hot paths can opt in to local exclusive values, which can't be silently retained by managed objects or captured by managed closures:
+Hot paths can opt in to local exclusive values, and the checker protects those values from silent retention by managed objects or managed closures:
 
 ```rust
 features: local
@@ -64,7 +64,7 @@ Files are managed-only unless they declare otherwise:
 features: local
 ```
 
-Only `local` is implemented today. Names like `native`, `unsafe`, `async`, `device`, `ffi`, and `reflection` are reserved for capabilities that genuinely change review risk. Ordinary libraries (JSON, File, Image, HTTP, Map, Regex) are *not* features. Repeated or unknown names are diagnostics — capability boundaries shouldn't be silently normalized away.
+Only `local` is implemented today. Names like `native`, `unsafe`, `async`, `device`, `ffi`, and `reflection` are reserved for capabilities that genuinely change review risk. Ordinary libraries (JSON, File, Image, HTTP, Map, Regex) stay as libraries. Repeated or unknown names are diagnostics so capability boundaries stay explicit.
 
 ---
 
@@ -139,13 +139,13 @@ User-facing APIs stay simple:
 let json = Json.parse(text: read body)?
 ```
 
-Internals can use local scratch and `*_into` forms for low-allocation paths, but that complexity doesn't leak out.
+Internals can use local scratch and `*_into` forms for low-allocation paths, while the public surface stays managed and reviewable.
 
 ---
 
 ## Semantic review
 
-Review is meant to be semantic, not just textual diff.
+Review is meant to be semantic and stronger than textual diff.
 
 ```sh
 rss review --diff base/ changed/
@@ -175,7 +175,7 @@ FOLDABLE
   private pure helpers, no retention, no resources
 ```
 
-RSScript doesn't eliminate human review. It moves human review up a level.
+RSScript moves human review up a level.
 
 ---
 
@@ -199,7 +199,7 @@ This is an architectural choice. The value is in the front end; the back end is
 
 ## Status
 
-Experimental. The current implementation is a Rust-based front-end prototype: lexer, parser, semantic checker with the review-oriented rules, structured diagnostics, review-map metadata, package review/diff metadata, Rust source lowering with source maps, rustc diagnostic remapping, a small runtime crate, and core `.rssi` interface signatures (parsed as ordinary files, not a hand-written builtin table). CI gates formatting, lint, tests, and generated-Rust fixtures; golden tests cover lowering and source-map shape.
+Experimental. The current implementation is a Rust-based front-end prototype: lexer, parser, semantic checker with the review-oriented rules, structured diagnostics, review-map metadata, package review/diff/lock metadata, Rust source lowering with source maps, rustc diagnostic remapping, a small runtime crate, and core `.rssi` interface signatures parsed through the ordinary interface path. CI gates formatting, lint, tests, and generated-Rust fixtures; golden tests cover lowering and source-map shape.
 
 The first milestone is a checker strong enough to validate the language model against real examples.
 
@@ -213,6 +213,7 @@ rss fmt      <file.rss>
 rss review   [--json] --diff <old.rss> <new.rss>
 rss review   [--json] --map  <file-or-directory>
 rss package  review [--json] <package-directory>
+rss package  lock   [--json] <package-directory>
 rss package  diff   [--json] <old-package-directory> <new-package-directory>
 rss lower    --rust  <file.rss> [--out-dir <directory>]
 rss run      [--json] <file.rss> [--out-dir <directory>]
@@ -226,6 +227,7 @@ A few details worth knowing:
 - `rss lint` reuses the frontend checks and emits warnings. The first lint is `RSL001` — public signatures over the review budget for parameter count, generics, effects, or nested-type depth.
 - `rss review --map` validates inputs first, so files with frontend errors get diagnostics instead of misleading classifications.
 - `rss package review` reads `rsspkg.toml`, treats `.rssi` files as the public semantic contract, and raises risk for native Rust wrappers, build scripts, proc macros, unsafe policy, external links, frontend diagnostics, and unknown review-map regions.
+- `rss package lock` emits root package lock metadata with SHA-256 hashes for the public `.rssi` contract, review metadata, package contents, and native Rust wrapper contents when enabled.
 - `rss package diff` compares two local package directories and reports package version changes, RSScript dependency changes, package feature changes, native Rust wrapper metadata changes, and public `.rssi` semantic contract changes.
 - `rss run` lowers to a temporary Rust package and delegates to `cargo run`; `--out-dir` keeps the generated package around for inspection. Diagnostics support `--json`; program stdout stays the program's own.
 - `rss verify-rust --out-dir` keeps the generated package and source map, so unmappable rustc diagnostics can be inspected against the actual generated Rust.

README.md

@@ -19,11 +19,12 @@ pub use diagnostic::{
 };
 pub use lint::lint_source;
 pub use package::{
-    PackageDiff, PackageIdentity, PackageInterfaceChange, PackageInterfaceChangeKind,
-    PackageManifestChange, PackageNativeRustReview, PackageReview, PackageReviewFile,
-    PackageReviewFileKind, PackageReviewSummary, PackageRisk, diff_package_dirs,
-    format_package_diff_human, format_package_diff_json, format_package_review_human,
-    format_package_review_json, review_package_dir,
+    PackageDiff, PackageIdentity, PackageInterfaceChange, PackageInterfaceChangeKind, PackageLock,
+    PackageLockMetadata, PackageLockPackage, PackageManifestChange, PackageNativeRustReview,
+    PackageReview, PackageReviewFile, PackageReviewFileKind, PackageReviewSummary, PackageRisk,
+    diff_package_dirs, format_package_diff_human, format_package_diff_json,
+    format_package_lock_json, format_package_lock_toml, format_package_review_human,
+    format_package_review_json, lock_package_dir, review_package_dir,
 };
 pub use review::{
     ReviewFinding, ReviewFix, ReviewMap, ReviewMapCategorySummary, ReviewMapClassification,

src/lib.rs

@@ -8,11 +8,12 @@ use rsscript::{
     Diagnostic, analyze_source, analyze_source_with_interfaces, check_generated_rust_package,
     core_interfaces, diff_package_dirs, explain_diagnostic_code, format_diagnostic_explanation,
     format_diagnostics_human, format_diagnostics_json, format_package_diff_human,
-    format_package_diff_json, format_package_review_human, format_package_review_json,
-    format_review_human, format_review_json, format_review_map_human, format_review_map_json,
-    lint_source, lower_source_to_rust, lower_source_to_rust_package, parse_runtime_diagnostics,
-    parse_source_map_json, remap_rustc_diagnostic_json_lines, review_map_sources,
-    review_package_dir, review_sources, write_generated_rust_package,
+    format_package_diff_json, format_package_lock_json, format_package_lock_toml,
+    format_package_review_human, format_package_review_json, format_review_human,
+    format_review_json, format_review_map_human, format_review_map_json, lint_source,
+    lock_package_dir, lower_source_to_rust, lower_source_to_rust_package,
+    parse_runtime_diagnostics, parse_source_map_json, remap_rustc_diagnostic_json_lines,
+    review_map_sources, review_package_dir, review_sources, write_generated_rust_package,
 };
 
 fn main() -> ExitCode {
@@ -42,6 +43,7 @@ fn main() -> ExitCode {
 fn run_package(args: &[String]) -> ExitCode {
     match parse_package_args(args) {
         PackageCommand::Review { json, path } => run_package_review(json, path),
+        PackageCommand::Lock { json, path } => run_package_lock(json, path),
         PackageCommand::Diff {
             json,
             old_path,
@@ -788,6 +790,10 @@ enum PackageCommand<'a> {
         json: bool,
         path: &'a str,
     },
+    Lock {
+        json: bool,
+        path: &'a str,
+    },
     Diff {
         json: bool,
         old_path: &'a str,
@@ -804,7 +810,7 @@ fn parse_package_args(args: &[String]) -> PackageCommand<'_> {
     for arg in args {
         if arg == "--json" {
             json = true;
-        } else if arg == "review" || arg == "diff" {
+        } else if arg == "review" || arg == "lock" || arg == "diff" {
             command = Some(arg.as_str());
         } else {
             paths.push(arg.as_str());
@@ -813,6 +819,7 @@ fn parse_package_args(args: &[String]) -> PackageCommand<'_> {
 
     match (command, paths.as_slice()) {
         (Some("review"), [path]) => PackageCommand::Review { json, path },
+        (Some("lock"), [path]) => PackageCommand::Lock { json, path },
         (Some("diff"), [old_path, new_path]) => PackageCommand::Diff {
             json,
             old_path,
@@ -953,6 +960,23 @@ fn run_package_review(json: bool, path: &str) -> ExitCode {
     }
 }
 
+fn run_package_lock(json: bool, path: &str) -> ExitCode {
+    let lock = match lock_package_dir(Path::new(path)) {
+        Ok(lock) => lock,
+        Err(error) => {
+            eprintln!("{error}");
+            return ExitCode::from(2);
+        }
+    };
+
+    if json {
+        println!("{}", format_package_lock_json(&lock));
+    } else {
+        print!("{}", format_package_lock_toml(&lock));
+    }
+    ExitCode::SUCCESS
+}
+
 fn run_package_diff(json: bool, old_path: &str, new_path: &str) -> ExitCode {
     let diff = match diff_package_dirs(Path::new(old_path), Path::new(new_path)) {
         Ok(diff) => diff,
@@ -1047,5 +1071,6 @@ fn print_usage() {
     eprintln!("  rsscript review [--json] --diff <old.rss> <new.rss>");
     eprintln!("  rsscript review [--json] --map <file-or-directory>");
     eprintln!("  rsscript package review [--json] <package-directory>");
+    eprintln!("  rsscript package lock [--json] <package-directory>");
     eprintln!("  rsscript package diff [--json] <old-package-directory> <new-package-directory>");
 }