/**
 * The year, assembled from what was already written down.
 *
 * The last chapter of the arc, and the one that turns this product's argument
 * into something a stranger can audit. Everything below comes from the store
 * and the plans a team already keeps: **no new data, and nothing computed that
 * could not be checked against a document that already exists.**
 *
 * That constraint is the whole design. An annual report is the document most
 * likely to be quoted out of the room it was written in, and the one nobody
 * goes back to verify. So it may not contain a single figure that this tool
 * would refuse to print anywhere else — which means it is mostly a summing
 * exercise with a great many refusals attached.
 *
 * ## Four questions, and the fourth is the one that matters
 *
 * What was spent. What was planned. What arrived. **And what could not be
 * told** — which in a normal annual report is silently folded into one of the
 * other three, almost always into the flattering one.
 *
 * `verify` has kept those three outcomes apart since 1.39. A year is where the
 * temptation to collapse them is strongest, because "eleven of fourteen
 * actions arrived" reads better than "eleven arrived, one did not, and two
 * could not be judged" — and the second sentence is the one that tells
 * somebody their measurement has a hole in it.
 *
 * ## It reports the record, not the team
 *
 * No per-person anything, no velocity, no ranking of who planned well. The
 * doctrine rule from 1.44, and it matters most here: an annual document is
 * exactly where a cost tool starts being used for performance review, and the
 * way to not be is to hold no data that could be.
 */
import type { PlanDocument } from './plan.js';
import type { PlanVerification } from './verify.js';
import type { OutcomeReport } from './outcome.js';
/** One period the year is built from, as the caller sliced it. */
export interface AnnualPeriod {
    /** `YYYY-MM`. */
    month: string;
    usd: number;
    calls: number;
    /** The plan made for this period, when one was. */
    plan?: PlanDocument;
    /** The verification of the previous plan, when one was run. */
    verification?: PlanVerification;
    /** Outcomes recorded in this period, when any were. */
    outcomes?: OutcomeReport;
}
export interface AnnualRecord {
    schemaVersion: 1;
    year: string;
    /** Months present, oldest first. Gaps are named rather than interpolated. */
    months: Array<{
        month: string;
        usd: number;
        calls: number;
    }>;
    /**
     * Months of the year with no record at all.
     *
     * Named, never filled. A year report that quietly covers nine months and
     * prints an annual total is wrong by a quarter and says nothing about it.
     */
    missingMonths: string[];
    totalUsd: number;
    totalCalls: number;
    /**
     * What was planned and what became of it — three outcomes, never two.
     *
     * `cannotTell` is the field an ordinary annual report does not have, and its
     * absence is how a year of unmeasurable promises turns into a year of kept
     * ones.
     */
    promises: {
        planned: number;
        arrived: number;
        notArrived: number;
        cannotTell: number;
        /**
         * Dollars the plans projected, summed.
         *
         * **There is deliberately no `arrivedUsd` beside it**, and the reason is
         * worth the paragraph: a verification says whether each action *arrived*,
         * and its `observed` map carries where the money sits now — but the
         * document has never carried a per-action figure for the saving that
         * actually landed. Summing one out of the observations would mean deciding
         * which of several numbers per action is "the saving", which is a
         * judgement the verification refused to make and this module has no
         * standing to make on its behalf.
         *
         * So the year says what was promised and how many promises were kept, and
         * says plainly that it cannot put a dollar figure on the kept ones. The
         * alternative — a plausible number assembled here — is precisely the
         * annual-report arithmetic this document exists to replace.
         */
        projectedUsd: number;
    };
    /**
     * The year's outcome coverage, or null when nothing recorded one.
     *
     * Null rather than a rate of zero, for the reason it has been null
     * everywhere since 1.50.4: an uninstrumented year and a failing year are
     * different sentences.
     */
    outcomes: {
        recorded: number;
        parsed: number;
        /** Share of the year's spend that carried no outcome. */
        unrecordedUsd: number;
    } | null;
    /**
     * Everything this record cannot say, named.
     *
     * The section an annual report is usually missing, and the reason this one
     * is worth trusting: a document that lists its own blind spots is a document
     * somebody can act on the rest of.
     */
    cannotSay: string[];
}
export declare function annualRecord(year: string, periods: readonly AnnualPeriod[]): AnnualRecord;
//# sourceMappingURL=annual.d.ts.map