From bcf5fb4e967c3933a7a3f8a9646ccf9ee9f928c8 Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Sun, 15 Nov 2026 17:44:07 +0800 Subject: [PATCH] docs(objects): explain attribute forwarding regression scenarios --- crates/objects/tests/attribute_storage.rs | 79 ++++++++++++++++++++++- 1 file changed, 76 insertions(+), 3 deletions(-) diff --git a/crates/objects/tests/attribute_storage.rs b/crates/objects/tests/attribute_storage.rs index ea6289b..f8047b5 100644 --- a/crates/objects/tests/attribute_storage.rs +++ b/crates/objects/tests/attribute_storage.rs @@ -1,48 +1,73 @@ +//! Rust 测试框架调用的属性存储回归，不执行源码指令。 +//! Proxy 让字段存储与名义身份分开；ReflectiveType 触发类型查询对自身属性的重入。 +//! 断言覆盖托管边生命周期、失败不修改版本、能力方法不得被实例属性遮蔽。 + use objects::{ObjectPayload, ObjectRef, ObjectStore, TypeConstructor, Value, VmError}; #[derive(Debug)] +/// 一个拥有后端存储引用的门面，type_target 保持默认 None。 struct Proxy(ObjectRef); impl ObjectPayload for Proxy { + /// Store 下转型测试载荷，不进行语言类型判定。 fn as_any(&self) -> &dyn std::any::Any { self } + /// 测试错误/诊断使用的类别标签。 fn kind_name(&self) -> &'static str { "proxy" } + /// Heap 分配/替换时记录一条拥有边，确保被代理存储或自引用 Cell 存活。 fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) { visit(self.0); } + /// Store::attribute_path 追踪实际字段存储，不改变代理对象头部类型。 fn attribute_target(&self, _: &ObjectStore) -> Result, VmError> { Ok(Some(self.0)) } } #[test] +/// 验证代理改指新存储后，名义类型不变、旧值释放、读写删除转到新终点。 fn storage_retargeting_preserves_type_identity_and_releases_old_state() { + // 建立独立堆隔离场景，所有分配根在测试末尾明确归还。 let mut store = ObjectStore::new().unwrap(); + // 自举 Object/Type，各有一份外部根；其图内自环需最终 collect_cycles。 let roots = store.bootstrap_types().unwrap(); + // 给代理/反射实例附着真实名义类型，字段转发不应替换它。 let class = store .new_type("Proxy", roots.object, TypeConstructor::Record) .unwrap(); + // 普通 Record 作为无类型后端存储，只有代理持有时也须存活。 let storage = store.new_object().unwrap(); + // 旧属性值先由测试根持有，之后转由字段强边持有。 let old_value = store.new_object().unwrap(); + // 弱句柄不持有旧值，替换存储后可观测其真正释放。 let weak_value = store.downgrade(old_value).unwrap(); store .set_attr(storage, "value", Value::Object(old_value)) .unwrap(); + // 归还外部根，留下 storage.value 一条强边。 store.release(old_value).unwrap(); + // Proxy 的 trace 持有后端，字段实际写入后端但类型留在 Proxy 头部。 let proxy = store.allocate(Proxy(storage)).unwrap(); store.attach_type(proxy, class).unwrap(); + // 归还后端外部根后仍由 Proxy 的载荷边维持存活。 store.release(storage).unwrap(); + // 确认路径同时包含门面和终点，不只返回头部类型对象。 assert_eq!(store.attribute_path(proxy).unwrap(), vec![proxy, storage]); + // 保留 type 属性查询代理自身名义类型，不跟随后端身份变化。 assert_eq!(store.get_attr(proxy, "type").unwrap(), Value::Object(class)); assert_eq!( store.get_attr(proxy, "value").unwrap(), Value::Object(old_value) ); + // 新后端先由根持有，替换成功后 Proxy 自己持有一条边。 let next = store.new_object().unwrap(); + // 受控替换重新登记边，旧后端及其唯一持有的属性值应被级联释放。 store.replace_payload(proxy, Proxy(next)).unwrap(); + // 归还新后端根，后续访问证明其仍由 Proxy 强边保留。 store.release(next).unwrap(); + // 旧值没有残余根，弱升级必须返回 None。 assert!(store.upgrade(weak_value).unwrap().is_none()); store .set_attr(proxy, "value", Value::Number(9_i64.into())) @@ -51,48 +76,67 @@ fn storage_retargeting_preserves_type_identity_and_releases_old_state() { store.get_attr(next, "value").unwrap(), Value::Number(9_i64.into()) ); + // 通过代理删除应作用于新后端，不只是门面自己的属性表。 store.del_attr(proxy, "value").unwrap(); assert!(store.get_attr(next, "value").is_err()); + // 逐项释放测试拥有根，不手动 release 内部边，避免重复归还。 for object in [proxy, class, roots.object, roots.type_type] { store.release(object).unwrap(); } + // 回收类型自举环及其他已无外部根的环，最终堆应为空。 store.collect_cycles(); assert_eq!(store.object_count(), 0); } #[test] +/// 验证属性转发环和异堆身份被拒绝，失败不产生新的变更版本。 fn cyclic_and_foreign_attribute_storage_fail_without_mutating_fields() { + // 建立独立堆隔离场景，所有分配根在测试末尾明确归还。 let mut store = ObjectStore::new().unwrap(); + // 普通 Record 作为无类型后端存储，只有代理持有时也须存活。 let storage = store.new_object().unwrap(); + // Proxy 的 trace 持有后端，字段实际写入后端但类型留在 Proxy 头部。 let proxy = store.allocate(Proxy(storage)).unwrap(); + // 注入合法托管自环但非法属性转发环；属性路径必须检测，不无限循环。 store.replace_payload(proxy, Proxy(proxy)).unwrap(); + // 记录失败读写前版本，路径检查失败不得修改对象。 let version = store.change_version(proxy).unwrap(); assert!(store.get_attr(proxy, "field").is_err()); assert!(store.set_attr(proxy, "field", Value::Nil).is_err()); assert_eq!(store.change_version(proxy).unwrap(), version); + // 异堆即使槽号相同也必须报 ForeignHandle，不当成普通缺字段。 let other = ObjectStore::new().unwrap(); assert_eq!(other.attribute_path(proxy), Err(VmError::ForeignHandle)); + // 归还后端外部根后仍由 Proxy 的载荷边维持存活。 store.release(storage).unwrap(); store.release(proxy).unwrap(); + // 外部根释放后只有 Proxy 自环残留，显式回收恰好一个对象。 assert_eq!(store.collect_cycles(), 1); } #[derive(Debug)] +/// 拥有一个 Cell，type_target 读 Cell 指回自己，测试递归属性查询。 struct ReflectiveType(ObjectRef); impl ObjectPayload for ReflectiveType { + /// Store 下转型测试载荷，不进行语言类型判定。 fn as_any(&self) -> &dyn std::any::Any { self } + /// 测试错误/诊断使用的类别标签。 fn kind_name(&self) -> &'static str { "reflective-type" } + /// 反射对象自行存字段，允许 selector 查询从公共属性表读取。 fn allows_attributes(&self) -> bool { true } + /// Heap 分配/替换时记录一条拥有边，确保被代理存储或自引用 Cell 存活。 fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) { visit(self.0); } + /// Store::type_of 调用时通过 Cell 找自己并读 selector，专门制造属性检查重入。 fn type_target(&self, store: &ObjectStore) -> Result, VmError> { + // Cell 初始 Nil 时不重入，安装自引用后读自身 selector 触发保护守卫路径。 if let Value::Object(receiver) = store.cell_get(self.0)? { store.get_attr(receiver, "selector")?; } @@ -101,8 +145,10 @@ impl ObjectPayload for ReflectiveType { } #[derive(Debug)] +/// 无捕获且不修改存储的能力方法测试实现；完整签名供声明/调用门禁读取。 struct TypedCheck; impl objects::NativeCallable for TypedCheck { + /// 为 check 声明显式 self、Number 返回和 ReadOnly 效果，供能力契约核对。 fn signature(&self) -> Option { Some(objects::CallSignature::exact( vec![objects::AnnotationType::Any], @@ -110,6 +156,7 @@ impl objects::NativeCallable for TypedCheck { objects::CallEffect::ReadOnly, )) } + /// 原生分派返回直接整数，无对象结果需要额外保留；本文件主要验证契约门禁。 fn invoke( &self, _: &mut objects::NativeContext<'_>, @@ -120,12 +167,17 @@ impl objects::NativeCallable for TypedCheck { } #[test] +/// 验证能力声明/调用各入口均拒绝同名字段遮蔽，且递归守卫失败后正确清理。 fn typed_method_storage_cannot_diverge_from_class_dispatch() { + // 建立独立堆隔离场景，所有分配根在测试末尾明确归还。 let mut store = ObjectStore::new().unwrap(); + // 自举 Object/Type，各有一份外部根；其图内自环需最终 collect_cycles。 let roots = store.bootstrap_types().unwrap(); + // 给代理/反射实例附着真实名义类型，字段转发不应替换它。 let class = store .new_type("Checked", roots.object, TypeConstructor::Record) .unwrap(); + // 上下文原生函数发布完整签名；类方法表还会单独拥有它的强边。 let function = store .allocate(objects::ContextNativeFunction::new( "check", @@ -134,6 +186,7 @@ fn typed_method_storage_cannot_diverge_from_class_dispatch() { )) .unwrap(); store.define_method(class, "check", function).unwrap(); + // 能力要求与原生方法完整契约一致，包含显式 self 参数。 let capability = store .new_typed_trait( "Checked", @@ -147,19 +200,28 @@ fn typed_method_storage_cannot_diverge_from_class_dispatch() { }], ) .unwrap(); + // 普通 Record 作为无类型后端存储，只有代理持有时也须存活。 let storage = store.new_object().unwrap(); + // Proxy 的 trace 持有后端，字段实际写入后端但类型留在 Proxy 头部。 let proxy = store.allocate(Proxy(storage)).unwrap(); store.attach_type(proxy, class).unwrap(); + // 直接写无类型后端可以造出对代理而言不符合能力的实例，后续门禁应拒绝。 store.set_attr(storage, "check", Value::Nil).unwrap(); + // 能力声明失败应保持定义版本和声明集合不变。 let version = store.change_version(class).unwrap(); assert!(matches!( + // 存储冲突消除后能力声明才允许提交。 store.implement_trait(class, capability), Err(VmError::TraitViolation { .. }) )); assert_eq!(store.change_version(class).unwrap(), version); + // 失败声明不能留下一半能力关系。 assert!(!store.implements_trait(class, capability).unwrap()); + // 删除遮蔽字段恢复合法存储，后续能力声明/查询应重新成功。 store.del_attr(storage, "check").unwrap(); + // 存储冲突消除后能力声明才允许提交。 store.implement_trait(class, capability).unwrap(); + // 代理受控写入在真正触及后端前失败，后端版本不得增加。 let version = store.change_version(storage).unwrap(); assert!(matches!( store.set_attr(proxy, "check", Value::Nil), @@ -167,8 +229,8 @@ fn typed_method_storage_cannot_diverge_from_class_dispatch() { )); assert_eq!(store.change_version(storage).unwrap(), version); assert!(store.supports(proxy, capability).unwrap()); - // A trusted host can access the untyped backing record directly. Every - // language/host dispatch gate must detect the resulting invalid instance. + // 可信宿主能直接写无类型后端；supports/get_attr/bind_attr/调用检查/直接存储检查都必须发现失效实例。 + // 直接写无类型后端可以造出对代理而言不符合能力的实例，后续门禁应拒绝。 store.set_attr(storage, "check", Value::Nil).unwrap(); assert!(matches!( store.supports(proxy, capability), @@ -190,13 +252,17 @@ fn typed_method_storage_cannot_diverge_from_class_dispatch() { store.check_typed_instance_storage(proxy), Err(VmError::TraitViolation { .. }) )); + // 另建已有冲突字段的记录，验证 attach_type 也守住能力存储约束。 let candidate = store.new_object().unwrap(); + // 先放同名字段再附着类型，不能绕过“创建后写入”的校验。 store.set_attr(candidate, "check", Value::Nil).unwrap(); assert!(matches!( store.attach_type(candidate, class), Err(VmError::TraitViolation { .. }) )); + // 附着失败不能留下部分头部类型关系。 assert_eq!(store.type_of(candidate).unwrap(), None); + // 删除遮蔽字段恢复合法存储，后续能力声明/查询应重新成功。 store.del_attr(storage, "check").unwrap(); assert!(store.supports(proxy, capability).unwrap()); assert_eq!( @@ -206,7 +272,9 @@ fn typed_method_storage_cannot_diverge_from_class_dispatch() { store .check_method_contract_call(function, proxy, false) .unwrap(); + // 用托管 Cell 保存反射对象，初始 Nil 避免初始化时就递归查询未设字段。 let self_cell = store.new_cell(Some(Value::Nil)).unwrap(); + // 载荷持有 Cell，Cell 稍后反向持有对象，形成可回收的托管环。 let reflective = store.allocate(ReflectiveType(self_cell)).unwrap(); store .set_attr(reflective, "selector", Value::Bool(true)) @@ -214,6 +282,7 @@ fn typed_method_storage_cannot_diverge_from_class_dispatch() { store .cell_set(self_cell, Value::Object(reflective)) .unwrap(); + // 附着能力类型期间查询 selector 会重入检查，守卫应避免无限递归。 store.attach_type(reflective, class).unwrap(); assert_eq!( store.get_attr(reflective, "selector").unwrap(), @@ -224,14 +293,17 @@ fn typed_method_storage_cannot_diverge_from_class_dispatch() { store.set_attr(reflective, "check", Value::Nil), Err(VmError::TraitViolation { .. }) )); - // A failed guarded check must not suppress the next one. + // 首次失败必须通过 RAII 移除标记；第二次同样的非法写入仍应失败，不能被误当成递归跳过。 assert!(matches!( store.set_attr(reflective, "check", Value::Nil), Err(VmError::TraitViolation { .. }) )); + // 归还自引用图外部根；环内边仍在，统一由最终回收处理。 store.release(reflective).unwrap(); + // Cell 的外部根也归还，不能仅释放反射门面而留下测试根。 store.release(self_cell).unwrap(); + // 逐项释放测试拥有根，不手动 release 内部边，避免重复归还。 for object in [ candidate, proxy, @@ -244,6 +316,7 @@ fn typed_method_storage_cannot_diverge_from_class_dispatch() { ] { store.release(object).unwrap(); } + // 回收类型自举环及其他已无外部根的环，最终堆应为空。 store.collect_cycles(); assert_eq!(store.object_count(), 0); }