rsscript: compact [adapter.*] whole-boundary native bindings

Closes the named P1-3 gap — "binding whole boundaries compactly without large
wrapper files". native/bindings.rssbind.toml gains an [adapter.<Namespace>]
section: one `crate` plus a `functions` list (and optional `rename` map) binds an
entire native namespace, so a boundary with N functions no longer needs N
[bindings] lines repeating the `Namespace.` prefix and `crate::` path.

Expansion happens at manifest-load time in flatten_native_bindings, producing the
exact same flat `symbol -> rust target` map every consumer already uses (Rust
lowering, the VM shim via package_lowering_input, and the binding-conformance
checks). Single expansion point, identical downstream data => zero VM/compiled
parity risk. Every method stays listed by name so the boundary remains
review-visible; duplicates across an adapter and explicit [bindings] are rejected.

Unit-tested for expansion, rename override, explicit+adapter composition,
duplicate rejection, and equivalence to the explicit form. Documented in
package-manager design §9.5 and spec §20.1-N.

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

Author: olwang

crates/rsscript/src/package/native.rs

@@ -45,6 +45,70 @@ struct CargoMetadataTarget {
 struct NativeBindingsManifest {
     #[serde(default)]
     bindings: BTreeMap<String, String>,
+    /// Compact whole-boundary binding: one `[adapter.<Namespace>]` section binds
+    /// many `Namespace.method` native functions to `<crate>::<method>` without a
+    /// per-function line. Expands into `bindings` at load time, so every
+    /// downstream consumer (lowering, VM shim, conformance checks) sees the same
+    /// flat map — there is no separate adapter code path.
+    #[serde(default)]
+    adapter: BTreeMap<String, AdapterBinding>,
+}
+
+#[derive(Debug, Deserialize)]
+struct AdapterBinding {
+    /// The Rust wrapper crate that owns every method in this boundary.
+    #[serde(rename = "crate")]
+    crate_name: String,
+    /// Method names declared under the namespace (the part after the dot). Each
+    /// `m` binds `Namespace.m` to `<crate>::m`.
+    #[serde(default)]
+    functions: Vec<String>,
+    /// Optional per-method Rust name overrides for `m` whose Rust function name
+    /// differs from the RSScript method name (`Namespace.m -> <crate>::<rename[m]>`).
+    #[serde(default)]
+    rename: BTreeMap<String, String>,
+}
+
+/// Flatten a binding manifest into the canonical `symbol -> rust target` map,
+/// expanding any compact `[adapter.*]` sections. Errors on malformed adapters and
+/// on a symbol produced by more than one source (explicit binding or adapter), so
+/// the binding surface stays unambiguous for review.
+fn flatten_native_bindings(
+    manifest: NativeBindingsManifest,
+) -> Result<BTreeMap<String, String>, String> {
+    let mut flat = manifest.bindings;
+    for (namespace, adapter) in manifest.adapter {
+        let crate_name = adapter.crate_name.trim();
+        if crate_name.is_empty() {
+            return Err(format!(
+                "adapter `{namespace}` must set a non-empty `crate`."
+            ));
+        }
+        if adapter.functions.is_empty() {
+            return Err(format!(
+                "adapter `{namespace}` lists no `functions`; add the method names it binds or remove the section."
+            ));
+        }
+        for method in &adapter.functions {
+            let method = method.trim();
+            if method.is_empty() {
+                return Err(format!("adapter `{namespace}` has an empty function name."));
+            }
+            let symbol = format!("{namespace}.{method}");
+            let rust_method = adapter
+                .rename
+                .get(method)
+                .map(String::as_str)
+                .unwrap_or(method);
+            let target = format!("{crate_name}::{rust_method}");
+            if flat.insert(symbol.clone(), target).is_some() {
+                return Err(format!(
+                    "native binding `{symbol}` is defined twice (by `[adapter.{namespace}]` and an explicit `[bindings]` entry, or duplicated)."
+                ));
+            }
+        }
+    }
+    Ok(flat)
 }
 
 pub(super) fn package_native_rust_dependencies(
@@ -190,7 +254,7 @@ pub(super) fn package_native_bindings(
         .map_err(|error| format!("failed to read {}: {error}", path.display()))?;
     let manifest: NativeBindingsManifest = toml::from_str(&source)
         .map_err(|error| format!("failed to parse {}: {error}", path.display()))?;
-    Ok(manifest.bindings)
+    flatten_native_bindings(manifest).map_err(|error| format!("{}: {error}", path.display()))
 }
 
 pub(super) fn native_binding_interface_sources(
@@ -1035,3 +1099,87 @@ pub(super) fn manifest_native_unsafe_boundary(manifest: &Manifest) -> bool {
         .and_then(|native| native.effective_unsafe_policy())
         .is_some_and(|policy| policy != "forbid")
 }
+
+#[cfg(test)]
+mod adapter_binding_tests {
+    use super::*;
+
+    fn flatten(toml_src: &str) -> Result<BTreeMap<String, String>, String> {
+        let manifest: NativeBindingsManifest = toml::from_str(toml_src).expect("manifest parses");
+        flatten_native_bindings(manifest)
+    }
+
+    #[test]
+    fn adapter_section_expands_to_per_method_bindings() {
+        let flat = flatten(
+            "[adapter.Rayon]\ncrate = \"rss_rayon_native\"\nfunctions = [\"sum_int\", \"sort_int\"]\n",
+        )
+        .expect("adapter expands");
+        assert_eq!(
+            flat.get("Rayon.sum_int").map(String::as_str),
+            Some("rss_rayon_native::sum_int")
+        );
+        assert_eq!(
+            flat.get("Rayon.sort_int").map(String::as_str),
+            Some("rss_rayon_native::sort_int")
+        );
+        assert_eq!(flat.len(), 2);
+    }
+
+    #[test]
+    fn adapter_form_matches_the_explicit_form() {
+        let compact = flatten(
+            "[adapter.Rayon]\ncrate = \"rss_rayon_native\"\nfunctions = [\"sum_int\", \"sort_int\"]\n",
+        )
+        .unwrap();
+        let explicit = flatten(
+            "[bindings]\n\"Rayon.sum_int\" = \"rss_rayon_native::sum_int\"\n\"Rayon.sort_int\" = \"rss_rayon_native::sort_int\"\n",
+        )
+        .unwrap();
+        assert_eq!(compact, explicit);
+    }
+
+    #[test]
+    fn rename_overrides_the_rust_method_name() {
+        let flat = flatten(
+            "[adapter.File]\ncrate = \"file_native\"\nfunctions = [\"open\"]\n\n[adapter.File.rename]\nopen = \"open_file\"\n",
+        )
+        .unwrap();
+        assert_eq!(
+            flat.get("File.open").map(String::as_str),
+            Some("file_native::open_file")
+        );
+    }
+
+    #[test]
+    fn explicit_bindings_and_adapters_compose() {
+        let flat = flatten(
+            "[bindings]\n\"Extra.ping\" = \"extra::ping\"\n\n[adapter.File]\ncrate = \"file_native\"\nfunctions = [\"open\"]\n",
+        )
+        .unwrap();
+        assert_eq!(flat.len(), 2);
+        assert!(flat.contains_key("Extra.ping"));
+        assert!(flat.contains_key("File.open"));
+    }
+
+    #[test]
+    fn duplicate_symbol_across_adapter_and_bindings_errors() {
+        let error = flatten(
+            "[bindings]\n\"File.open\" = \"file_native::open\"\n\n[adapter.File]\ncrate = \"file_native\"\nfunctions = [\"open\"]\n",
+        )
+        .expect_err("duplicate symbol should error");
+        assert!(error.contains("File.open"), "error: {error}");
+    }
+
+    #[test]
+    fn empty_crate_and_empty_functions_error() {
+        assert!(
+            flatten("[adapter.File]\ncrate = \"\"\nfunctions = [\"open\"]\n").is_err(),
+            "empty crate must error"
+        );
+        assert!(
+            flatten("[adapter.File]\ncrate = \"file_native\"\nfunctions = []\n").is_err(),
+            "empty functions must error"
+        );
+    }
+}

docs/RSScript_Package_Manager_Design_v0.6.md

@@ -1877,6 +1877,31 @@ A native wrapper package may provide:
 "Json.JsonError" = "rss_json_native::JsonError"
 ```
 
+A whole boundary that binds many functions of one namespace to a single Rust
+wrapper crate can be declared compactly with an `[adapter.<Namespace>]` section
+instead of one `[bindings]` line per function:
+
+```toml
+# native/bindings.rssbind.toml
+
+[adapter.Json]
+crate = "rss_json_native"
+functions = ["parse", "field_string"]
+
+# Per-method overrides when the Rust name differs from the RSScript method:
+[adapter.Json.rename]
+parse = "json_parse"
+field_string = "json_field_string"
+```
+
+This expands at load time to exactly the `[bindings]` entries above
+(`Json.parse -> rss_json_native::json_parse`, …), so lowering, the VM shim, and
+all binding checks see the identical flat map — there is no separate adapter code
+path. Every bound method is still listed by name, keeping the boundary
+review-visible; only the repeated `Namespace.` prefix and `crate::` path are
+factored out. A symbol defined by both an adapter and an explicit `[bindings]`
+entry (or by two adapters) is rejected as a duplicate.
+
 Package checks must reject:
 
 ```text

docs/RSScript_v0.7_Spec.md

@@ -5416,10 +5416,12 @@ M. Module visibility and re-export hardening
 
 N. Native boundary and ABI adapter contracts
    - RSScript already declares native functions in .rssi with explicit unsafe and
-     native markers.
-   - future work: structured native adapter protocol (Rust adapter crate per
-     native dependency), tooling checks that bindings exist and match declared
-     contracts, dependency updates as review events with semantic diff.
+     native markers, groups them compactly with `native module`, and binds a whole
+     boundary in one `[adapter.<Namespace>]` manifest section (package-manager
+     §9.5) that expands to per-function bindings without a separate code path.
+   - future work: deeper structured native adapter protocol (Rust adapter crate
+     per native dependency), broader tooling checks that bindings exist and match
+     declared contracts, dependency updates as review events with semantic diff.
    - not adopted: general FFI, C header parsing, automatic binding generation
      without audit, or direct pointer manipulation in RSScript source.
 ```

docs/spec-todo.md

@@ -44,11 +44,22 @@ actual driver (see "Basis" at the bottom).
   come up; (b) a persistent **LSP-protocol daemon** (stdio) for editors — `rss ide`
   is request/response, not a long-running server. Track as a follow-up.
 
-- [ ] **FFI / native-ABI adapter contracts** (§3.2 general FFI, §20.1-N) —
-  _effort: medium–large, open-ended._
-  `native fn` declares external boundaries today; the gap is binding *whole*
-  runtime/autogen/device boundaries compactly without large wrapper files, plus
-  ABI-adapter conformance facts. Needs a concrete target boundary to scope "done."
+- [x] **FFI / native-ABI adapter contracts** (§3.2 general FFI, §20.1-N) —
+  _compact whole-boundary binding done; deeper adapter protocol remains._
+  The FFI surface was already mature (`native fn`, `native module` grouping,
+  transitive binding inheritance, unbound-call error at lowering, `rss native
+  audit`, review capability classification). Closed the named gap — "binding whole
+  boundaries compactly without large wrapper files" — with an
+  `[adapter.<Namespace>]` section in `native/bindings.rssbind.toml` (package-mgr
+  §9.5): one `crate` + a `functions` list (plus optional `rename`) binds a whole
+  namespace, expanding at load time into the same flat `symbol -> target` map every
+  consumer already uses (lowering, VM shim, conformance checks) — **zero parity
+  risk, single expansion point** (`flatten_native_bindings`). Duplicates across an
+  adapter and explicit `[bindings]` are rejected. Unit-tested for expansion,
+  rename, composition, and equivalence to the explicit form.
+  _Remaining (deferred, §20.1-N):_ deeper structured adapter protocol (Rust adapter
+  crate per dep), broader binding-conformance facts, dependency updates as semantic
+  review events. General FFI / C-header parsing / auto-binding stay non-goals.
 
 ## P2 — real features, not blocking today