Struct ResourceLedger 

pub struct ResourceLedger { /* private fields */ }

层级资源账本

设计

• 单所有者：整个账本树由一个 Supervisor 独占拥有
• 无子账本用 Arc/Rc，所有子账本为 owned 存储
• 父账本只通过层级路径索引子账本，不保留反向引用
• 所有操作为 &mut self，Rust 类型系统自然保证线程安全

Implementations

impl ResourceLedger

pub fn new( name: impl Into<String>, ledger_type: LedgerType, total: LedgerQuota, ) -> ResourceLedger

创建新的资源账本（Root 级）

pub fn root(total: LedgerQuota) -> ResourceLedger

创建根账本

pub fn name(&self) -> &str

获取账本名称

pub fn ledger_type(&self) -> LedgerType

获取账本类型

pub fn depth(&self) -> u8

获取层级深度

pub fn total(&self) -> &LedgerQuota

获取总配额

pub fn used(&self) -> &LedgerQuota

获取已使用配额

pub fn allocated_to_children(&self) -> &LedgerQuota

获取已分配给子账本的配额

pub fn child_count(&self) -> usize

获取子账本数量

pub fn child_names(&self) -> impl Iterator<Item = &str>

迭代子账本名称

pub fn get_child(&self, name: &str) -> Option<&ResourceLedger>

查找子账本（不可变）

pub fn get_child_mut(&mut self, name: &str) -> Option<&mut ResourceLedger>

查找子账本（可变）

pub fn create_child( &mut self, name: impl Into<String>, ledger_type: LedgerType, quota: LedgerQuota, ) -> Result<&mut ResourceLedger, CoreError>

在当前账本下创建子账本

父账本校验（fail-closed，逐项资源）： allocated_to_children + child_quota <= total - used

即「已承诺给现有子账本的配额 + 新子账本配额」不得超过父账本 扣除自身已用后的剩余配额，防止多子账本配额之和超卖父账本。

失败

• 配额不足（含兄弟账本已占用部分）→ CoreError::QuotaExceeded
• 子账本名称已存在 → CoreError::ResourceAlreadyExists
• 子账本全零配额 → CoreError::InvalidConfig（静默失败防护）

pub fn remove_child(&mut self, name: &str) -> Result<(), CoreError>

注销子账本（回收其配额）

子账本的 total 配额会从父账本的 allocated_to_children 中扣除。 同时回滚子树曾向父账本 roll-up 的使用量（used）： 子树被移除后其占用的资源视为全部释放，父账本不再为其记账。 回滚采用饱和语义——仅回收父账本实际记账的部分 （子树未经 allocate_in_child roll-up 的使用本就不在父账本账上）。

pub fn allocate( &mut self, resource: ResourceType, amount: u64, ) -> Result<(), CoreError>

在当前账本上分配资源（checked arithmetic）

超卖防护

本账本自身的直接用量（used_direct）+ 已承诺给子账本的配额不得超过 total。 否则父账本可直接分配耗尽 total，与子账本承诺配额叠加造成 “子账本配额 + 父自身用量 > total” 的分层配额超卖。

双重计数修复（CORE-013）

传统实现用 used（子树汇总）参与分配校验，会把子账本实际 roll-up 用量 与 allocated_to_children 配额重复计算，导致子账本用量 < 其配额时父账本 合法分配被误拒。修复后校验仅依赖 used_direct（本账本自身直接用量）， 与子账本已承诺配额做加法，不再叠加子账本实际用量。

pub fn release( &mut self, resource: ResourceType, amount: u64, ) -> Result<(), CoreError>

在当前账本上释放资源（直接释放，与 allocate 互逆）

双轨回滚：used_direct（本账本直接用量）与 used（子树汇总）同时扣减。 祖先 roll-up 回滚请使用 release_rollup，勿在本方法误用。

pub fn allocate_in_child( &mut self, child_path: &[&str], resource: ResourceType, amount: u64, ) -> Result<(), CoreError>

在指定子账本（按名称路径逐层下钻）上分配资源，并沿路径向所有祖先 roll-up

分层配额语义：子孙的实际使用同时消耗路径上每一层祖先的配额， 因此祖先账本的 used 始终反映其整棵子树的使用量。

原子性

路径上任一层配额不足或路径不存在时，已完成的祖先 roll-up 会逐层回滚， 调用前后账本树保持一致（fail-closed，不产生部分提交）。

Arguments

• child_path - 子账本名称路径（空路径等价于 self.allocate）
• resource - 资源类型
• amount - 分配数量

失败

• 路径不存在 → CoreError::ResourceNotFound
• 任一层配额不足 → CoreError::QuotaExceeded

pub fn release_in_child( &mut self, child_path: &[&str], resource: ResourceType, amount: u64, ) -> Result<(), CoreError>

在指定子账本（按名称路径逐层下钻）上释放资源，并沿路径回滚所有祖先的 roll-up

与 ResourceLedger::allocate_in_child 互逆：释放时逐层扣减路径上 每个账本的 used，保证祖先账本记账与子树实际使用一致。

原子性

路径不存在或任一层 used 不足时，已回滚的祖先层会逐层恢复， 调用前后账本树保持一致（fail-closed，不产生部分提交）。

失败

• 路径不存在 → CoreError::ResourceNotFound
• 任一层 used 不足（释放量超过已分配量）→ CoreError::ArithmeticOverflow

pub fn can_allocate(&self, resource: ResourceType, amount: u64) -> bool

检查是否可以分配指定资源

与 allocate 的校验一致：used_direct + amount + allocated_to_children <= total。 使用 checked_add 判断，加法溢出（不可容纳于 u64）时返回 false（fail-closed，CORE-012）。

pub fn remaining(&self) -> LedgerQuota

计算剩余配额

pub fn max_depth(&self) -> u8

递归深度（用于调试）

pub fn node_count(&self) -> u64

账本树节点总数（用于完整性检查）

Trait Implementations

impl Debug for ResourceLedger

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.