/**
 * Usage command — local usage-ledger reporting (usage-ledger plan,
 * Ticket 5).
 *
 * The command is presentation + aggregation only: it receives an
 * already-read {@link UsageLedger} through its dependency and folds it
 * into the DESIGN D8 report envelope. Ledger reading (path resolution
 * against the config root, fail-open parse) is owned by the dispatcher
 * (`src/index.ts` `handleUsage`), which follows `handleCache`'s
 * injection-free posture — no injected reader object; tests inject
 * `env.SCOUTLINE_CONFIG_DIR` at a prepared directory and the production
 * `readUsageLedger(...)` (default deps: real reader, no `onWarning`)
 * preserves D8's silent-on-corrupt contract.
 *
 * Output shapes (DESIGN D8):
 *
 *   - data mode: the raw envelope JSON (`schemaVersion`, `windowDays`,
 *     `generatedAt`, `unitNote`, `providers[]` with per-provider
 *     `totals` and ascending `capabilities[]`).
 *   - tty/compact/markdown/refs: a fixed-order table of the same data.
 *
 * Missing or corrupt ledgers surface as an empty window with exit 0 —
 * never a throw, never stderr noise (the fail-open read already
 * normalized the failure away before this module sees a ledger).
 */
import type { CommandResult } from "../command-invocation.js";
import type { UsageCounters, UsageLedger } from "../lib/usage-ledger.js";
/** One D8 envelope's unit note — also rendered as the table's caption. */
export declare const USAGE_UNIT_NOTE = "counts are billable call attempts; providers do not report credit costs";
/** Default reporting window in days (DESIGN D8). */
export declare const DEFAULT_USAGE_WINDOW_DAYS = 7;
/**
 * Maximum reporting window in days. Generous far beyond the 90-day
 * retention horizon (any larger window shows exactly the retained
 * history), while staying orders of magnitude below the ~±100,000,000
 * day range JavaScript Dates can represent — an unvalidated `--days
 * 1000000000` would otherwise pass the integer/≥1 checks and throw a
 * RangeError computing the cutoff date.
 */
export declare const MAX_USAGE_WINDOW_DAYS = 100000;
/** One capability row: the emitted `capabilityId` verbatim + its counters. */
export interface UsageCapabilitySummary {
    readonly capabilityId: string;
    readonly counters: UsageCounters;
}
/** One provider row: window totals plus per-capability rows (id asc). */
export interface UsageProviderSummary {
    readonly provider: string;
    readonly totals: UsageCounters;
    readonly capabilities: readonly UsageCapabilitySummary[];
}
/** The D8 data-mode envelope. */
export interface UsageReport {
    readonly schemaVersion: 1;
    readonly windowDays: number;
    readonly generatedAt: number;
    readonly unitNote: string;
    readonly providers: readonly UsageProviderSummary[];
}
export interface UsageReportOptions {
    /** Window size in UTC days (dispatcher already validated ≥ 1). */
    readonly windowDays: number;
    /** Clock for `generatedAt` and the window's upper-edge day key. */
    readonly now: () => number;
    /** Optional provider filter (dispatcher already validated known ids). */
    readonly provider?: string;
}
/**
 * Fold a ledger into the D8 report: keep day keys within the last
 * `windowDays` UTC days (today's key inclusive; the key exactly
 * `windowDays - 1` days back is the oldest kept), optionally keep one
 * provider only, sum every counter axis across days and capabilities,
 * and emit providers ascending / capabilities ascending. Pure: no I/O,
 * never mutates the input ledger.
 */
export declare function buildUsageReport(ledger: UsageLedger, options: UsageReportOptions): UsageReport;
/**
 * Render the report as a fixed-order table (DESIGN D8's tty
 * presentation): providers ascending, capabilities ascending, every
 * counter axis in a fixed column. Pure.
 */
export declare function formatUsageReport(report: UsageReport): string;
export interface UsageCommandDependencies {
    /** Reads the ledger (production: `readUsageLedger` over the resolved path). */
    readonly readLedger: () => Promise<UsageLedger>;
    /** Window size in UTC days; the dispatcher validated it before this seam. */
    readonly windowDays: number;
    /** Optional provider filter; the dispatcher validated it before this seam. */
    readonly provider?: string;
    /** Clock for `generatedAt` and the window edge. */
    readonly now: () => number;
}
/**
 * Run the `usage` command: read the ledger, fold it into the D8
 * envelope, and return it as base data with the shared text-mode
 * presentation. Exit code is 0 on success; the fail-open read means a
 * missing or corrupt ledger is already an empty ledger here.
 */
export declare function usageCommand(deps: UsageCommandDependencies): Promise<CommandResult<UsageReport>>;
export declare const USAGE_HELP: string;
//# sourceMappingURL=usage.d.ts.map