docs(objects): explain exports and storage arithmetic regressions

crates/objects/src/lib.rs

@@ -1,6 +1,6 @@
-//! Core Endor objects, values, validated executable data and object storage.
-//! This crate has no VM evaluator or external dependencies. Handles, reference
-//! accounting and mutable payload replacement remain encapsulated here.
+//! Endor 对象、数值、已验证代码和存储的公共 API；compiler/core 和宿主都从这里导入。
+//! 不包含 VM 指令求值器；数值精确运算使用 num_* 依赖，句柄/计数/载荷修改仍封装在本 crate。
+//! 下方示例由文档测试调用：创建拥有根、读写属性，最后 release，不把复制句柄误当新增根。
 //!
 //! ```
 //! use objects::{ObjectStore, Value};
@@ -13,41 +13,64 @@
 //! # Ok::<(), objects::VmError>(())
 //! ```
 
+// 内部内置载荷：字符串、字典、函数、闭包槽和异常。
 mod builtins;
+// 内部变更通知结构，消费者据此失效缓存。
 mod changes;
+// 代码布局和构造校验，不执行代码。
 mod code;
+// 各层共享错误，避免对象层依赖 VM。
 mod error;
+// 私有堆：代际身份、根/边计数、只读追踪和回收。
 mod heap;
+// 指令协议及字节编解码，供编译器和执行器共用。
 mod instruction;
+// 宿主回调契约、上下文和结果根移交。
 mod native;
+// 无损数值表示和受预算约束的精确运算。
 mod number;
+// 直接值、载荷协议及公共对象实体。
 mod object;
+// 受控对象操作门面，宿主可独立于 VM 使用。
 mod store;
+// 字典/Cell/函数等内置载荷的 Store 扩展。
 mod store_builtins;
+// 名义类型、能力、字段注解及子模块中的契约/效果分析。
 mod types;
 
+// 向宿主公开内置载荷，分配和修改仍经 Store。
 pub use builtins::{
     EndorBaseExceptionObject, EndorCellObject, EndorDictObject, EndorFunctionObject,
     EndorStringObject, EndorTracebackEntry,
 };
+// 向缓存消费者公开借用变更通知，不提供对象拥有根。
 pub use changes::{ChangeBatch, ChangeKey, ObjectChange};
+// 编译器构造与 VM 共享执行数据需要的代码 API。
 pub use code::{CodeLayout, EndorCode, EndorCodeObject, SourceSignature};
+// 调用者结构化匹配的统一错误。
 pub use error::VmError;
+// 只公开句柄和读取观察结果，不导出可变 Heap。
 pub use heap::{ObjectRef, ReadAccess, ReadDependency, ReadSet, TrackedReads, WeakObjectRef};
+// 编译器/宿主组装指令，执行器读取解码结果。
 pub use instruction::{DecodedInstruction, Instruction, Opcode};
+// 宿主实现原生函数并声明参数、返回值和效果。
 pub use native::{
     CallArity, CallEffect, CallSignature, CallType, ContextNativeFunction, NativeCallable,
     NativeContext, NativeResult,
 };
+// 编译器字面量、VM 算术和宿主显式转换共用数值 API。
 pub use number::{
     ArithmeticOp, EndorDecimal, EndorInteger, EndorNumber, EndorNumberObject, EndorRational,
     EndorReal,
 };
+// 宿主实现载荷及等待协议，保留旧原生函数别名兼容。
 pub use object::{
     AwaitPoll, CompareOp, EndorNativeCall, EndorNativeFunctionObject, EndorObject, NativeCall,
     NativeFunction, ObjectHeader, ObjectPayload, Record, Value,
 };
+// 独立存储的主要入口，VM 也持有同一门面。
 pub use store::ObjectStore;
+// 宿主注册类型/能力，执行器检查构造和调用契约。
 pub use types::{
     AnnotationType, ClassField, EndorTraitObject, EndorTypeObject, MethodRequirement, RootTypes,
     TypeConstructor, TypedMethodRequirement,