@suluk/keys - v0.1.0
    Preparing search index...

    Function pooledHeadroom

    @suluk/keys — the delegation-chain ALGEBRA for hierarchical API keys (C046, extracted from a real app).

    The app builds a ChainNode[] (a caller + its ancestors) and per-path SpendRow[] from its OWN store — the DB query is the seam (a Drizzle reference adapter is a follow-on, deferred per C046) — then calls these PURE functions for the money/abuse-correctness logic so it can never drift: • effectiveCaps — scope ∩, credit-cap/rate-share/expiry min up the chain (a child can't out-scope/out-spend a parent) • pooledHeadroom — a node's cap bounds its WHOLE subtree's total spend (the abuse-proof property) • expired/disabledAncestor — the read-time revocation/expiry cascade • clampChildGrant — clamp a minted child to the parent's effective grant plus the materialized-path utilities and the scope/metadata model.

    • The chain's POOLED credit headroom — the BINDING constraint a charge must clear: over every node that declares an own cap, the LEAST cap − subtreeSpend(node) (a node's subtree = itself ∪ descendants). Pooling is what makes a cap abuse-proof: a parent capped at 50 can't mint children to spend 50 each, because every child's spend lands in the parent's subtree. The app fetches spendRows (per-path spend over the topmost capped node's subtree — one grouped query); this sums per node in O(nodes × rows). Returns null when no node declares a cap (uncapped — only the balance gates).

      Parameters

      Returns Headroom | null