From 9c8ea52396ba17283729e4462c11e70a8355cf2e Mon Sep 17 00:00:00 2001
From: buke <wangbuke@gmail.com>
Date: Fri, 22 May 2026 15:15:19 +0800
Subject: [PATCH 1/2] docs(bytecode): document trusted input boundary

- warn that QuickJS bytecode must only be loaded from trusted sources
- annotate EvalBytecode and LoadModuleBytecode with the same trust requirement
- mirror the guidance in both the English and Chinese README bytecode sections
---
 README.md       | 2 ++
 README_zh-cn.md | 2 ++
 context.go      | 4 ++++
 3 files changed, 8 insertions(+)

diff --git a/README.md b/README.md
index 4f91836..d4d2b25 100644
--- a/README.md
+++ b/README.md
@@ -1578,6 +1578,8 @@ func main() {
 
 ### Bytecode Compiler
 
+QuickJS bytecode should only be loaded from trusted input produced by this library or another trusted writer. It is not a safe interchange format for untrusted data, and loading hostile bytecode may lead to memory corruption in the underlying engine.
+
 ```go
 package main
 
diff --git a/README_zh-cn.md b/README_zh-cn.md
index 8e672dc..296c332 100644
--- a/README_zh-cn.md
+++ b/README_zh-cn.md
@@ -1573,6 +1573,8 @@ func main() {
 
 ### 字节码编译器
 
+QuickJS 字节码只应从本库生成的可信输入，或其他可信写入方生成的输入中加载。它不是面向不可信数据的安全交换格式；加载恶意字节码可能导致底层引擎发生内存破坏。
+
 ```go
 package main
 
diff --git a/context.go b/context.go
index bb13adb..5570c4d 100644
--- a/context.go
+++ b/context.go
@@ -987,6 +987,8 @@ func (ctx *Context) CompileModule(filePath string, moduleName string, opts ...Ev
 }
 
 // LoadModuleByteCode returns a js value with given bytecode and module name.
+// Only load bytecode produced by a trusted source. QuickJS bytecode is not a
+// safe interchange format for untrusted data.
 func (ctx *Context) LoadModuleBytecode(buf []byte, opts ...EvalOption) *Value {
 	if !ctx.hasValidRef() {
 		return nil
@@ -1030,6 +1032,8 @@ func (ctx *Context) BootstrapBJSON() bool {
 }
 
 // EvalBytecode returns a js value with given bytecode.
+// Only load bytecode produced by a trusted source. QuickJS bytecode is not a
+// safe interchange format for untrusted data.
 // Need call Free() `quickjs.Value`'s returned by `Eval()` and `EvalFile()` and `EvalBytecode()`.
 func (ctx *Context) EvalBytecode(buf []byte) *Value {
 	if !ctx.hasValidRef() {

From cf21d5409ee9571502eb6fd5bffe90a2849c89f8 Mon Sep 17 00:00:00 2001
From: buke <wangbuke@gmail.com>
Date: Fri, 22 May 2026 15:23:39 +0800
Subject: [PATCH 2/2] docs(context): refine bytecode API warnings

- fix the LoadModuleBytecode docstring name and parameter wording
- make the memory corruption risk explicit for bytecode-loading APIs
- tighten the EvalBytecode ownership note to match the returned value
---
 context.go | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/context.go b/context.go
index 5570c4d..27058ef 100644
--- a/context.go
+++ b/context.go
@@ -986,9 +986,10 @@ func (ctx *Context) CompileModule(filePath string, moduleName string, opts ...Ev
 	return ctx.CompileFile(filePath, opts...)
 }
 
-// LoadModuleByteCode returns a js value with given bytecode and module name.
+// LoadModuleBytecode returns a js value from the given bytecode.
 // Only load bytecode produced by a trusted source. QuickJS bytecode is not a
-// safe interchange format for untrusted data.
+// safe interchange format for untrusted data, and loading hostile bytecode
+// may lead to memory corruption in the underlying engine.
 func (ctx *Context) LoadModuleBytecode(buf []byte, opts ...EvalOption) *Value {
 	if !ctx.hasValidRef() {
 		return nil
@@ -1031,10 +1032,11 @@ func (ctx *Context) BootstrapBJSON() bool {
 	return C.js_init_module_bjson(ctx.ref, moduleName) != nil
 }
 
-// EvalBytecode returns a js value with given bytecode.
+// EvalBytecode returns a js value from the given bytecode.
 // Only load bytecode produced by a trusted source. QuickJS bytecode is not a
-// safe interchange format for untrusted data.
-// Need call Free() `quickjs.Value`'s returned by `Eval()` and `EvalFile()` and `EvalBytecode()`.
+// safe interchange format for untrusted data, and loading hostile bytecode
+// may lead to memory corruption in the underlying engine.
+// The caller must call Free() on the Value returned by EvalBytecode().
 func (ctx *Context) EvalBytecode(buf []byte) *Value {
 	if !ctx.hasValidRef() {
 		return nil