/**
 * AgentGuard® — Free-tier CALL QUOTA metering (local-only).
 *
 * This module meters how many ENFORCEMENT CALLS AgentGuard has metered for a
 * tenant in the current calendar month, purely from the local signed decision
 * store (~/.agentguard/<tenant>/decisions.ndjson). It powers:
 *   - the "Free tier: used / limit" usage bar in `agentguard serve`
 *   - the `agentguard usage` CLI summary
 *   - a one-time, first-run "surprise generosity" top-up to the free call quota
 *
 * ────────────────────────────────────────────────────────────────────────────
 * TWO HARD ARCHITECTURAL RULES — DO NOT VIOLATE:
 *
 * RULE 1 — The spend cap is SACRED. Nothing here reads, mutates, resets, or
 *   loosens the user's SPEND CAP or the enforcement path (spend-guard.ts /
 *   policy caps). The "free call quota" is AgentGuard's own generosity metric
 *   (how many free enforcement calls we give before a paid tier would apply) and
 *   is a COMPLETELY SEPARATE concept from the customer's money guardrail. When
 *   an agent hits its spend cap it still hard-stops, deterministically. A bonus
 *   here never changes a single cent of enforcement behavior.
 *
 * RULE 2 — ZERO data plane. No network calls. Everything is derived in-process
 *   from the local ledger and a small local state file. No user data, keys, or
 *   call contents leave the machine.
 * ────────────────────────────────────────────────────────────────────────────
 *
 * Patent notice: Protected by U.S. patent-pending technology
 * (App. Nos. 63/983,615; 63/983,621; 63/983,843; 63/984,626;
 * 64/071,781; 64/071,789).
 */
/** Site-stated free tier: "under 10,000 enforcement calls/month, no credit card". */
export declare const DEFAULT_FREE_LIMIT = 10000;
/** First-run generosity fires once a tenant crosses this fraction of the base quota. */
export declare const BONUS_THRESHOLD_PCT = 50;
export interface FreeTierOptions {
    /** Base directory. Defaults to AGENTGUARD_HOME or ~/.agentguard. */
    home?: string;
    /** Base monthly free call quota. Defaults to AGENTGUARD_FREE_LIMIT env or 10,000. */
    baseLimit?: number;
    /** Size of the one-time first-run bonus. Defaults to AGENTGUARD_FREE_BONUS env or baseLimit. */
    bonusCalls?: number;
    /** Override "now" for deterministic tests. */
    now?: Date;
}
/** Persisted, once-per-tenant free-tier state (local only). */
export interface FreeTierState {
    /** True once the first-run bonus has EVER been granted for this tenant. */
    bonusEverGranted: boolean;
    /** Size of the granted bonus in free calls (0 if never granted). */
    bonusCalls: number;
    /** ISO timestamp the bonus was granted. */
    grantedAt?: string;
    /** Calendar month (YYYY-MM) the bonus was granted in, for display only. */
    grantedMonth?: string;
}
export interface MonthlyUsage {
    tenant: string;
    /** Enforcement calls metered for this tenant this calendar month. */
    used: number;
    /** Base free quota (before any bonus). */
    baseLimit: number;
    /** One-time bonus calls already granted to this tenant (0 if none). */
    bonusCalls: number;
    /** Effective free quota this month = baseLimit + bonusCalls. */
    limit: number;
    /** used / limit as a whole-ish percent (one decimal), clamped to >= 0. */
    pctUsed: number;
    /** Calls remaining in the free quota (never negative). */
    remaining: number;
    /** ISO timestamp when the monthly counter resets (first instant of next month, UTC). */
    resetsAt: string;
    /** Whether the first-run bonus has ever been granted. */
    bonusEverGranted: boolean;
}
/** Read the local free-tier state file. Missing/corrupt → clean default. */
export declare function readFreeTierState(tenant: string, options?: FreeTierOptions): FreeTierState;
/**
 * Free-tier usage for a tenant this calendar month, from the LOCAL ledger only.
 * The effective `limit` includes any one-time bonus already granted.
 */
export declare function getMonthlyUsage(tenant: string, options?: FreeTierOptions): MonthlyUsage;
export interface BonusResult {
    /** True only when THIS call granted the bonus (the transition edge). */
    granted: boolean;
    /** Size of the bonus that was granted this call (0 if none). */
    bonusCalls: number;
    /** Usage AFTER any grant applied — safe to render directly. */
    usage: MonthlyUsage;
    /** Friendly, quota-scoped message when a bonus was just granted. */
    message?: string;
}
/** Copy that must make crystal clear this is the FREE CALL QUOTA, not a spend cap. */
export declare function bonusMessage(usage: MonthlyUsage): string;
/**
 * First-run "surprise generosity" — grants a ONE-TIME top-up to the FREE CALL
 * QUOTA (never the spend cap) the first time a tenant crosses ~50% of their
 * base quota (or would hit the limit). Idempotent: once `bonusEverGranted` is
 * recorded, this can never fire again for the tenant.
 *
 * Returns the (possibly updated) usage plus whether this call granted the bonus.
 * Enforcement / spend behavior is never touched.
 */
export declare function maybeGrantFirstTimeBonus(tenant: string, options?: FreeTierOptions): BonusResult;
//# sourceMappingURL=usage.d.ts.map