rsscript: #lower_name("...") backend-name escape hatch

Add a function attribute that pins a declaration's generated Rust symbol, for
FFI/autogen boundaries and compiler transitions. Follows the existing
`#deprecated("...")` attribute convention.

- Parser: extend the function attribute loop to accept `#lower_name("...")`;
  store it on `FunctionDecl.lower_name`.
- Lowering: a per-run thread-local override map (populated from the program's
  pins) is consulted by the canonical name-lowering helpers (`rust_function_ident`,
  `rust_qualified_function_ident`, and `lower_callee`'s free-call path), so the
  pinned symbol is used at the definition and every call site.
- Inventory: `symbol_inventory` installs the same overrides so `lowered_name`
  reports the pinned symbol.
- Checker (RS0035): a pin must be a valid Rust identifier and must not collide
  with another function's final backend name.
- Formatter round-trips the attribute.

Tests: symbol-inventory pin test, definition+call-site lowering test, pass
fixture, two fail fixtures (conflict + invalid), formatter round-trip. Full
`cargo test -p rsscript` green; clippy clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Haofei

crates/rsscript/src/analyzer.rs

@@ -1039,6 +1039,7 @@ impl Analyzer<'_> {
         self.check_async_fn_lowerable();
         self.check_match_exhaustiveness();
         self.check_duplicate_declarations();
+        self.check_lowered_name_conflicts();
         self.check_protocol_contracts();
         self.check_signature_explicitness();
         self.check_unknown_types();
@@ -3737,6 +3738,72 @@ impl Analyzer<'_> {
         }
     }
 
+    /// Validate `#lower_name("...")` pins: each must be a valid Rust identifier,
+    /// and no pin may collide with another function's final backend name (pinned
+    /// or default), so generated symbols stay unique. Only conflicts that involve
+    /// at least one pin are reported here (plain default collisions, if any, are a
+    /// separate concern from this escape hatch).
+    fn check_lowered_name_conflicts(&mut self) {
+        use crate::rust_lower::lowered_symbol_name;
+        let mut seen: HashMap<String, (String, bool)> = HashMap::new();
+        let mut conflicts: Vec<(crate::diagnostic::Span, String, String)> = Vec::new();
+        let mut invalid: Vec<(crate::diagnostic::Span, String)> = Vec::new();
+        for item in &self.syntax_program.items {
+            let crate::syntax::ast::Item::Function(function) = item else {
+                continue;
+            };
+            let pinned = function.lower_name.as_deref();
+            if let Some(pin) = pinned
+                && !is_valid_rust_identifier(pin)
+            {
+                invalid.push((function.span.clone(), pin.to_string()));
+                continue;
+            }
+            let lowered = pinned
+                .map(str::to_string)
+                .unwrap_or_else(|| lowered_symbol_name(&function.name));
+            let is_pinned = pinned.is_some();
+            if let Some((first_name, first_pinned)) = seen.get(&lowered) {
+                if is_pinned || *first_pinned {
+                    conflicts.push((function.span.clone(), lowered.clone(), first_name.clone()));
+                }
+            } else {
+                seen.insert(lowered, (function.name.clone(), is_pinned));
+            }
+        }
+        for (span, pin) in invalid {
+            self.diagnostics.push(
+                Diagnostic::error(
+                    code::LOWER_NAME_CONFLICT,
+                    format!("`#lower_name(\"{pin}\")` is not a valid Rust identifier."),
+                    span,
+                    "invalid lowered name",
+                )
+                .with_cause(
+                    "A pinned backend name must be a plain Rust identifier (letters, digits, and underscores, not starting with a digit).",
+                ),
+            );
+        }
+        for (span, lowered, first_name) in conflicts {
+            self.diagnostics.push(
+                Diagnostic::error(
+                    code::LOWER_NAME_CONFLICT,
+                    format!("lowered backend name `{lowered}` is already used by `{first_name}`."),
+                    span,
+                    "lowered name conflict",
+                )
+                .with_cause(
+                    "Two declarations would lower to the same Rust symbol; a `#lower_name(\"...\")` pin must be unique.",
+                )
+                .with_fix(
+                    "rename_lowered",
+                    "Choose a different `#lower_name(\"...\")` value.",
+                    "manual",
+                ),
+            );
+        }
+    }
+
     fn check_duplicate_declarations(&mut self) {
         for duplicate in self.hir.duplicate_symbols() {
             self.diagnostics.push(
@@ -6253,6 +6320,19 @@ fn type_ref_name(ty: &TypeRef) -> String {
     }
 }
 
+/// Whether `name` is a plain Rust identifier (used verbatim as a pinned backend
+/// symbol): non-empty, starts with a letter or `_`, and otherwise alphanumeric or
+/// `_`. Raw identifiers and keywords are intentionally rejected.
+fn is_valid_rust_identifier(name: &str) -> bool {
+    let mut chars = name.chars();
+    let Some(first) = chars.next() else {
+        return false;
+    };
+    (first.is_ascii_alphabetic() || first == '_')
+        && chars.all(|ch| ch.is_ascii_alphanumeric() || ch == '_')
+        && !crate::rust_lower::is_rust_keyword(name)
+}
+
 fn type_ref_is_noescape(ty: &TypeRef) -> bool {
     ty.is_noescape || ty.args.iter().any(type_ref_is_noescape)
 }

crates/rsscript/src/diagnostic.rs

@@ -38,6 +38,7 @@ pub mod code {
     pub const PROTOCOL_NOT_SATISFIED: &str = "RS0032";
     pub const INTEGER_LITERAL_OUT_OF_RANGE: &str = "RS0033";
     pub const UNINFERABLE_BINDING_TYPE: &str = "RS0034";
+    pub const LOWER_NAME_CONFLICT: &str = "RS0035";
     pub const FEATURE_VIOLATION: &str = "RS0101";
     pub const UNNAMED_ARGUMENT: &str = "RS0201";
     pub const MISSING_DATA_EFFECT: &str = "RS0202";
@@ -445,6 +446,11 @@ static DIAGNOSTIC_EXPLANATIONS: &[DiagnosticExplanation] = &[
         title: "invalid noalloc call",
         explanation: "`effects(noalloc)` is a guarantee that the function performs no heap allocation. Calls inside it must target enum variants or functions also declared `effects(noalloc)`, while direct constructors and `manage` are allocation diagnostics.",
     },
+    DiagnosticExplanation {
+        code: code::LOWER_NAME_CONFLICT,
+        title: "lowered name conflict",
+        explanation: "A `#lower_name(\"...\")` pin must be a valid Rust identifier and must not collide with any other declaration's lowered backend name, so generated symbols stay unique.",
+    },
     DiagnosticExplanation {
         code: code::NON_EXHAUSTIVE_MATCH,
         title: "non-exhaustive match",

crates/rsscript/src/formatter.rs

@@ -254,6 +254,9 @@ impl Formatter {
     }
 
     fn function_decl(&mut self, function: &FunctionDecl) {
+        if let Some(lower_name) = &function.lower_name {
+            self.out.push_str(&format!("#lower_name({})\n", quoted_string(lower_name)));
+        }
         let mut prefix = String::new();
         if function.is_public {
             prefix.push_str("pub ");
@@ -1892,6 +1895,18 @@ impl Writer for BufferWriter {
         );
     }
 
+    #[test]
+    fn round_trips_lower_name_attribute() {
+        let source = "#lower_name(\"helpers__count\")\nfn count(value: read Int) -> Int {\n    return value\n}\n";
+        // The pin must survive formatting (idempotent + lossless).
+        let formatted = format_source("pin.rss", source);
+        assert!(
+            formatted.contains("#lower_name(\"helpers__count\")"),
+            "formatter dropped the lower_name pin:\n{formatted}"
+        );
+        assert_eq!(format_source("pin.rss", &formatted), formatted);
+    }
+
     #[test]
     fn renders_list_slice_patterns() {
         let source = r#"features: local

crates/rsscript/src/rust_lower/helpers.rs

@@ -1260,7 +1260,10 @@ pub(super) fn lower_callee(callee: &Callee) -> String {
     }
 
     match callee {
-        Callee::Name(name) => rust_ident(type_root_name(name)),
+        Callee::Name(name) => {
+            let canonical = type_root_name(name);
+            lower_name_override(canonical).unwrap_or_else(|| rust_ident(canonical))
+        }
         Callee::Qualified { namespace, name } if type_root_name(namespace) == "ResourcePool" => {
             format!(
                 "rsscript_runtime::ResourcePool::{}",
@@ -1613,12 +1616,41 @@ pub(super) fn lower_source_span(span: &Span) -> String {
     )
 }
 
+thread_local! {
+    /// Per-lowering-run map from a function's source qualified name (e.g.
+    /// `helpers.count`) to its pinned backend name from `#lower_name("...")`.
+    /// Populated before a lowering run (and before building the symbol inventory)
+    /// and consulted by the canonical name-lowering helpers so the emitted Rust
+    /// symbol and the reported `lowered_name` always agree.
+    static LOWER_NAME_OVERRIDES: std::cell::RefCell<std::collections::HashMap<String, String>> =
+        std::cell::RefCell::new(std::collections::HashMap::new());
+}
+
+/// Install the pinned-name overrides for the current thread; pass an empty map to
+/// disable. Returns the previous map so callers can restore it.
+pub(crate) fn set_lower_name_overrides(
+    overrides: std::collections::HashMap<String, String>,
+) -> std::collections::HashMap<String, String> {
+    LOWER_NAME_OVERRIDES.with(|cell| cell.replace(overrides))
+}
+
+fn lower_name_override(source_name: &str) -> Option<String> {
+    LOWER_NAME_OVERRIDES.with(|cell| cell.borrow().get(source_name).cloned())
+}
+
 pub(super) fn rust_function_ident(name: &str) -> String {
+    if let Some(pinned) = lower_name_override(name) {
+        return pinned;
+    }
     let joined = name.split('.').collect::<Vec<_>>().join("_");
     rust_ident(&joined)
 }
 
 pub(super) fn rust_qualified_function_ident(namespace: &str, name: &str) -> String {
+    let source_name = format!("{namespace}.{}", type_root_name(name));
+    if let Some(pinned) = lower_name_override(&source_name) {
+        return pinned;
+    }
     namespace
         .split('.')
         .chain(std::iter::once(type_root_name(name)))
@@ -1637,7 +1669,7 @@ pub(super) fn rust_path_segment(segment: &str) -> String {
 
 /// Whether `name` is a Rust keyword (strict or reserved) that cannot be used as a
 /// bare identifier.
-pub(super) fn is_rust_keyword(name: &str) -> bool {
+pub(crate) fn is_rust_keyword(name: &str) -> bool {
     const KEYWORDS: &[&str] = &[
         "abstract", "as", "async", "await", "become", "box", "break", "const", "continue", "crate",
         "do", "dyn", "else", "enum", "extern", "false", "final", "fn", "for", "gen", "if", "impl",

crates/rsscript/src/rust_lower/lowerer.rs

@@ -128,6 +128,10 @@ impl<'a> RustLowerer<'a> {
     }
 
     pub(super) fn lower(mut self) -> LoweredRust {
+        // Install this program's `#lower_name(...)` pins for the duration of the
+        // run so the canonical name-lowering helpers emit the pinned symbols.
+        let previous_overrides =
+            set_lower_name_overrides(super::collect_lower_name_overrides(self.program));
         let mut out = String::new();
         out.push_str("// Generated by RSScript. Edit the .rss source instead.\n");
         out.push_str(
@@ -194,6 +198,7 @@ impl<'a> RustLowerer<'a> {
             out.pop();
         }
 
+        set_lower_name_overrides(previous_overrides);
         LoweredRust {
             rust_source: out,
             source_map: self.source_map,

crates/rsscript/src/rust_lower/mod.rs

@@ -18,6 +18,7 @@ mod runtime_diagnostics;
 mod source_map;
 mod types;
 
+pub(crate) use helpers::{is_rust_keyword, set_lower_name_overrides};
 pub use backend_check::check_generated_rust_package;
 pub use runtime_diagnostics::parse_runtime_diagnostics;
 pub use source_map::{
@@ -41,6 +42,25 @@ pub fn lowered_symbol_name(qualified_name: &str) -> String {
     helpers::rust_function_ident(qualified_name)
 }
 
+/// Collect the `#lower_name("...")` pins a program's functions declare, keyed by
+/// source qualified name. Both the lowerer and the symbol inventory install
+/// these so the emitted Rust symbol and the reported `lowered_name` agree.
+pub(crate) fn collect_lower_name_overrides(
+    program: &Program,
+) -> std::collections::HashMap<String, String> {
+    program
+        .items
+        .iter()
+        .filter_map(|item| match item {
+            crate::syntax::ast::Item::Function(function) => function
+                .lower_name
+                .as_ref()
+                .map(|pinned| (function.name.clone(), pinned.clone())),
+            _ => None,
+        })
+        .collect()
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
 pub struct LowerCoverageReport {
     pub runtime_intrinsics: CoverageBucket,

crates/rsscript/src/symbols.rs

@@ -120,8 +120,12 @@ pub fn symbol_inventory(file: &str, source: &str) -> Vec<SymbolInventoryEntry> {
         .and_then(|stem| stem.to_str())
         .unwrap_or(file)
         .to_string();
+    // Install this file's `#lower_name(...)` pins so the reported `lowered_name`
+    // matches the symbol the backend actually emits.
+    let overrides = crate::rust_lower::collect_lower_name_overrides(&parse_source_raw(file, source));
+    let previous = crate::rust_lower::set_lower_name_overrides(overrides);
     let index = symbol_index(file, source);
-    index
+    let entries = index
         .definitions()
         .iter()
         .filter(|definition| {
@@ -137,7 +141,9 @@ pub fn symbol_inventory(file: &str, source: &str) -> Vec<SymbolInventoryEntry> {
             span: definition.span.clone(),
             lowered_name: crate::rust_lower::lowered_symbol_name(&definition.name),
         })
-        .collect()
+        .collect();
+    crate::rust_lower::set_lower_name_overrides(previous);
+    entries
 }
 
 /// Parse `source` and return a top-level document outline.
@@ -989,6 +995,23 @@ mod tests {
         assert_eq!(find("Device").kind, SymbolKind::Type);
     }
 
+    #[test]
+    fn symbol_inventory_reflects_lower_name_pin() {
+        let source = concat!(
+            "#lower_name(\"helpers__count\")\n",
+            "fn count(value: read Int) -> Int {\n",
+            "    return value\n",
+            "}\n",
+        );
+        let inventory = symbol_inventory("helpers.rss", source);
+        let count = inventory
+            .iter()
+            .find(|entry| entry.qualname == "count")
+            .expect("count in inventory");
+        // The pinned backend name overrides the default flattened symbol.
+        assert_eq!(count.lowered_name, "helpers__count");
+    }
+
     const SOURCE: &str = concat!(
         "fn helper(value: read Int) -> Int {\n",
         "    return value\n",

crates/rsscript/src/syntax/ast.rs

@@ -272,6 +272,11 @@ pub struct FunctionDecl {
     pub has_body: bool,
     pub default_impl_marker: bool,
     pub deprecated_reason: Option<String>,
+    /// An explicit pinned backend name from `#lower_name("...")`. When set, the
+    /// function lowers to exactly this Rust symbol (rather than the flattened
+    /// default) and the symbol inventory reports it. Used for FFI/autogen
+    /// boundaries and compiler transitions.
+    pub lower_name: Option<String>,
     pub type_params: Vec<GenericParam>,
     pub malformed_generic_param_spans: Vec<Span>,
     pub params: Vec<Param>,

crates/rsscript/src/syntax/parser.rs

@@ -461,23 +461,32 @@ impl Parser<'_> {
         let start = self.index;
         let span = self.current()?.span.clone();
         let mut deprecated_reason = None;
+        let mut lower_name = None;
         while self.at_symbol("#") {
             self.index += 1;
-            if !self.at_ident("deprecated") {
+            let attribute = if self.at_ident("deprecated") {
+                "deprecated"
+            } else if self.at_ident("lower_name") {
+                "lower_name"
+            } else {
                 self.index = start;
                 return None;
-            }
+            };
             self.index += 1;
             if !self.at_symbol("(") {
                 self.index = start;
                 return None;
             }
             self.index += 1;
-            let Some(TokenKind::String(reason)) = self.current().map(|token| &token.kind) else {
+            let Some(TokenKind::String(value)) = self.current().map(|token| &token.kind) else {
                 self.index = start;
                 return None;
             };
-            deprecated_reason = Some(reason.clone());
+            match attribute {
+                "deprecated" => deprecated_reason = Some(value.clone()),
+                "lower_name" => lower_name = Some(value.clone()),
+                _ => unreachable!(),
+            }
             self.index += 1;
             if !self.at_symbol(")") {
                 self.index = start;
@@ -585,6 +594,7 @@ impl Parser<'_> {
             has_body,
             default_impl_marker,
             deprecated_reason,
+            lower_name,
             type_params,
             malformed_generic_param_spans,
             params,