docs(jit): codify supported acceleration baseline

Author: olwang

benchmarks/vm-jit/README.md

@@ -41,7 +41,9 @@ use. Microbenchmark-only wins are insufficient.
 Current evidence keeps baseline scalar loops, native call chains, and the shared
 Option/Result/Variant scalar-replacement path. Profile-guided closure PIC and
 branch-side-exit speculation are isolated behind the VM-only `jit-speculation`
-feature. Native recursion is isolated behind `jit-recursion-experimental`.
+feature. Native recursion is isolated behind `jit-recursion-experimental`, and
+loop-invariant helper memoization behind `jit-memoization-experimental`. The
+ordinary SDK `native-jit` feature compiles none of those research implementations.
 
 ## Adding a workload
 

crates/rsscript-sdk/tests/architecture.rs

@@ -1197,6 +1197,38 @@ fn cranelift_engine_uses_real_modules_instead_of_flattened_includes() {
     }
 }
 
+#[test]
+fn cranelift_engine_keeps_research_features_and_raw_abi_out_of_the_stable_surface() {
+    let root = workspace_root();
+    let manifest = read(&root.join("crates/rsscript-jit-cranelift/Cargo.toml"));
+    let library = read(&root.join("crates/rsscript-jit-cranelift/src/lib.rs"));
+    let vm_manifest = read(&root.join("crates/rsscript-vm/Cargo.toml"));
+
+    assert!(manifest.contains("publish = false"));
+    for feature in ["speculation = []", "recursion = []", "memoization = []"] {
+        assert!(
+            manifest.contains(feature),
+            "Cranelift manifest is missing isolated research feature `{feature}`"
+        );
+    }
+    assert!(!library.contains("pub use host_abi::*;"));
+    assert!(!library.contains("pub use ir::*;"));
+    assert!(!library.contains("pub use module::*;"));
+    assert!(library.contains("JitCallFrame"));
+    assert!(!library.contains("pub use host_abi::{\n    JitCallFrame"));
+
+    let native_jit = vm_manifest
+        .lines()
+        .find(|line| line.starts_with("native-jit ="))
+        .expect("VM must declare the stable native-jit feature");
+    assert!(!native_jit.contains("speculation"));
+    assert!(!native_jit.contains("recursion"));
+    assert!(!native_jit.contains("memoization"));
+    assert!(vm_manifest.contains("jit-speculation"));
+    assert!(vm_manifest.contains("jit-recursion-experimental"));
+    assert!(vm_manifest.contains("jit-memoization-experimental"));
+}
+
 fn rust_files_below(root: &Path) -> Vec<PathBuf> {
     fn visit(directory: &Path, files: &mut Vec<PathBuf>) {
         let mut entries = fs::read_dir(directory)

docs/spec/native-jit-contract.md

@@ -3,6 +3,14 @@
 The native JIT is an optional accelerator for trusted, in-process execution. It
 does not add an isolation boundary and never changes Provider authority.
 
+The supported `native-jit` feature is intentionally a bounded *feature surface*,
+not yet an accelerator for bounded executions. Whole-function native entry
+currently declines when step, cancellation, deadline, allocation, live-memory,
+intrinsic-call, or Provider-call limits are armed. The interpreter then executes
+the request with the original limits. This fail-closed behavior keeps ordinary
+bounded execution correct; hosts only receive native acceleration from the
+explicit trusted/unbounded execution mode until accounting parity is implemented.
+
 ## Stable invariants
 
 - The interpreter is the semantic oracle. Unsupported operations and guarded
@@ -25,6 +33,11 @@ does not add an isolation boundary and never changes Provider authority.
   deoptimization, and OSR eligibility are classified by the exhaustive
   `JitInstr::effects` API. Validators and tiering must consume those facts rather
   than maintain independent opcode lists.
+- Structural compilation work is bounded by `JitLimits` before Cranelift code
+  generation. Instruction, register, CFG-edge, operand, analysis-word, deopt,
+  memo-scope, callee, and recursive-group counts have deterministic limits.
+  `max_compile_millis` is a soft admission/telemetry limit, not a claim that an
+  in-process Cranelift invocation can be interrupted at a wall-clock deadline.
 
 ## Internal contracts
 
@@ -41,6 +54,21 @@ Profile-guided closure PIC and branch-side-exit speculation are excluded from th
 stable SDK path. They remain behind the VM-only `jit-speculation` research feature
 until a canonical compiler workload demonstrates a repeatable end-to-end benefit.
 
+Loop-invariant host-helper memoization is likewise excluded from the stable SDK
+path and compiled only by `jit-memoization-experimental`. Its CFG scope proof and
+runtime memo state must earn retention through the same canonical scorecard.
+
+The Cranelift engine crate is not independently published. Its public root exposes
+only the VM-facing engine, validated IR, typed options/outcomes, host-helper
+contract, and prepared-call boundary. Raw call-frame layout, ABI offsets, helper
+function aliases, codegen internals, and module implementation types remain
+crate-private.
+
+Native rewrites carry `NativeInstructionOrigin { bytecode_ip, resume_ip }` in one
+owned pipeline state. A pass may temporarily return a local new-to-previous map,
+but only the pipeline state composes it; source and deopt-resume identity may not
+travel in unrelated parallel vectors.
+
 ## Native recursion
 
 Tail recursion may be lowered to a loop. Non-tail self or group recursion uses the
@@ -62,3 +90,10 @@ deoptimization and rollback cases, 64/128/256 KiB host-stack entries, guard-page
 flat-buffer bounds tests, AddressSanitizer coverage for host wrappers, structured
 IR fuzzing, and the workload scorecard. ASan does not instrument generated machine
 code; guard pages and canary/boundary fixtures cover direct native memory accesses.
+
+The stable retention set is baseline scalar/flat-data execution, native leaf-call
+chains, transactional helpers, precise deopt, and the Option/Result/Variant scalar
+replacement paths that enter on the canonical scorecard. Speculation, non-tail
+native recursion, and helper memoization are research features. A local scorecard
+run is diagnostic only; timings become a compatibility or release signal only
+after a controlled-hardware baseline is checked in with machine/toolchain metadata.