value

裁剪与依赖

只需要标量、字符串或 native 句柄时不启用 VALUE_CONTAINER。只需要基础增删改查时不启用 VALUE_COLLECTION；数组批量操作、映射合并和 Set 代数可以独立裁掉。

核心契约

对象终结职责由最后一次 backing 原子释放唯一取得，而非各外壳释放前的引用数快照。 带终结器的身份对象被公开迭代器引用时，迭代器同时拥有 backing 和真实来源外壳； End 先清空游标状态、释放 backing 槽，再释放外壳槽，保证最后一次终结获得真实 receiver。普通无终结器 COW 容器仍只拥有 backing，不改变源外壳的弱引用寿命。 拥有图按这两个实际槽分别计边，内部检查用的临时视图不得冒充拥有外壳。

xrtValueObjectFinalizerBindOwned(object, finalize, context, trace, release) 在唯一外壳和 backing 上原子接管上下文，不分配；失败不更改对象、不消费上下文、不调用任何回调。 非空上下文要求显式 Trace。Finalize 先借用对象和字段，全部 backing 字段释放后才 调用 Release 一次。Finalize 内可枚举字段；其新建游标若继续持有 backing，字段及 上下文释放也随之延后，但不会重新运行 Finalize。运行中的终结拒绝图检查。 Release 若释放最后一份代码租约，Release 本身须常驻；XRT 不会自动保活任意回调代码。 旧 FinalizerBind 的回调仍自行管理其上下文，不转成新接口的拥有式接管合同。

• xvalue 是不透明结构，调用方不得依赖内部布局。
• NULL 表示失败或缺失，语言 null 使用 xrtValueNull() 单例表示。
• null 和 bool 是不可变单例；其他值使用原子外壳引用计数。
• 字符串与字节默认复制；StringTake 和 BytesTake 接管 XRT 分配的内存。
• Take 的来源指针槽必须独立存在，不能位于准备接管的字符串、字节或句柄内存中。
• 裸指针不拥有目标；句柄必须提供释放器，策略描述必须比值活得更久。
• 句柄 Hash 与 Equal 必须同时提供或同时省略；两者必须满足相等值哈希一致。
• 句柄克隆器失败时必须设置错误，并且不得在输出中遗留资源；未提供克隆器的句柄深拷贝报告 XERR_UNSUPPORTED。
• Getter 和 Hash 失败时不改输出；输出区间不得覆盖 Value 外壳或其拥有的字符串、字节、句柄首地址。
• 句柄 Hash、Equal、Clone 和最终释放回调不得读取、保留或再次释放正在参与回调的 Value；这些重入以 XERR_STATE 拒绝。
• 标量不可变。Retain 共享同一身份，Clone 对标量等价于 Retain。
• 非静态值可在发布前用 xrtValueTypeIdBind 一次性绑定调用者定义的非零语义类型身份；重复绑定同一值成功，冲突绑定报告 XERR_STATE。该身份随浅克隆和深克隆传播，但不改变 XRT 的类别、相等、哈希或序列化语义。
• 精确 Getter 不做文本解析或隐式类型转换，类型错误报告 XERR_TYPE。
• xrtValueHash 只接受可哈希标量，并与数值相等规则保持一致；Pointer 和 Handle 的哈希仅在当前进程内有效，不可持久化或跨进程比较。
• xrtValueScalarEqual 比较标量内容；字符代码、有符号整数、无符号整数与可无损转换的浮点数按精确数值等价，所有 NaN 互相等价。
• Value Set 同样接受 XVALUE_CHAR 与完整 XVALUE_UINT；字符 'A'、整数 65、

无符号整数 65 和浮点数 65.0 共用规范哈希，去重时保留首次插入的值类型。 字符 NUL/补充平面码点合法；浅克隆后的增删不会更改原集合。

xrtValueTruthy 使用稳定的动态值真值口径：null、false、数值零、空字符串、空字节和空容器为 false；其他值为 true。Time、Pointer 和 Handle 表示已经存在的值对象，因此即使其内部数值或地址为零也为 true。

字符与拥有图补充合同

以下是现有原生 Value API 的合同，不表示语言标准库公开拥有图或回调接口。

类型

xvaluetype 是稳定的动态值类别，不等同于可扩展的 xrttype 运行时类型描述：

标量

字符串视图允许内嵌零，并额外保证 Data[Size] 是零。二进制视图只承诺长度内字节有效。

StringTake 会把缓冲调整到 size + 1 并写入末尾零，失败时来源指针和内容不变。 BytesTake 不增加隐藏终止字节。两者只接受由 XRT 分配器取得的内存；成功后来源 指针被清空，Value 在最后释放时销毁该内存。

xrtValueTypeId 对未绑定值和空指针返回零。xrtValueTypeIdBind 只接受非静态值与 非零身份；调用方必须在把值外壳发布给其他线程之前完成首次绑定。类型身份属于宿主 语义元数据，不会被 XRT 当作结构内容；COW 外壳克隆和 Value Graph 深克隆会保留它。 xrtValueTypeIdRebind 仅供已经完成语义验证的唯一拥有外壳替换身份；冲突的共享外壳 以 XERR_STATE 拒绝，调用方需要先创建独立 COW 外壳，不能重新解释其他持有者的值。

Native Handle

Drop 必须提供，空句柄也会按同一策略进入 Drop。Clone 只供 Value Graph 深克隆 使用；普通 xrtValueClone 只增加不可变句柄 Value 的外壳引用。Hash 和 Equal 可以同时省略，此时句柄不能加入 Value Set，也不能与另一个句柄执行标量或结构 内容比较。直接调用 Hash/Equal 时，正在参与策略回调的 Handle Value 都进入忙状态。

策略结构是不可变静态描述；user_data 与策略生命周期都必须覆盖关联的全部 Value。 只读句柄 Value 可跨线程发布，因此 Hash、Equal 和 Clone 回调若可能并发执行，回调 自身必须线程安全。完整用法见 examples/value/handle/main.c。

快照迭代

xvaluekeytype 说明每次迭代返回的键：

迭代器持有 backing 快照。xrtValueIterBegin 按稳定正序推进；xrtValueIterRBegin 按完全相反的稳定顺序推进。迭代开始后修改原值会触发 COW，旧迭代顺序和借用键仍然有效。Object 字符串键借用快照 backing，迭代结束后失效。键输出不得覆盖迭代器，Begin 输出不得覆盖 Value 外壳；别名错误不会推进快照。Begin 和 RBegin 只能用于未活动或已经 End 的迭代器。该公开层供 JSON、可选数据格式、模板和动态宿主使用，不需要访问任何私有容器结构。

xrtValueIterNext 是不隔离当前错误的最短快速路径，返回空值时调用方需按自身上下文判断结束。需要严格区分结果时使用 xrtValueIterAdvance：XVALUE_ITER_ITEM 表示写出一个借用元素，XVALUE_ITER_END 表示正常结束，XVALUE_ITER_ERROR 表示失败且当前错误已更新。成功项和正常结束均保留调用前已有错误；空指针或未活动迭代器属于错误。

Create/RCreate 提供相同语义的拥有式入口，适合 FFI、语言运行时和不保存公开结构布局的消费者。成功后必须用 xrtValueIterDestroy 结束并释放；Destroy(NULL) 是空操作。栈上固定存储仍优先使用 Begin/End，不会产生一次迭代器分配。

批量操作与集合代数

Array Extend、IntMap/Object Merge 和 Set Merge 都是失败原子操作：全部准备完成后才一次提交，OOM、冲突或环检测失败不会暴露部分结果；来源与目标可以是同一个值。映射合并必须显式选择策略：

• XVALUE_MERGE_KEEP：保留目标已有值，只加入缺失键。
• XVALUE_MERGE_REPLACE：来源覆盖已有值，但 Object 中已有键的位置不变。
• XVALUE_MERGE_ERROR：任一键冲突即报告 XERR_EXISTS，目标保持不变。

Object 的来源新键按来源顺序追加。Set 运算直接复用通用 Set 已压实的失败原子实现：并集保持左集合顺序并追加右侧独有元素；交集和差集保持左集合顺序；对称差集先放左侧独有元素，再放右侧独有元素。IsSubset 和 IsSuperset 支持普通或严格关系判断；IsDisjoint 判断是否没有共同元素；SetEqual 在不启用值图模块时也能直接比较两个标量集合。

空来源批量操作、映射共享同一 backing 且没有实际替换、Set 子集合并和自身 Keep/Replace 合并都是不分配、不分离 backing 的成功操作。空目标接收非空 Array、IntMap、Object 或 Set 时直接共享来源 backing，再由 COW 保证后续修改隔离。Union/Intersection 等同一集合或空集合恒等式也走 O(1) Clone 或直接创建空结果，不复制元素。

Value Set 的 Handle Hash/Equal 策略执行期间，左右 Value 外壳和底层 Set 同时进入忙状态；回调不能读取、Clone、释放或修改任一参与外壳。映射批量提交释放被替换旧值时，目标外壳同样保持忙状态。关系不成立是正常的 false；非法参数、类型、忙状态和分配失败分别报告结构化错误。

值图

深拷贝与源图完全隔离，并保留同一个 Value 外壳在结果图中的共享身份。不同 COW 外壳即使暂时共享 backing，仍表示两个独立的可修改位置，因此分别深克隆。null、 bool 和其他不可变标量只增加引用，复杂度为 O(1) 且不分配；拥有句柄只有提供 Clone 策略时才能深拷贝，避免把同一 native 资源伪装成两个独立所有者。Clone 失败却遗留非空输出时，库会防御性调用 Drop 回收，但回调仍违反契约。

结构相等比较内容而不是共享拓扑：一侧重复引用同一子值、另一侧放置两个内容相等 的独立子值，结果仍然相等。Object 不比较插入顺序，Array 比较顺序，Set 复用通用 Set 的等价元素关系；有符号整数、无符号整数与可无损转换的浮点数仍按精确数值相等。两个不同 Handle 必须 具有相同的策略与 user_data，并提供 Equal，否则报告 XERR_TYPE。

深克隆和结构相等各使用 32 项栈内身份表，小图不会为遍历状态分配；更大的图才按需 创建 Map。深克隆按源 Value 身份去重并保留 DAG，结构相等按已经验证相等的值对去重， 因此共享 DAG 不会按重复路径指数展开。结构相等不修改输入，但大图记忆表可能报告 XERR_MEMORY。从根开始最多访问 XRT_VALUE_DEPTH_MAX 层值；下一层报告 XERR_VALUE。

Handle Clone/Equal 和嵌套 Set 的 Hash/Equal 执行期间，当前 Handle、当前容器以及从 根到当前位置的活动祖先都进入忙状态。回调不得对这些 Value 执行读取、Clone、写入 或释放；同一外壳的跨线程调用仍由调用方同步。

可复制的 backing 生命周期能力

xrtValueObjectLifetimeBindOwned 把不可变上下文交给独立的共享生命周期节点， 不创建终结职责。绑定要求唯一外壳/backing；分配或校验失败不修改对象、不运行 回调、不消费上下文。成功后 backing 拥有该节点，节点拥有上下文及 Trace 描述 的真实强边；非空上下文必须提供 Trace，Release 始终必需。

浅 Clone 共享 backing；COW 分裂、DeepClone 的新 Object backing 各增加一次 生命周期节点引用。节点计数对应实际 backing 边，不把每个别名外壳误算成一个 上下文 owner。Release 仅在最后一个关联 backing 的字段及 finalizer context 全部释放后执行。代码租约适合放在这个节点，普通可复制对象不需要伪造空析构。 回调地址必须保持有效；Release 若可能释放最后代码引用，本身须为常驻函数。

xrtValueObjectConstructionPrepare 标记没有用户析构的普通构造事务；不会使 对象变为禁止 COW 分裂的引用身份。其 pending 状态随普通 backing 分裂/复制 传播，xrtValueObjectConstructionCommit 无分配地提交一次，也可提交通过 FinalizerPrepareOwned 准备的实际析构。原 FinalizerCommit 仍只接受真正的 owned finalizer；有用户终结职责的共享 backing 仍不能分裂或复制该职责。 DeepClone 继承生命周期能力但不复制终结职责，语言的 clone 策略须由上层定义。

空 Object 合并也从目标准备 backing，保留目标生命周期和构造状态，不借来源 backing 的快速路径替换它们。源数据字段仍按正常合并策略复制/共享。 这不是环收集器或原生并发图安全点；字段/构造状态修改及 ownership inspection 继续遵守既有同步要求，独立 backing 对同一生命周期节点的引用释放是原子的。

普通 Value 的物理接管适配器

xrtValueOwnershipAdapterV1 在调用方已持有 ownership freeze 时识别本 XRT 实例的普通 Value 外壳和四类容器 backing。它不调用未知 Count、Trace 或用户 策略，也不读取外部 descriptor 的尾部。自定义 handle、identity、finalizer、 lifetime、构造中对象，以及借用 blob 内存仍返回 NULL；包括上下文为 NULL 但代码来自外部的析构器。弱引用 Handle 是已知内建策略，不提供强拥有边。

适配器遵循 core 中 V1 的完整图保有与两阶段接管合同。普通强引用仍按原语义 保有；Claim 暂时使 WeakRefLock 返回 null，但 WeakRefExpired 仍反映实际强 生命周期。撤销 Restore 后可以重新提升。Clear 提交隔离并按物理 backing 断开元素强边，不经 COW EnsureUnique、不分配，所有目标须仍由事务实际保有。 有外部别名可达的 backing 不得 Clear。Drop 在 freeze 外归还事务引用。

该接口不自动寻找环，也不会把未建模的类析构/原生 callable 默认为空清理。 专项 ownership_adapter_tests 保留了普通终态析构，验证实际 COW 共享、重复边、 弱准入恢复、无分配清理及在回调之前拒绝自定义策略。

显式认证的类与原生 Handle 生命周期

xrtValueObjectOwnershipBindV1 仅接受尚未发布的 prepared 对象，绑定不可变的 xvalueobjectownershipv1 策略身份；收集器必须用同一授权策略调用 xrtValueObjectOwnershipAdapterV1。非空 Trace 并不意味着允许接管。 xrtValueObjectIdentityBindV1 把同一代码生命周期覆盖的 hash/equal 纳入认证； 普通 identity 绑定不会隐式获得这种权限。COW 副本继承实际 lifetime 拥有边。

非终态 Finalize 借用事务实际保有的 receiver，先物理撤销析构职责，再在 freeze 之外调用 FinalizeChecked；返回 false 即失败，即使没有错误对象。终态 RC 路径仍使用 void Finalize，两者必须表达同一语言职责，绝不会各调用一次。 撤销事务不恢复已执行职责；字段与 context/lifetime 在重验证和全部语义析构后 才机械释放。真正的事务 backing Hold 有独立记账，不伪造强计数，也不把它误当 COW 别名；第二个真实外壳/游标仍遵守原有共享与借用 receiver 限制。

xrtValueHandleOwnershipAdapterV1 只识别明确授权的 resident Ops/Trace 对， Clear 隔离实际 payload，Finish 在 freeze 之外运行一次机械 Drop。它不认证 payload 指向的 callable 或任意用户对象；每个传递子节点仍须独立准入。

普通末次释放同样区分物理修改和语义析构：已认证的类先在短 mutation 内归零并 隔离节点，然后在该 scope 外调用真实 receiver 的 Finalize；字段、context、 copyable lifetime 的拥有引用仍保持到各自实际释放边界。原生游标结束先脱离 自己的 backing/receiver 槽，再运行子释放。未知 legacy finalizer/lifetime 不 获得这一认证；外部调用方自己持有的 mutation 不会被库自动暂停。

xrtValueHandleOwnershipBindPhased 是独立的显式末次 Drop 合同，要求不可变的 Ops/Trace 和真实代码生命周期自行协调载荷变化与活动。它与 trace-only 的 xrtValueHandleOwnershipBind 都不自动授权图收集；后者保留保守的 Drop scope。 DeepClone 继承同一 Drop 合同。xruntime 已知 callable/Future Value 包装层使用 phased 绑定，任意 Object/Weak/native 包装策略不会因有 Trace 而自动升级。

普通 String/Bytes 有两种物理拥有形式：xrtValueString/Bytes 把副本内联保存在 同一个 Value 分配中，Take 入口则拥有单独分配。OWNED_DATA 只表示后者，不能 据此拒绝前者。普通适配器识别本实例的内联地址或明确的独立拥有标志，仍不接纳 未知外部借用字节。ownership_adapter_tests 保留原分母，新增 200 个容器图、 1200 个内联/空/Take 的物理字符串和字节值，以及 Clone 后的 2400 个实际拥有槽， 覆盖清理与恢复、精确重复边计数、无分配事务及内存平衡。不可变标量的 Clone 保有原节点，不创建第二个物理节点。