/**
 * Windowed, priced savings over the analytics ledger.
 *
 * WHY THIS IS NOT THE MCP REPORT. `get_optimization_report` answers "what has
 * token-optimizer saved, broken down by tool, hook and server" over a date
 * range the caller has to supply. The question an operator actually asks is the
 * other one -- "what did it save me today, this week, this month, and what was
 * that worth" -- and nothing in this package answered it. The breakdowns here
 * are by MODEL and by CLIENT for the same reason: those are the two dimensions
 * a bill is denominated in.
 *
 * THE PROVENANCE GATE IS INHERITED, NOT RELAXED. Every number below is built
 * from `verifiedTransportDelta`, which is zero for any row that cannot prove a
 * before-state from two materialized payloads, and from `priceTokenUsage`,
 * which refuses a model it does not have an exact catalog entry for. So a
 * window can legitimately report tokens saved and no dollar figure, and that
 * pair is reported as it is rather than averaged into something presentable.
 *
 * THE WINDOWS NEST; THEY DO NOT PARTITION. Today is inside the last 7 days is
 * inside the last 30. Summing them double-counts, which is exactly the mistake
 * a reader makes with a column of numbers that look like buckets, so the label
 * on each one says "last N days" and `since` is carried alongside.
 */
import type { AnalyticsEntry } from '../analytics/analytics-types.js';
import type { AnalyticsRollup } from '../analytics/analytics-rollup.js';
/** The group name used for a row that carries no attribution of its own. */
export declare const UNATTRIBUTED = "(unattributed)";
/**
 * The dollar value of one row's verified transport delta, or null.
 *
 * ONE IMMEDIATE UNCACHED-INPUT EQUIVALENT, which is the same definition
 * `get_optimization_report` publishes, and this is deliberately the only copy
 * of it: two copies of a pricing rule drift, and the one that drifts is always
 * the one nobody is looking at.
 *
 * NULL IS NOT ZERO. A model with no exact catalog entry has an unknown price,
 * and folding it in at zero would make a report look cheaper the less it knew.
 */
export declare function priceVerifiedDelta(entry: AnalyticsEntry): number | null;
/**
 * What a token count on one row costs as uncached input, at that row's rate.
 *
 * ONE FUNCTION FOR EVERY SURFACE THAT PRICES A ROW. The savings report prices
 * the verified delta; the dashboard also prices the context a row returned. If
 * each kept its own copy of this, a correction to the request shape -- which
 * provider, which route, which request-time tier -- would land on one surface
 * and not the other, and the two would quietly stop agreeing about the same
 * row.
 *
 * THE SIGN TRAVELS SEPARATELY FROM THE RATE, because a tier is chosen by the
 * size of a request and a negative count is not a smaller request. The
 * magnitude is priced and the direction is reapplied afterwards.
 */
export declare function priceEntryTokens(entry: AnalyticsEntry, tokens: number): number | null;
export interface SavingsWindow {
    readonly label: string;
    /** ISO instant the window opens at, or null for all time. */
    readonly since: string | null;
    readonly operations: number;
    readonly tokensSaved: number;
    readonly tokensBefore: number;
    readonly savingsPercent: number;
    readonly costUsd: number | null;
    readonly pricedOperations: number;
    readonly eligibleOperations: number;
}
export interface SavingsGroup {
    readonly name: string;
    readonly operations: number;
    readonly tokensSaved: number;
    /**
     * The before-state of the SAME rows `tokensSaved` came from.
     *
     * A GROUP CAN BE HELD TO A PERCENTAGE ONLY IF IT CARRIES ITS OWN
     * DENOMINATOR. Without this field the only honest question to ask of a
     * client is "did it save anything at all", and a gate built on that would
     * pass a client whose traffic we barely touched.
     */
    readonly tokensBefore: number;
    /** `tokensSaved` over `tokensBefore`, by the same rule the windows use. */
    readonly savingsPercent: number;
    readonly costUsd: number | null;
    readonly pricedOperations: number;
    readonly eligibleOperations: number;
}
export interface SavingsReport {
    readonly windows: readonly SavingsWindow[];
    readonly byModel: readonly SavingsGroup[];
    readonly byClient: readonly SavingsGroup[];
    /** Every row in the ledger, including the ones no claim is built on. */
    readonly totalEntries: number;
    /** Rows that cleared the provenance gate in one direction or the other. */
    readonly eligibleEntries: number;
    /** Model ids an eligible row named that the catalog has no price for. */
    readonly unpricedModels: readonly string[];
    /**
     * How much of the report above came from days that are no longer rows.
     *
     * DISCLOSED, BECAUSE IT CHANGES WHAT ELSE CAN BE ASKED. The figures are the
     * same either way -- that is the point of folding rather than deleting --
     * but a folded day can no longer be filtered by session or exported row by
     * row, and an operator who cannot see that a day was folded would read an
     * empty session query as an empty day.
     */
    readonly foldedOperations: number;
    /** Local days the figures above drew from totals rather than rows. */
    readonly foldedDays: number;
}
/**
 * Midnight at the start of `now`'s LOCAL day.
 *
 * LOCAL, NOT UTC, and the difference is not cosmetic. Entries are stamped in
 * UTC, so a UTC day boundary would put an operator in UTC-7 into "tomorrow" at
 * 5pm: they would run the command after an afternoon's work and be told they
 * had saved nothing today, while the work sat in a window labelled for a day
 * that had not started where they were. The boundary a person means by "today"
 * is the one on their own clock.
 */
export declare function startOfLocalDay(now: Date): Date;
/**
 * The local calendar day a stamp falls in, as `YYYY-MM-DD`.
 *
 * LOCAL, NOT UTC, because the report's windows are local days. A UTC key would
 * put the evening's requests in tomorrow for anyone east of Greenwich, and a
 * folded day would then straddle a boundary that the raw rows did not.
 */
export declare function localDayKey(at: Date): string;
/** Midnight that opens a `YYYY-MM-DD` key, in local time, or null if unparseable. */
export declare function startOfDayKey(key: string): Date | null;
/**
 * CALENDAR DAYS, NOT ROLLING HOURS. "Last 7 days" opens at the start of the
 * local day six days back, so it covers seven days including today -- which is
 * what the phrase means to a reader and what makes two runs an hour apart
 * report the same window rather than a silently sliding one.
 */
export declare function windowBoundaries(now: Date): readonly {
    readonly label: string;
    readonly since: Date | null;
}[];
/**
 * A dollar figure the report can publish.
 *
 * QUANTIZED BECAUSE ADDITION IN BINARY FLOATING POINT IS NOT ASSOCIATIVE. The
 * same set of priced rows summed in a different order lands a few parts in
 * 10^15 apart, so without this the report's own total depends on the order the
 * rows came back in -- and once a day is folded, the fold sums that day first
 * and the window adds one term where it used to add hundreds. Two readings of
 * the same history would then disagree in the last digits, which is exactly
 * the kind of disagreement nobody can explain and everybody distrusts.
 *
 * TEN DECIMALS, which is a ten-billionth of a dollar: far below the smallest
 * real price in the catalog and far above the noise being removed.
 */
/**
 * The last word in a group ordering, so a tie has one answer everywhere.
 *
 * CODE POINTS, NOT `localeCompare`. Two models that saved the same number of
 * tokens compared equal, and the order then came from whatever collation the
 * host's locale supplies -- so the same ledger printed its table in a different
 * order on a different machine, with every figure identical. A published table
 * whose row order moves for no visible reason is read as the figures having
 * moved.
 */
export declare function byName(a: {
    name: string;
}, b: {
    name: string;
}): number;
export declare function usd(amount: number): number;
/**
 * The rows a dated window covers.
 *
 * AN UNPARSEABLE STAMP IS OUT OF EVERY DATED WINDOW, not silently in all of
 * them: it cannot be placed, and placing it anyway would move a number an
 * operator reads as a day's work.
 *
 * ONE DEFINITION, because both the windows and the savings gate ask this same
 * question. A gate that filtered rows its own way would eventually hold a
 * client to a period the report never showed.
 */
export declare function withinWindow(entries: readonly AnalyticsEntry[], since: Date | null): readonly AnalyticsEntry[];
/**
 * The folded days a dated window covers.
 *
 * A FOLDED DAY IS IN OR OUT WHOLE. Every dated window opens at a local
 * midnight and a fold never spans two local days, so the day it names is
 * either entirely inside this window or entirely outside it -- which is what
 * makes a day the exact grain rather than an approximate one.
 */
export declare function foldedWithin(rollups: readonly AnalyticsRollup[], since: Date | null): readonly AnalyticsRollup[];
export declare function summarize(entries: readonly AnalyticsEntry[], label: string, since: Date | null, rollups?: readonly AnalyticsRollup[]): SavingsWindow;
/**
 * Groups by one attribution, dropping the rows no claim is built on.
 *
 * ROWS WITH NO VERIFIED DELTA ARE LEFT OUT OF THE GROUPS ENTIRELY, which is
 * the opposite of the windows above. A window is a period and has to account
 * for everything that happened in it; a breakdown by model exists to say where
 * a saving came from, and a model whose every row failed the gate contributed
 * none -- listing it at zero would read as a model the compressor cannot help,
 * when what happened is that nothing was measurable.
 */
export declare function groupBy(entries: readonly AnalyticsEntry[], key: (entry: AnalyticsEntry) => string, folded?: {
    readonly rollups: readonly AnalyticsRollup[];
    readonly key: (rollup: AnalyticsRollup) => string;
}): readonly SavingsGroup[];
/**
 * The model ids an eligible row named that no catalog entry prices.
 *
 * NAMED, NOT COUNTED. `(8/12 priced)` tells an operator that a third of the
 * dollar figure is missing without telling them what to do about it, and the
 * model id is the one fact that makes it actionable. A per-model breakdown
 * carries the same fact only while the row survives the top-N truncation,
 * which is exactly the case where the unpriced model is the small one.
 *
 * NO FALLBACK RATE, EVER. Pricing an unknown model at some default -- the
 * obvious way to make this note unnecessary -- would hand back a dollar figure
 * nobody was ever charged, indistinguishable in the output from a measured
 * one. An absent number can be chased; a fabricated one cannot be detected.
 */
export declare function unpricedModels(entries: readonly AnalyticsEntry[], rollups?: readonly AnalyticsRollup[]): readonly string[];
/**
 * The whole report, from live rows and from whatever has been folded away.
 *
 * THE FOLDED DAYS ARE PART OF EVERY FIGURE, not a footnote beside them. The
 * alternative -- rows for the recent window and a note saying older work
 * existed -- is the failure this policy was written to avoid: a product that
 * reports less the longer it runs, because the evidence of its own work was
 * deleted to save a disk.
 */
export declare function buildReport(entries: readonly AnalyticsEntry[], now?: Date, rollups?: readonly AnalyticsRollup[]): SavingsReport;
//# sourceMappingURL=windows.d.ts.map