Struct SqliteBudgetStore 

pub struct SqliteBudgetStore { /* private fields */ }

Implementations

impl SqliteBudgetStore

pub fn cumulative_approval_operation_projection( &self, operation_id: &str, ) -> Result<Option<(BudgetCumulativeApprovalUsage, BudgetMutationRecord)>, BudgetStoreError>

Returns an operation’s latest cumulative usage and durable mutation event.

impl SqliteBudgetStore

pub fn reap_holds_by_map( &self, realized_by_hold: &HashMap<String, u64>, ) -> Result<ReapSummary, BudgetStoreError>

Reconcile or reverse every hold still open at startup. Holds present in realized_by_hold (arbitrated by the ADR-0013 durable receipt log) are reconciled to their realized spend; holds absent from it (never durably admitted) are reversed. This is fail-closed against double-spend: a naive blanket release is never used.

Called by the BudgetStore trait implementation of reap_orphaned_holds.

pub fn reap_expired_reserved_holds( &self, now_unix_secs: i64, ) -> Result<usize, BudgetStoreError>

Settle every reserved hold that is still open and whose reserved_until deadline is at or before now_unix_secs at its reserved worst-case, forfeiting the reserved amount to realized spend. In the two-phase reserve/reconcile flow the only evidence a spend occurred is the caller’s reconcile; an expired-and-unreconciled hold may correspond to a call that executed and spent, so releasing it (realized 0) would under-count real spend and fail open for a cumulative cap. The abandoning caller instead forfeits the worst-case (must reconcile before expiry to reclaim the difference). Fail-closed: only holds explicitly marked reserved (a non-NULL reserved_until) and past expiry are touched; a not-yet-expired reserved hold and any non-open hold are left alone. Idempotent (a settled hold is no longer open). Returns the number of holds settled.

pub fn mark_hold_reserved_until( &self, hold_id: &str, reserved_until_unix_secs: i64, currency: &str, payment_reference: Option<&str>, envelope: &ReservedHoldEnvelope, ) -> Result<(), BudgetStoreError>

Stamp an open hold with a TTL reaper deadline, the grant currency, and the rail transaction id of a prepaid MustPrepay reservation (None when the reserve carried no prepayment). Errors fail-closed when the hold is missing or is no longer open.

pub fn reserve_invocation_hold( &self, hold_id: &str, capability_id: &str, grant_index: usize, reserved_until_unix_secs: i64, envelope: &ReservedHoldEnvelope, ) -> Result<(), BudgetStoreError>

Adopt an already-debited invocation into a durable zero-exposure reserved hold, stamped with the TTL deadline and no currency. The invocation was already counted by try_increment, so this only records the open hold (never touching the invocation count); reversing it by hold id returns the invocation, while reconciling or reaping it keeps the invocation consumed. Fails closed when a hold already exists under the id.

pub fn budget_hold_snapshot( &self, hold_id: &str, ) -> Result<Option<BudgetHoldSnapshot>, BudgetStoreError>

Project a single hold by id, including its reserved-until deadline.

impl SqliteBudgetStore

pub fn max_mutation_event_seq(&self) -> Result<u64, BudgetStoreError>

Highest budget mutation event_seq, or 0 when empty. Mirrors the private max_budget_mutation_event_seq helper but is a public head read for the status path.

pub fn max_mutation_event_seq_for_authority( &self, authority_id: &str, ) -> Result<u64, BudgetStoreError>

Highest mutation event_seq written under one origin authority, or 0 when none. The cluster budget-write handler reads this immediately after a local (leader) write to build the write’s quorum-witness token: it is always >= the just-written event’s own seq (a concurrent same-origin write can only raise it), so the per-origin contiguous witness can only under-count witnesses, never over-count one (fail-closed).

pub fn mutation_event_seq_for_event_id( &self, event_id: &str, ) -> Result<Option<u64>, BudgetStoreError>

The exact event_seq of the mutation event written under event_id, or None if no such event exists (or it predates seq assignment). The cluster budget-write handler waits on THIS write’s own event_seq, looked up by the write’s event_id, instead of MAX(event_seq) for the authority: a concurrent same-authority commit (or an idempotent retry while later same-origin events already exist) can raise that MAX above this write’s seq, making the quorum wait target the wrong (higher) seq and roll back a write that itself reached quorum. Looked up by the unique event_id, this is race-free and, for an idempotent retry, returns the ORIGINAL event’s seq.

pub fn mutation_event_for_event_id( &self, event_id: &str, ) -> Result<Option<BudgetMutationRecord>, BudgetStoreError>

pub fn usage_projection_for_event_id( &self, event_id: &str, ) -> Result<Option<BudgetUsageRecord>, BudgetStoreError>

pub fn mutation_event_witness_for_event_id( &self, event_id: &str, ) -> Result<Option<(u64, Option<String>, Option<u64>)>, BudgetStoreError>

The quorum-witness identity of the mutation event stored under event_id: (event_seq, authority_id, lease_epoch), or None when no such event exists or it predates seq assignment. The witness must target the event’s STORED origin authority, not the current lease: an idempotent retry after leadership moved re-reads the already-written event, and peers advertise it under its ORIGINAL authority, so keying the wait on the current leader would look under the wrong origin and time out a write that already committed. A null-seq (legacy) row returns None so the caller falls back to the authority MAX rather than witnessing on seq 0.

pub fn record_abandoned_event_seqs( &self, seqs: &[u64], ) -> Result<(), BudgetStoreError>

Record snapshot-carried abandoned event sequences.

pub fn record_abandoned_event_seq_ranges( &self, ranges: &[(u64, u64)], ) -> Result<(), BudgetStoreError>

Record snapshot-carried abandoned event sequences as inclusive ranges.

impl SqliteBudgetStore

pub fn budget_import_floor( &self, authority_id: &str, ) -> Result<u64, BudgetStoreError>

pub fn record_budget_import_floors( &self, events: &[BudgetMutationRecord], ) -> Result<(), BudgetStoreError>

pub fn upsert_usage( &self, record: &BudgetUsageRecord, ) -> Result<(), BudgetStoreError>

pub fn import_snapshot_records( &self, usages: &[BudgetUsageRecord], events: &[BudgetMutationRecord], ) -> Result<(), BudgetStoreError>

pub fn import_snapshot_records_with_anchors( &self, usages: &[BudgetUsageRecord], events: &[BudgetMutationRecord], anchors: &[BudgetUsageRecord], abandoned_seq_ranges: &[(u64, u64)], covered_head: u64, ) -> Result<(), BudgetStoreError>

pub fn import_budget_snapshot( &self, snapshot: &BudgetStoreSnapshot, ) -> Result<(), BudgetStoreError>

pub fn import_budget_snapshot_with_anchor_provenance( &self, snapshot: &BudgetStoreSnapshot, provenance: &BudgetSnapshotAnchorProvenance, expected_leader_url: &str, expected_election_term: u64, cluster_service_token: &str, ) -> Result<(), BudgetStoreError>

pub fn import_delta_records( &self, usages: &[BudgetUsageRecord], events: &[BudgetMutationRecord], ) -> Result<(), BudgetStoreError>

pub fn export_budget_snapshot( &self, ) -> Result<BudgetStoreSnapshot, BudgetStoreError>

pub fn budget_snapshot_covered_head(&self) -> Result<u64, BudgetStoreError>

pub fn list_usage_history_anchors( &self, ) -> Result<Vec<BudgetUsageRecord>, BudgetStoreError>

impl SqliteBudgetStore

pub fn open(path: impl AsRef<Path>) -> Result<Self, BudgetStoreError>

pub fn budget_ack_heads(&self) -> Result<Vec<(String, u64)>, BudgetStoreError>

Per-origin contiguous ack head, anchored on the peer’s GLOBAL contiguous import head.

event_seq is a single store-wide dense sequence, so each origin’s events are a sparse subsequence of one global stream; a per-origin gaps-and- islands run (partitioned by authority) mis-models this: an origin whose block starts mid-sequence after a leadership change looks like a gap and is wrongly dropped, stalling its writes.

Instead this first computes the GLOBAL contiguous head H (the largest seq such that every global event_seq in 1..=H is present with no hole) as a single gaps-and-islands run over the whole stream (NOT partitioned), anchored at genesis (island 0). A hole caps H below it. Legacy NULL-authority events still occupy their global slot, so they count for contiguity (a present slot is not a gap) but are never reported as an ack. It then reports, per origin, MAX(event_seq) among that origin’s events with event_seq <= H.

Sound because global-contiguity enforcement on the puller means holding H implies holding EVERY event (all origins) at seq <= H, so head[origin] >= write.event_seq iff the peer durably holds that write and all its predecessors. Fail-closed: a global hole caps H, so no origin is ever reported past a missing global predecessor, and a missing prefix (nothing at seq 1) yields H = 0 and no acks.

NOTE: genesis anchoring assumes budget mutation events are never bulk-compacted below seq 1 (they are not today); if such compaction is added, anchor at a durable global floor instead.

NOTE: a rollback-retry that abandons a seq (existing_event_allowed) leaves a permanent interior hole that caps this GLOBAL head, stalling quorum budget-writes above the hole for EVERY origin cluster-wide (not per-origin) until operator intervention - it does not self-heal, since a snapshot from the holed leader carries the hole. Fail-closed (a hole withholds quorum and never over-counts). PERF: this runs on every cluster status request (once per sync round, an interval clamped as low as 50ms), so it must not rescan the whole ledger. The GLOBAL contiguous head is maintained incrementally against a durable watermark W (budget_ack_head_watermark): each call only advances W over the rows ABOVE it (a window scan bounded to event_seq > W), so steady state cost is O(new rows), not O(history). Soundness holds because W only advances while the run stays gap-free, and any DELETE of a mutation event resets W to 0 (reset_budget_ack_head_watermark, backstopped structurally by the budget_mutation_events_reset_ack_head_watermark AFTER DELETE trigger so a future or out-of-band delete site cannot skip the reset), forcing the next call to re-verify from genesis so a hole punched below W can never leave a stale-high head that over-counts.

pub fn list_abandoned_event_seqs(&self) -> Result<Vec<u64>, BudgetStoreError>

The abandoned/tombstoned event_seqs (rolled-back-then-re-appended writes’ original seqs) that budget_ack_heads treats as filled slots. Replicated in the cluster snapshot so a FRESH follower - which never held the original event and so never fired the delete-trigger that records it locally - still learns the slot is abandoned and does not stall its contiguous head at the hole.

pub fn list_abandoned_event_seq_ranges( &self, ) -> Result<Vec<(u64, u64)>, BudgetStoreError>

The abandoned event_seqs RANGE-ENCODED as inclusive (start, end) runs of consecutive seqs (ascending, non-overlapping).

The cluster snapshot carries the abandoned set this way instead of one entry per seq. A rollback storm abandons a long CONTIGUOUS run of seqs; enumerated, that is millions of integers that push the snapshot body past MAX_PEER_RESPONSE_BYTES, so the force-snapshot recovery path fails to decode cluster_snapshot() and the peer stalls in force_snapshot forever (unlike the delta path, the snapshot backstop has no further fallback). Range-encoded, each contiguous run collapses to one small pair, and the run count is bounded by the number of live mutation events (a run is separated from the next by a filled non-abandoned slot), which the snapshot already carries and which dominate the byte budget - so if the events fit under the cap the ranges do too. The encoding is LOSSLESS: a follower expands the runs to the identical seq set, so the filled-or-abandoned head-advance semantics are preserved bit-for-bit. Computed in SQL (gaps-and-islands) so the full seq set is never materialized here either.

pub fn list_abandoned_event_seqs_after( &self, after_seq: u64, ) -> Result<Vec<u64>, BudgetStoreError>

Abandoned event_seqs strictly above after_seq (ascending). The budget delta endpoint returns these alongside the pulled events so the puller can treat the abandoned slots as filled and not reject the leader’s legitimately gappy stream.

pub fn list_abandoned_event_seqs_in_range( &self, after_seq: u64, up_to_seq: u64, limit: usize, ) -> Result<Vec<u64>, BudgetStoreError>

Abandoned event_seqs in (after_seq, up_to_seq] (ascending), at most limit entries.

The budget delta endpoint uses this to BOUND the abandoned list it serves. A rollback storm can pack an arbitrarily large abandoned window between the follower cursor and the next live event; serializing all of it (the old unbounded list_abandoned_event_seqs_after + in-memory <= page_max filter) could exceed the peer-response byte cap, so the client rejects the body while decoding and never gets to classify the oversized window as snapshot-recovery, pinning the cursor forever. Both the upper bound and the row cap are pushed into SQL so a huge window is never materialized here.

pub fn hold_authority( &self, hold_id: &str, ) -> Result<Option<BudgetEventAuthority>, BudgetStoreError>

pub fn import_mutation_record( &self, record: &BudgetMutationRecord, ) -> Result<(), BudgetStoreError>

pub fn list_usages_after( &self, limit: usize, after_seq: Option<u64>, ) -> Result<Vec<BudgetUsageRecord>, BudgetStoreError>

pub fn list_all_usages( &self, ) -> Result<Vec<BudgetUsageRecord>, BudgetStoreError>

pub fn list_mutation_events_after_seq( &self, limit: usize, after_event_seq: u64, ) -> Result<Vec<BudgetMutationRecord>, BudgetStoreError>

pub fn try_increment_with_event_id( &self, capability_id: &str, grant_index: usize, max_invocations: Option<u32>, event_id: Option<&str>, ) -> Result<bool, BudgetStoreError>

Trait Implementations

impl BudgetStore for SqliteBudgetStore

fn try_increment( &self, capability_id: &str, grant_index: usize, max_invocations: Option<u32>, ) -> Result<bool, BudgetStoreError>

fn authorize_budget_hold( &self, request: BudgetAuthorizeHoldRequest, ) -> Result<BudgetAuthorizeHoldDecision, BudgetStoreError>

fn capture_invocation_reservations( &self, request: BudgetCaptureInvocationRequest, ) -> Result<BudgetInvocationCaptureDecision, BudgetStoreError>

fn authorize_cumulative_approval( &self, request: BudgetAuthorizeCumulativeApprovalRequest, ) -> Result<BudgetCumulativeApprovalAuthorizationDecision, BudgetStoreError>

fn cancel_captured_before_dispatch( &self, request: BudgetCancelCapturedBeforeDispatchRequest, ) -> Result<BudgetCapturedBeforeDispatchCancellationDecision, BudgetStoreError>

fn release_budget_hold( &self, request: BudgetReleaseHoldRequest, ) -> Result<BudgetReleaseHoldDecision, BudgetStoreError>

fn reverse_budget_hold( &self, request: BudgetReverseHoldRequest, ) -> Result<BudgetReverseHoldDecision, BudgetStoreError>

fn reconcile_budget_hold( &self, request: BudgetReconcileHoldRequest, ) -> Result<BudgetReconcileHoldDecision, BudgetStoreError>

fn capture_budget_hold( &self, request: BudgetCaptureHoldRequest, ) -> Result<BudgetCaptureHoldDecision, BudgetStoreError>

fn try_charge_cost( &self, capability_id: &str, grant_index: usize, max_invocations: Option<u32>, cost_units: u64, max_cost_per_invocation: Option<u64>, max_total_cost_units: Option<u64>, ) -> Result<bool, BudgetStoreError>

Atomically check monetary budget limits and record provisional exposure if within bounds.

fn try_charge_cost_with_ids( &self, capability_id: &str, grant_index: usize, max_invocations: Option<u32>, cost_units: u64, max_cost_per_invocation: Option<u64>, max_total_cost_units: Option<u64>, hold_id: Option<&str>, event_id: Option<&str>, ) -> Result<bool, BudgetStoreError>

fn try_charge_cost_with_ids_and_authority( &self, capability_id: &str, grant_index: usize, max_invocations: Option<u32>, cost_units: u64, max_cost_per_invocation: Option<u64>, max_total_cost_units: Option<u64>, hold_id: Option<&str>, event_id: Option<&str>, authority: Option<&BudgetEventAuthority>, ) -> Result<bool, BudgetStoreError>

Apply a charge under the caller’s durable hold/event identity and authority fence. Implementations must preserve all three values or return an explicit unsupported error. This method is required so a backend upgrade cannot compile successfully and fail only on live calls.

fn reverse_charge_cost( &self, capability_id: &str, grant_index: usize, cost_units: u64, ) -> Result<(), BudgetStoreError>

Reverse a previously applied provisional exposure for a pre-execution denial path.

fn reverse_charge_cost_with_ids( &self, capability_id: &str, grant_index: usize, cost_units: u64, hold_id: Option<&str>, event_id: Option<&str>, ) -> Result<(), BudgetStoreError>

fn reverse_charge_cost_with_ids_and_authority( &self, capability_id: &str, grant_index: usize, cost_units: u64, hold_id: Option<&str>, event_id: Option<&str>, authority: Option<&BudgetEventAuthority>, ) -> Result<(), BudgetStoreError>

Reverse a charge under the exact durable identity and authority fence.

fn reduce_charge_cost( &self, capability_id: &str, grant_index: usize, cost_units: u64, ) -> Result<(), BudgetStoreError>

Release a previously exposed monetary amount without changing invocation count.

fn reduce_charge_cost_with_ids( &self, capability_id: &str, grant_index: usize, cost_units: u64, hold_id: Option<&str>, event_id: Option<&str>, ) -> Result<(), BudgetStoreError>

fn reduce_charge_cost_with_ids_and_authority( &self, capability_id: &str, grant_index: usize, cost_units: u64, hold_id: Option<&str>, event_id: Option<&str>, authority: Option<&BudgetEventAuthority>, ) -> Result<(), BudgetStoreError>

Release exposure under the exact durable identity and authority fence.

fn settle_charge_cost( &self, capability_id: &str, grant_index: usize, exposed_cost_units: u64, realized_cost_units: u64, ) -> Result<(), BudgetStoreError>

Atomically release provisional exposure and record realized spend.

fn settle_charge_cost_with_ids( &self, capability_id: &str, grant_index: usize, exposed_cost_units: u64, realized_cost_units: u64, hold_id: Option<&str>, event_id: Option<&str>, ) -> Result<(), BudgetStoreError>

fn settle_charge_cost_with_ids_and_authority( &self, capability_id: &str, grant_index: usize, exposed_cost_units: u64, realized_cost_units: u64, hold_id: Option<&str>, event_id: Option<&str>, authority: Option<&BudgetEventAuthority>, ) -> Result<(), BudgetStoreError>

Reconcile exposure and spend under the exact durable identity and authority fence.

fn list_usages( &self, limit: usize, capability_id: Option<&str>, ) -> Result<Vec<BudgetUsageRecord>, BudgetStoreError>

fn get_usage( &self, capability_id: &str, grant_index: usize, ) -> Result<Option<BudgetUsageRecord>, BudgetStoreError>

fn get_invocation_quota_usage( &self, key: &BudgetQuotaKey, ) -> Result<Option<BudgetInvocationQuotaUsage>, BudgetStoreError>

fn get_cumulative_approval_account_usage( &self, key: &BudgetCumulativeApprovalAccountKey, ) -> Result<Option<BudgetCumulativeApprovalAccountUsage>, BudgetStoreError>

fn get_cumulative_approval_operation_usage( &self, operation_id: &str, ) -> Result<Option<BudgetCumulativeApprovalUsage>, BudgetStoreError>

fn list_mutation_events( &self, limit: usize, capability_id: Option<&str>, grant_index: Option<usize>, ) -> Result<Vec<BudgetMutationRecord>, BudgetStoreError>

fn reap_orphaned_holds( &self, realized_by_hold: &HashMap<String, u64>, ) -> Result<(usize, usize), BudgetStoreError>

fn count_open_holds(&self) -> Result<usize, BudgetStoreError>

fn list_open_delegated_reserved_hold_ids( &self, ) -> Result<Option<Vec<String>>, BudgetStoreError>

fn request_id_has_reserved_hold( &self, request_id: &str, ) -> Result<Option<bool>, BudgetStoreError>

fn get_budget_hold( &self, hold_id: &str, ) -> Result<Option<BudgetHoldSnapshot>, BudgetStoreError>

fn mark_hold_reserved( &self, hold_id: &str, reserved_until_unix_secs: i64, currency: &str, payment_reference: Option<&str>, envelope: &ReservedHoldEnvelope, ) -> Result<(), BudgetStoreError>

fn reserve_invocation_hold( &self, hold_id: &str, capability_id: &str, grant_index: usize, reserved_until_unix_secs: i64, envelope: &ReservedHoldEnvelope, ) -> Result<(), BudgetStoreError>

fn reap_expired_reserved_holds( &self, now_unix_secs: i64, ) -> Result<usize, BudgetStoreError>

fn budget_guarantee_level(&self) -> BudgetGuaranteeLevel

fn budget_authority_profile(&self) -> BudgetAuthorityProfile

fn budget_metering_profile(&self) -> BudgetMeteringProfile

impl Clone for SqliteBudgetStore

fn clone(&self) -> SqliteBudgetStore

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.