/**
 * Durable execution-budget ledger.
 *
 * An append-only, idempotent, replay-safe accounting ledger for durable
 * execution budgets. Totals are always derived by replaying entries — never by
 * mutating a running counter — so a resume after interruption cannot double
 * charge and a cancelled run does not erase consumed budget.
 *
 * Estimated amounts are recorded first and reconciled against provider actuals
 * via `reconcileEntry` (idempotent). Unknown pricing is classified explicitly
 * rather than guessed. Cached-input usage is tracked separately. Subagent usage
 * is charged to both the child and the parent.
 */
import type { BudgetLedgerEntry, BudgetResource, BudgetThresholds, ExecutionBudget, ThresholdVerdict } from "./types.js";
export interface BudgetLedger {
    runId: string;
    entries: readonly BudgetLedgerEntry[];
}
export declare function resourcesOfBudget(): readonly BudgetResource[];
export declare function createBudgetLedger(runId: string): BudgetLedger;
export interface AppendResult {
    ledger: BudgetLedger;
    appended: boolean;
    reason?: string;
}
/**
 * Append a single durable entry.
 *
 * Idempotent by `entryId`: appending an entry that already exists returns the
 * same ledger with `appended: false`, so replay or resume can never double
 * charge. Amounts are snapshotted defensively.
 */
export declare function appendEntry(ledger: BudgetLedger, entry: BudgetLedgerEntry): AppendResult;
/**
 * Reconcile an estimated entry against a provider actual.
 *
 * The actual is appended as a new (separate) entry referencing the same
 * `sourceEventId` with kind `actual`. Reformatting of the provisional estimate
 * preserves the audit trail. Idempotent: re-applying the same actual is
 * rejected as a duplicate entryId.
 */
export declare function reconcileEntry(ledger: BudgetLedger, estimatedEntryId: string, actual: Omit<BudgetLedgerEntry, "estimatedOrActual" | "entryId" | "runId"> & {
    entryId?: string;
}): AppendResult;
export interface Usage {
    total: number;
    estimated: number;
    actual: number;
}
/**
 * Derive usage for a resource by replay (sum only the most authoritative kind
 * per entry). Actual supersedes the estimated entry that shares a sourceEventId
 * only for reporting clarity; totals count each entry once by idempotency.
 */
export declare function getUsage(ledger: BudgetLedger, resource: BudgetResource): Usage;
export declare function sumResource(ledger: BudgetLedger, resource: BudgetResource): number;
/**
 * Count distinct provider/model-billed estimated entries reconciled with an
 * actual for the same sourceEventId, so we can assert no-persistent-overshoot.
 */
export declare function resolvedSourceEvents(ledger: BudgetLedger): number;
export interface ThresholdOutput {
    verdicts: ThresholdVerdict[];
    blocked: boolean;
    hardReached: ThresholdVerdict[];
    softReached: ThresholdVerdict[];
}
/**
 * Evaluate soft/hard thresholds for every budget dimension given thresholds.
 * Reserved capacity (finalization + recovery) is reserved from the hard
 * threshold before ordinary consumption is judged.
 */
export declare function evaluateThresholds(ledger: BudgetLedger, thresholds: BudgetThresholds, options?: {
    reserved?: number;
}): ThresholdOutput;
export interface BudgetAllocationInput {
    global: Partial<ExecutionBudget>;
    user?: Partial<ExecutionBudget>;
    run?: Partial<ExecutionBudget>;
    phase?: Partial<ExecutionBudget>;
    role?: Partial<ExecutionBudget>;
    subagent?: Partial<ExecutionBudget>;
}
export interface AllocationResult {
    effective: Partial<ExecutionBudget>;
    blocked: boolean;
    reasons: string[];
    /** A manually-configured value may never exceed the unallocated remainder. */
    remainderOverflow: string[];
}
/**
 * Resolve the effective budget by intersecting the hierarchy: each level is
 * capped by the unallocated remainder of its parent. A child can never request
 * more than the parent has left. Lower levels may only reduce.
 */
export declare function resolveBudgetHierarchy(input: BudgetAllocationInput): AllocationResult;
/**
 * Reserve capacity for finalization. Returns the allowed-discretionary value
 * (hard minus reserve) and the reserve value, and never lets ordinary execution
 * spend the reserve: ordinary use is bounded by the reserved-adjusted hard.
 */
export declare function reserveFinalization(limit: number, reserve: number): {
    discretionary: number;
    reserve: number;
};
/** Mark a typed budget block when a hard limit is reached for a resource. */
export declare function budgetBlock(runId: string, resource: BudgetResource, used: number, threshold: number, finalizationReserveAvailable: boolean): {
    blocked: true;
    runId: string;
    resource: BudgetResource;
    used: number;
    threshold: number;
    reasonCode: "HARD_LIMIT_REACHED";
    finalizationReserveAvailable: boolean;
};
//# sourceMappingURL=budget-ledger.d.ts.map