@trazum/core 1.50.10 → 1.51.0

package/dist/annual.d.ts

@@ -0,0 +1,122 @@
+/**
+ * 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

package/dist/annual.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annual.d.ts","sourceRoot":"","sources":["../src/annual.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC,uDAAuD;IACvD,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,CAAC,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D;;;;;OAKG;IACH,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,QAAQ,EAAE;QACR,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB;;;;;;;;;;;;;;;;WAgBG;QACH,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF;;;;;;OAMG;IACH,QAAQ,EAAE;QACR,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,yDAAyD;QACzD,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,IAAI,CAAC;IACT;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AASD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,YAAY,CA+DzF"}

package/dist/annual.js

@@ -0,0 +1,101 @@
+/**
+ * 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.
+ */
+/**
+ * The twelve months of a year, so a gap is a fact rather than an absence.
+ */
+function monthsOf(year) {
+    return Array.from({ length: 12 }, (_, i) => `${year}-${String(i + 1).padStart(2, '0')}`);
+}
+export function annualRecord(year, periods) {
+    const inYear = [...periods]
+        .filter((p) => p.month.startsWith(`${year}-`))
+        .sort((a, b) => a.month.localeCompare(b.month));
+    const present = new Set(inYear.map((p) => p.month));
+    const missingMonths = monthsOf(year).filter((m) => !present.has(m));
+    let planned = 0;
+    let arrived = 0;
+    let notArrived = 0;
+    let cannotTell = 0;
+    let projectedUsd = 0;
+    for (const period of inYear) {
+        if (period.plan !== undefined) {
+            planned += period.plan.actions.length;
+            projectedUsd += period.plan.projectedSavingUsd;
+        }
+        if (period.verification !== undefined) {
+            arrived += period.verification.arrived;
+            notArrived += period.verification.notArrived;
+            cannotTell += period.verification.cannotTell;
+        }
+    }
+    const withOutcomes = inYear.filter((p) => p.outcomes !== undefined);
+    const outcomes = withOutcomes.length === 0
+        ? null
+        : {
+            recorded: withOutcomes.reduce((sum, p) => sum + (p.outcomes?.coverage.recorded ?? 0), 0),
+            parsed: withOutcomes.reduce((sum, p) => sum + (p.outcomes?.coverage.parsed ?? 0), 0),
+            unrecordedUsd: withOutcomes.reduce((sum, p) => sum + (p.outcomes?.coverage.unrecordedUsd ?? 0), 0),
+        };
+    const cannotSay = [];
+    if (missingMonths.length > 0)
+        cannotSay.push('months-missing');
+    if (planned === 0)
+        cannotSay.push('nothing-was-planned');
+    else if (arrived + notArrived + cannotTell === 0)
+        cannotSay.push('nothing-was-verified');
+    if (cannotTell > 0)
+        cannotSay.push('some-promises-unjudgeable');
+    /**
+     * Named every time there is anything to verify, because it is a permanent
+     * limit of the record rather than a gap in this particular year.
+     */
+    if (arrived > 0)
+        cannotSay.push('arrived-savings-not-quantified');
+    if (outcomes === null)
+        cannotSay.push('no-outcomes-recorded');
+    else if (outcomes.recorded < outcomes.parsed)
+        cannotSay.push('outcome-coverage-partial');
+    return {
+        schemaVersion: 1,
+        year,
+        months: inYear.map((p) => ({ month: p.month, usd: p.usd, calls: p.calls })),
+        missingMonths,
+        totalUsd: inYear.reduce((sum, p) => sum + p.usd, 0),
+        totalCalls: inYear.reduce((sum, p) => sum + p.calls, 0),
+        promises: { planned, arrived, notArrived, cannotTell, projectedUsd },
+        outcomes,
+        cannotSay,
+    };
+}
+//# sourceMappingURL=annual.js.map

package/dist/annual.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annual.js","sourceRoot":"","sources":["../src/annual.ts"],"names":[],"mappings":"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"}

package/dist/commitment.d.ts

@@ -0,0 +1,144 @@
+/**
+ * What a committed-use deal would have been worth **on the traffic you
+ * actually had**.
+ *
+ * Providers sell committed-use and reserved-capacity contracts, and every team
+ * that signs one is doing arithmetic in a spreadsheet against a number they
+ * guessed. That is exactly the failure this product exists to end — and it is
+ * the highest-stakes instance of it, because the guess is annual and signed.
+ *
+ * ## An as-if calculation, and the wording never blurs it
+ *
+ * "On the traffic you actually had, this commitment would have saved $X" is a
+ * measurement of the past.
+ *
+ * "You will save $X" is a claim about the future, and this product has refused
+ * that at every scale since 1.27. Nothing here projects, extrapolates, fits a
+ * trend or annualises a partial month. Every figure describes months that
+ * happened, and the type says so in a field a machine reader can check.
+ *
+ * ## Both directions, because one direction is the sales pitch
+ *
+ * A commitment is a **floor** as well as a discount. Below the floor you pay
+ * for capacity you did not use, and a saving quoted without that half is not
+ * an analysis — it is the vendor's slide.
+ *
+ * So every month is priced both ways, the months that would have fallen short
+ * are counted and named, and what the unused floor would have cost is its own
+ * figure rather than netted quietly against the good months.
+ *
+ * ## The shortfall risk is a count, not a probability
+ *
+ * "Three of your last twelve months would have fallen short, by $400, $150 and
+ * $2,900" is a measurement. "There is a 25% chance of shortfall" is a model of
+ * a distribution nobody fitted, presented with the authority of arithmetic.
+ * Only the first is available from a log, so only the first is printed.
+ */
+/** The deal, as the provider states it. */
+export interface CommitmentTerms {
+    /**
+     * What you commit to spending each month, **after** the discount — which is
+     * how these contracts are almost always written.
+     *
+     * If your discounted usage comes in under this, you pay this anyway.
+     */
+    monthlyFloorUsd: number;
+    /** The discount, 0-1. 0.2 is twenty per cent off. */
+    discount: number;
+    /** How many months the commitment runs. */
+    months: number;
+}
+/** One measured month, as the caller sliced it. */
+export interface MeasuredMonth {
+    /** `YYYY-MM`. */
+    month: string;
+    usd: number;
+}
+export interface MonthReplay {
+    month: string;
+    /** What was actually paid, with no commitment. */
+    listUsd: number;
+    /** What the discounted usage would have come to. */
+    discountedUsd: number;
+    /** What would actually have been paid: the floor, or the discounted usage. */
+    paidUsd: number;
+    /** Positive means the commitment saved money that month. */
+    savingUsd: number;
+    /** Whether the floor was the binding number — a month that fell short. */
+    shortfall: boolean;
+    /** What the unused floor cost, in a month that fell short. Zero otherwise. */
+    unusedFloorUsd: number;
+}
+export type CommitmentUnknown = 'no-history' | 'too-few-months' | 'partial-months-excluded-everything';
+export interface CommitmentReplay {
+    /**
+     * Always `measured-past`. There is no other value, and the field exists so a
+     * machine reader cannot mistake this for a projection — the same reason
+     * every other document in this product carries its provenance.
+     */
+    provenance: 'measured-past';
+    months: MonthReplay[];
+    /** Summed over the months replayed, positive meaning the deal won. */
+    netUsd: number;
+    /** What the good months saved, before the shortfalls are taken off. */
+    savedInGoodMonthsUsd: number;
+    /**
+     * What the shortfall months cost, kept as its own figure.
+     *
+     * Netted against the savings it disappears, and the disappearing is the
+     * whole trick a vendor's slide relies on.
+     */
+    lostToUnusedFloorUsd: number;
+    /** How many of the measured months would have fallen short. A count, never a rate. */
+    shortfallMonths: number;
+    /**
+     * The monthly spend at which the commitment stops losing money.
+     *
+     * Equal to the floor: below it you pay the floor for less usage. Above it
+     * the saving grows, first as (spend − floor) and then, once discounted usage
+     * clears the floor, as spend × discount.
+     */
+    breakEvenMonthlyUsd: number;
+    /**
+     * Measured spread across the months replayed — lowest and highest, and how
+     * far the range spans as a share of the median.
+     *
+     * The honest form of "shortfall risk": a reader looking at a range wider than
+     * the floor can see the deal is a bet, without anybody modelling a
+     * distribution nobody fitted.
+     */
+    spread: {
+        lowUsd: number;
+        highUsd: number;
+        medianUsd: number;
+    } | null;
+    /** Set when nothing could be replayed. A refusal never arrives bare. */
+    unknown: CommitmentUnknown | null;
+    /** How many whole months would settle it, when there are too few. */
+    monthsNeeded: number | null;
+}
+/**
+ * The fewest whole months worth replaying a commitment against.
+ *
+ * Three. Two months cannot show a shortfall pattern and one cannot show
+ * anything at all — and a commitment is signed for a year, so an answer from a
+ * single month is a year-long decision made on a fortnight of evidence.
+ */
+export declare const MIN_MONTHS_FOR_REPLAY = 3;
+export declare function replayCommitment(history: readonly MeasuredMonth[], terms: CommitmentTerms): CommitmentReplay;
+/**
+ * Whether the replay covers as long as the commitment runs.
+ *
+ * Kept separate from the refusals because it does not stop the arithmetic: six
+ * months of history against a twelve-month deal is a real answer about six
+ * months, and saying so is more useful than refusing. What it must not do is
+ * go unsaid — a twelve-month decision read off half a year of evidence, with
+ * nothing on the page marking the gap, is the spreadsheet this module was
+ * written to replace.
+ */
+export declare function coversTheTerm(replay: CommitmentReplay, terms: CommitmentTerms): {
+    covered: number;
+    ofMonths: number;
+    short: boolean;
+};
+//# sourceMappingURL=commitment.d.ts.map

package/dist/commitment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commitment.d.ts","sourceRoot":"","sources":["../src/commitment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC5B,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB,8EAA8E;IAC9E,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,iBAAiB,GACzB,YAAY,GACZ,gBAAgB,GAChB,oCAAoC,CAAC;AAEzC,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,UAAU,EAAE,eAAe,CAAC;IAC5B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAC7B,sFAAsF;IACtF,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;;;;OAOG;IACH,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACtE,wEAAwE;IACxE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAClC,qEAAqE;IACrE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,KAAK,EAAE,eAAe,GACrB,gBAAgB,CAkDlB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE,eAAe,GACrB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAMvD"}

package/dist/commitment.js

@@ -0,0 +1,110 @@
+/**
+ * What a committed-use deal would have been worth **on the traffic you
+ * actually had**.
+ *
+ * Providers sell committed-use and reserved-capacity contracts, and every team
+ * that signs one is doing arithmetic in a spreadsheet against a number they
+ * guessed. That is exactly the failure this product exists to end — and it is
+ * the highest-stakes instance of it, because the guess is annual and signed.
+ *
+ * ## An as-if calculation, and the wording never blurs it
+ *
+ * "On the traffic you actually had, this commitment would have saved $X" is a
+ * measurement of the past.
+ *
+ * "You will save $X" is a claim about the future, and this product has refused
+ * that at every scale since 1.27. Nothing here projects, extrapolates, fits a
+ * trend or annualises a partial month. Every figure describes months that
+ * happened, and the type says so in a field a machine reader can check.
+ *
+ * ## Both directions, because one direction is the sales pitch
+ *
+ * A commitment is a **floor** as well as a discount. Below the floor you pay
+ * for capacity you did not use, and a saving quoted without that half is not
+ * an analysis — it is the vendor's slide.
+ *
+ * So every month is priced both ways, the months that would have fallen short
+ * are counted and named, and what the unused floor would have cost is its own
+ * figure rather than netted quietly against the good months.
+ *
+ * ## The shortfall risk is a count, not a probability
+ *
+ * "Three of your last twelve months would have fallen short, by $400, $150 and
+ * $2,900" is a measurement. "There is a 25% chance of shortfall" is a model of
+ * a distribution nobody fitted, presented with the authority of arithmetic.
+ * Only the first is available from a log, so only the first is printed.
+ */
+/**
+ * The fewest whole months worth replaying a commitment against.
+ *
+ * Three. Two months cannot show a shortfall pattern and one cannot show
+ * anything at all — and a commitment is signed for a year, so an answer from a
+ * single month is a year-long decision made on a fortnight of evidence.
+ */
+export const MIN_MONTHS_FOR_REPLAY = 3;
+export function replayCommitment(history, terms) {
+    const bare = (unknown, have) => ({
+        provenance: 'measured-past',
+        months: [],
+        netUsd: 0,
+        savedInGoodMonthsUsd: 0,
+        lostToUnusedFloorUsd: 0,
+        shortfallMonths: 0,
+        breakEvenMonthlyUsd: terms.monthlyFloorUsd,
+        spread: null,
+        unknown,
+        monthsNeeded: Math.max(0, MIN_MONTHS_FOR_REPLAY - have),
+    });
+    if (history.length === 0)
+        return bare('no-history', 0);
+    if (history.length < MIN_MONTHS_FOR_REPLAY)
+        return bare('too-few-months', history.length);
+    const months = history.map((entry) => {
+        const discountedUsd = entry.usd * (1 - terms.discount);
+        const shortfall = discountedUsd < terms.monthlyFloorUsd;
+        const paidUsd = shortfall ? terms.monthlyFloorUsd : discountedUsd;
+        return {
+            month: entry.month,
+            listUsd: entry.usd,
+            discountedUsd,
+            paidUsd,
+            savingUsd: entry.usd - paidUsd,
+            shortfall,
+            // What the floor bought that nobody used. Its own figure, never netted.
+            unusedFloorUsd: shortfall ? terms.monthlyFloorUsd - discountedUsd : 0,
+        };
+    });
+    const sorted = [...history].map((m) => m.usd).sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    const medianUsd = sorted.length % 2 === 0 ? ((sorted[mid - 1] ?? 0) + (sorted[mid] ?? 0)) / 2 : (sorted[mid] ?? 0);
+    return {
+        provenance: 'measured-past',
+        months,
+        netUsd: months.reduce((sum, m) => sum + m.savingUsd, 0),
+        savedInGoodMonthsUsd: months.filter((m) => !m.shortfall).reduce((sum, m) => sum + m.savingUsd, 0),
+        lostToUnusedFloorUsd: months.reduce((sum, m) => sum + m.unusedFloorUsd, 0),
+        shortfallMonths: months.filter((m) => m.shortfall).length,
+        breakEvenMonthlyUsd: terms.monthlyFloorUsd,
+        spread: { lowUsd: sorted[0] ?? 0, highUsd: sorted[sorted.length - 1] ?? 0, medianUsd },
+        unknown: null,
+        monthsNeeded: null,
+    };
+}
+/**
+ * Whether the replay covers as long as the commitment runs.
+ *
+ * Kept separate from the refusals because it does not stop the arithmetic: six
+ * months of history against a twelve-month deal is a real answer about six
+ * months, and saying so is more useful than refusing. What it must not do is
+ * go unsaid — a twelve-month decision read off half a year of evidence, with
+ * nothing on the page marking the gap, is the spreadsheet this module was
+ * written to replace.
+ */
+export function coversTheTerm(replay, terms) {
+    return {
+        covered: replay.months.length,
+        ofMonths: terms.months,
+        short: replay.months.length < terms.months,
+    };
+}
+//# sourceMappingURL=commitment.js.map

package/dist/commitment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commitment.js","sourceRoot":"","sources":["../src/commitment.ts"],"names":[],"mappings":"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"}

package/dist/conform.d.ts

@@ -25,7 +25,7 @@
  * nobody upgrades. Only *absent* required fields and *wrong* types fail.
  */
 /** The documents this project emits, and their names. */
-export type ContractName = 'usage-log' | 'profile' | 'plan' | 'verification' | 'history' | 'connected' | 'cost-answer';
+export type ContractName = 'usage-log' | 'profile' | 'plan' | 'verification' | 'history' | 'connected' | 'cost-answer' | 'outcome-report' | 'annual-record';
 export interface ConformanceProblem {
     /** Where: `line 12` for a log, or a dotted path inside a document. */
     at: string;

package/dist/conform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conform.d.ts","sourceRoot":"","sources":["../src/conform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,yDAAyD;AACzD,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,SAAS,GACT,MAAM,GACN,cAAc,GACd,SAAS,GACT,WAAW,GACX,aAAa,CAAC;AAElB,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,IAAI;IACF,kCAAkC;IAChC,SAAS;IACX,qDAAqD;OACnD,YAAY;IACd,qEAAqE;OACnE,iBAAiB;IACnB,2DAA2D;OACzD,YAAY,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,CAAC,CAAC;IACjB,gEAAgE;IAChE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAClC,+DAA+D;IAC/D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;CACnB;AA0MD,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,iBAAiB,CAgIrF"}
+{"version":3,"file":"conform.d.ts","sourceRoot":"","sources":["../src/conform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,yDAAyD;AACzD,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,SAAS,GACT,MAAM,GACN,cAAc,GACd,SAAS,GACT,WAAW,GACX,aAAa,GACb,gBAAgB,GAChB,eAAe,CAAC;AAEpB,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,IAAI;IACF,kCAAkC;IAChC,SAAS;IACX,qDAAqD;OACnD,YAAY;IACd,qEAAqE;OACnE,iBAAiB;IACnB,2DAA2D;OACzD,YAAY,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,CAAC,CAAC;IACjB,gEAAgE;IAChE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAC9B;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAClC,+DAA+D;IAC/D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;CACnB;AA+SD,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,iBAAiB,CAwIrF"}

package/dist/conform.js

@@ -182,12 +182,73 @@ const DOCUMENT_RULES = {
         rule('total', 'an object', isObject),
         rule('unavailable', 'an array of findings this source cannot support', isArray),
     ],
+    /**
+     * The outcome chapter — the standard is only worth something if its
+     * refusals travel with it.
+     *
+     * Another tool emitting this format has to handle a **missing numerator**
+     * the same way this one does: a rate that is `null` rather than `0` when
+     * nothing was recorded, a `noRate` beside it saying which of the two reasons
+     * applies, and undeclared values kept in their own list rather than folded
+     * into the failures. A format that carried the fields and lost the refusals
+     * would be worse than no format, because it would look interoperable.
+     */
+    'outcome-report': [
+        rule('slices', 'an array of declared outcome values, dearest first', isArray),
+        rule('undeclared', 'an array — named, never counted as failures', isArray),
+        rule('coverage', 'an object with recorded, parsed and unrecordedUsd', isObject),
+        rule('successShareOfRecordedUsd', 'a number, or **null** when nothing was recorded — never 0, which is a real and terrible measurement rather than an absence', 
+        // `absence-as-zero` is detected from the word "null" in the expected
+        // text, so a tool emitting 0 here is told it emitted an absence as a
+        // measurement rather than merely getting a type wrong.
+        (v) => v === null || isNumber(v)),
+        rule('noRate', 'a string saying why there is no rate, or null when there is one — a refusal never arrives bare', (v) => v === null || typeof v === 'string'),
+    ],
+    'annual-record': [
+        rule('months', 'an array, oldest first', isArray),
+        rule('missingMonths', 'an array — named, never interpolated', isArray),
+        rule('promises', 'an object with planned, arrived, notArrived and cannotTell', isObject),
+        rule('outcomes', 'an object, or null when nothing recorded one', (v) => v === null || isObject(v)),
+        rule('cannotSay', 'an array of what this record cannot answer', isArray),
+    ],
     'cost-answer': [
         rule('verdict', 'one of within, over, cannot-tell', (v) => v === 'within' || v === 'over' || v === 'cannot-tell'),
         rule('call', 'an object, or null when nothing was described', (v) => v === null || isObject(v)),
         rule('budget', 'an object, or null when there is no budget', (v) => v === null || isObject(v)),
     ],
 };
+const CROSS_RULES = {
+    'outcome-report': [
+        {
+            at: 'successShareOfRecordedUsd',
+            kind: 'absence-as-zero',
+            ok: (doc) => {
+                const coverage = doc.coverage;
+                const recorded = typeof coverage?.recorded === 'number' ? coverage.recorded : null;
+                if (recorded !== 0)
+                    return true;
+                return doc.successShareOfRecordedUsd === null;
+            },
+            detail: 'nothing was recorded, so the rate must be null — 0 is a real and terrible measurement and this is an absence',
+        },
+        {
+            at: 'noRate',
+            kind: 'missing',
+            ok: (doc) => (doc.successShareOfRecordedUsd === null ? doc.noRate !== null : doc.noRate === null),
+            detail: 'a null rate needs a reason beside it and a stated rate must not carry one — a refusal never arrives bare, and a reason attached to an answer is two answers',
+        },
+    ],
+    'annual-record': [
+        {
+            at: 'cannotSay',
+            kind: 'missing',
+            ok: (doc) => !Array.isArray(doc.missingMonths) ||
+                doc.missingMonths.length === 0 ||
+                (Array.isArray(doc.cannotSay) && doc.cannotSay.includes('months-missing')),
+            detail: 'months are missing and cannotSay does not say so — a year that quietly covers nine months and prints an annual total is wrong by a quarter',
+        },
+    ],
+};
 /**
  * Which contract a document is claiming to be.
  *
@@ -198,6 +259,10 @@ const DOCUMENT_RULES = {
 function contractOf(doc) {
     if (Array.isArray(doc.byLabelAndModel))
         return 'profile';
+    if (Array.isArray(doc.missingMonths) && isObject(doc.promises))
+        return 'annual-record';
+    if (Array.isArray(doc.undeclared) && isObject(doc.coverage))
+        return 'outcome-report';
     if (Array.isArray(doc.periods) && Array.isArray(doc.runs))
         return 'history';
     if (Array.isArray(doc.actions) && typeof doc.arrived === 'number')
@@ -329,6 +394,13 @@ export function conform(text, options = {}) {
             });
         }
     }
+    // Relational rules last, so a document with a missing field is told about the
+    // field before it is told about a relationship that field is half of.
+    for (const cross of CROSS_RULES[contract] ?? []) {
+        if (!cross.ok(doc)) {
+            problems.push({ at: cross.at, kind: cross.kind, detail: cross.detail });
+        }
+    }
     return {
         schemaVersion: 1,
         contract,