Module budget_split 

Sibling-sum budget enforcement for delegated capability tokens.

CapabilityToken::validate_schema already enforces the per-token cap budget_share_bps <= 10_000. That check is necessary but not sufficient: it does not see siblings. A parent at 5_000 bps could mint two children at 5_000 bps each, and per-token validation would happily accept both, letting the children jointly claim 100% of the parent’s authority while the parent itself only owns 50%.

BudgetSplit and the BudgetRegistry trait close that gap. When a verifier admits a freshly delegated child, it asks the registry whether the parent has enough remaining headroom. If the running sum of admitted sibling shares plus the new child’s share would exceed the parent’s share, the registry rejects the child and verification fails closed.

The split type is intentionally pure: it owns no clock, no I/O, and no revocation state. Callers that need a hosted in-memory registry use InMemoryBudgetRegistry (gated behind the crate std feature). no_std consumers can implement the BudgetRegistry trait against their own storage.

Overflow safety

BudgetSplit::current_total_child_bps returns a u32 and the admit check uses u32 arithmetic so two u16::MAX siblings cannot overflow into a wraparound that silently passes the cap. The parent share itself is bounded by MAX_BUDGET_SHARE_BPS which the per-token validator enforces at load time.

Structs

BudgetSplit

A live record of how much of a parent’s budget has already been delegated to admitted children.

ChildAdmission

A single admitted child edge: the share it claimed plus a reference count of the active evaluations currently holding it.

InMemoryBudgetRegistry

Pure in-memory BudgetRegistry backed by a BTreeMap.

NoopBudgetRegistry

A no-op BudgetRegistry used by callers that have not yet wired the budget plumbing.

Enums

AdmitMode

Whether an admit acquires a releasable holder lease or only checks admissibility.

BudgetSplitError

Errors raised by BudgetSplit admission and release operations.

Constants

MAX_BUDGET_SHARE_BPS

Hard ceiling on any single token’s budget share in basis points.

Traits

BudgetRegistry

A registry of live BudgetSplits, keyed by parent capability id.