@trazum/core 1.47.0 → 1.49.0

package/dist/waivers.d.ts

@@ -0,0 +1,133 @@
+/**
+ * What a team has decided to live with, and how long they have been deciding it.
+ *
+ * 1.40 named this gap and could not fill it: *no document stores past waivers,
+ * and a history invented from the current config would be a guess presented as
+ * a record*. That was the right refusal — a config says what is waived **now**,
+ * and nothing in it says whether the same finding was waived last quarter under
+ * a different reason, or whether the expiry has been pushed forward four times
+ * by four people who each assumed somebody else had looked.
+ *
+ * It is fixable by **recording**, not by inferring. A waiver silences a gate;
+ * the moment it does, that use is a fact with a date on it, and this module
+ * reads those facts back.
+ *
+ * Three rules hold the whole thing up:
+ *
+ * **Nothing is back-filled.** The history starts the day the recording did,
+ * and `since` says which day that was. Reconstructing a past from the present
+ * config is exactly what 1.40 refused, and it would be worse here than
+ * nowhere: a fabricated "waived four times" is an accusation.
+ *
+ * **A use is recorded when the waiver silences something, not when it is
+ * written.** A waiver nobody's build has ever hit is not a habit — it is dead
+ * config, and the report says which it is rather than folding the two together.
+ *
+ * **The verdict describes the record, never the team.** "Renewed without being
+ * revisited" is a statement about dates and reasons in a file. Whether that was
+ * the right call is a conversation this tool does not get to have.
+ */
+import type { WaiveEntry } from './config-schema.js';
+/** One occasion on which a waiver silenced a gate. */
+export interface WaiverUse {
+    schemaVersion: 1;
+    /** The UTC day it happened, `YYYY-MM-DD`. */
+    day: string;
+    /** The gate silenced — a `WAIVABLE_GATES` entry or `byLabel:<label>`. */
+    gate: string;
+    /** The reason the config gave **at that moment**, not today's. */
+    reason: string;
+    /** The expiry the waiver carried at that moment. */
+    until: string;
+    /**
+     * The commit that carried it, when the run could see one.
+     *
+     * Null is common and honest: a waiver used outside a repository, or in a CI
+     * job that did not export the SHA. Null never becomes "unknown commit" in a
+     * count — a use with no commit is still a use.
+     */
+    commit: string | null;
+    /** What the gate measured, so a recorded use is checkable rather than asserted. */
+    measuredUsd: number | null;
+    limitUsd: number | null;
+}
+export type WaiverVerdict = 
+/** One recorded use. Nothing to say about it yet. */
+'used-once'
+/** Used repeatedly under one unchanging reason and one unchanging expiry. */
+ | 'recurring'
+/**
+ * The expiry moved while the reason stayed the same.
+ *
+ * The shape a decision takes when nobody is revisiting it: the same sentence
+ * carried forward past its own deadline. Named, and never called wrong —
+ * plenty of real constraints outlive their first estimate.
+ */
+ | 'renewed-without-revisiting'
+/**
+ * The reason changed between uses.
+ *
+ * Somebody looked. Worth telling apart from the case above, because it is
+ * the opposite behaviour and would otherwise be counted as the same habit.
+ */
+ | 'reason-changed';
+export interface WaiverHabit {
+    gate: string;
+    /** How many recorded uses, never an estimate. */
+    uses: number;
+    firstDay: string;
+    lastDay: string;
+    /** Distinct days it fired on — a gate hit twice on one day is one day. */
+    days: number;
+    /** Every distinct reason given, oldest first. */
+    reasons: string[];
+    /** Every distinct expiry carried, oldest first. More than one means it moved. */
+    expiries: string[];
+    verdict: WaiverVerdict;
+    /** Whether this gate is still waived in the config as it stands today. */
+    stillConfigured: boolean;
+}
+export interface WaiverHistory {
+    schemaVersion: 1;
+    /**
+     * The first day any use was recorded, or null when none has been.
+     *
+     * Rendered as "the history starts here", because a reader looking at two
+     * uses needs to know whether that is two in the project's life or two since
+     * Tuesday.
+     */
+    since: string | null;
+    /** Most-used first — the order somebody would read in. */
+    habits: WaiverHabit[];
+    /**
+     * Waivers in the config today that no recorded run has ever hit.
+     *
+     * Dead config, not habit. Either the gate stopped failing — which is good
+     * news nobody wrote down — or the waiver names a situation that never
+     * arises. Both are worth deleting; neither is a team living with a finding.
+     */
+    neverUsed: string[];
+    /** Total recorded uses across every gate. */
+    totalUses: number;
+}
+/** `YYYY-MM-DD` for a moment, UTC — the same day boundary the store uses. */
+export declare function waiverDay(at: Date): string;
+/**
+ * Whether a value is a use record this module can read.
+ *
+ * Same posture as the plan validator: a line that is not a record is skipped
+ * and counted by the caller, never coerced into one. A malformed line in an
+ * append-only file is a fact about the file, and a reader that silently
+ * repairs it produces a history that is wrong by an unknown amount.
+ */
+export declare function isWaiverUse(value: unknown): value is WaiverUse;
+/**
+ * The habits, from the record and the config as it stands.
+ *
+ * `configured` is used for exactly one thing — telling a gate somebody is
+ * still waiving from one they stopped — and never to invent a use. A waiver in
+ * the config with no recorded use appears in `neverUsed`, with a count of
+ * nothing, which is the honest shape.
+ */
+export declare function waiverHistory(uses: readonly WaiverUse[], configured?: readonly WaiveEntry[]): WaiverHistory;
+//# sourceMappingURL=waivers.d.ts.map

package/dist/waivers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"waivers.d.ts","sourceRoot":"","sources":["../src/waivers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,sDAAsD;AACtD,MAAM,WAAW,SAAS;IACxB,aAAa,EAAE,CAAC,CAAC;IACjB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,mFAAmF;IACnF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,MAAM,aAAa;AACvB,qDAAqD;AACnD,WAAW;AACb,6EAA6E;GAC3E,WAAW;AACb;;;;;;GAMG;GACD,4BAA4B;AAC9B;;;;;GAKG;GACD,gBAAgB,CAAC;AAErB,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iFAAiF;IACjF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,aAAa,CAAC;IACvB,0EAA0E;IAC1E,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,CAAC,CAAC;IACjB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,0DAA0D;IAC1D,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,EAAE,EAAE,IAAI,GAAG,MAAM,CAE1C;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAU9D;AAQD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,SAAS,EAAE,EAC1B,UAAU,GAAE,SAAS,UAAU,EAAO,GACrC,aAAa,CAgDf"}

package/dist/waivers.js

@@ -0,0 +1,114 @@
+/**
+ * What a team has decided to live with, and how long they have been deciding it.
+ *
+ * 1.40 named this gap and could not fill it: *no document stores past waivers,
+ * and a history invented from the current config would be a guess presented as
+ * a record*. That was the right refusal — a config says what is waived **now**,
+ * and nothing in it says whether the same finding was waived last quarter under
+ * a different reason, or whether the expiry has been pushed forward four times
+ * by four people who each assumed somebody else had looked.
+ *
+ * It is fixable by **recording**, not by inferring. A waiver silences a gate;
+ * the moment it does, that use is a fact with a date on it, and this module
+ * reads those facts back.
+ *
+ * Three rules hold the whole thing up:
+ *
+ * **Nothing is back-filled.** The history starts the day the recording did,
+ * and `since` says which day that was. Reconstructing a past from the present
+ * config is exactly what 1.40 refused, and it would be worse here than
+ * nowhere: a fabricated "waived four times" is an accusation.
+ *
+ * **A use is recorded when the waiver silences something, not when it is
+ * written.** A waiver nobody's build has ever hit is not a habit — it is dead
+ * config, and the report says which it is rather than folding the two together.
+ *
+ * **The verdict describes the record, never the team.** "Renewed without being
+ * revisited" is a statement about dates and reasons in a file. Whether that was
+ * the right call is a conversation this tool does not get to have.
+ */
+/** `YYYY-MM-DD` for a moment, UTC — the same day boundary the store uses. */
+export function waiverDay(at) {
+    return at.toISOString().slice(0, 10);
+}
+/**
+ * Whether a value is a use record this module can read.
+ *
+ * Same posture as the plan validator: a line that is not a record is skipped
+ * and counted by the caller, never coerced into one. A malformed line in an
+ * append-only file is a fact about the file, and a reader that silently
+ * repairs it produces a history that is wrong by an unknown amount.
+ */
+export function isWaiverUse(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    return (record.schemaVersion === 1 &&
+        typeof record.day === 'string' &&
+        typeof record.gate === 'string' &&
+        typeof record.reason === 'string' &&
+        typeof record.until === 'string');
+}
+function verdictFor(reasons, expiries, uses) {
+    if (uses <= 1)
+        return 'used-once';
+    if (reasons.length > 1)
+        return 'reason-changed';
+    return expiries.length > 1 ? 'renewed-without-revisiting' : 'recurring';
+}
+/**
+ * The habits, from the record and the config as it stands.
+ *
+ * `configured` is used for exactly one thing — telling a gate somebody is
+ * still waiving from one they stopped — and never to invent a use. A waiver in
+ * the config with no recorded use appears in `neverUsed`, with a count of
+ * nothing, which is the honest shape.
+ */
+export function waiverHistory(uses, configured = []) {
+    const byGate = new Map();
+    for (const use of uses) {
+        const list = byGate.get(use.gate);
+        if (list === undefined)
+            byGate.set(use.gate, [use]);
+        else
+            list.push(use);
+    }
+    const configuredGates = new Set(configured.map((entry) => entry.gate));
+    const habits = [];
+    for (const [gate, list] of byGate) {
+        const sorted = [...list].sort((a, b) => a.day.localeCompare(b.day));
+        // Distinct values in the order they were first seen, so "the reason
+        // changed" reads chronologically rather than alphabetically.
+        const reasons = [...new Set(sorted.map((u) => u.reason))];
+        const expiries = [...new Set(sorted.map((u) => u.until))];
+        const days = new Set(sorted.map((u) => u.day)).size;
+        const first = sorted[0];
+        const last = sorted[sorted.length - 1];
+        if (first === undefined || last === undefined)
+            continue;
+        habits.push({
+            gate,
+            uses: sorted.length,
+            firstDay: first.day,
+            lastDay: last.day,
+            days,
+            reasons,
+            expiries,
+            verdict: verdictFor(reasons, expiries, sorted.length),
+            stillConfigured: configuredGates.has(gate),
+        });
+    }
+    habits.sort((a, b) => b.uses - a.uses || a.gate.localeCompare(b.gate));
+    const allDays = uses.map((use) => use.day).sort((a, b) => a.localeCompare(b));
+    return {
+        schemaVersion: 1,
+        since: allDays[0] ?? null,
+        habits,
+        neverUsed: configured
+            .filter((entry) => !byGate.has(entry.gate))
+            .map((entry) => entry.gate)
+            .sort(),
+        totalUses: uses.length,
+    };
+}
+//# sourceMappingURL=waivers.js.map

package/dist/waivers.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/core",
-  "version": "1.47.0",
+  "version": "1.49.0",
   "description": "Trazum core: priced advisories for LLM prompts (caching, model tier, batching, schemas), plus deterministic trimming, token counting and pricing.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",

package/src/budget.ts

@@ -0,0 +1,321 @@
+/**
+ * One measured number, wherever it is asked for.
+ *
+ * By 1.48 there are four ways to ask Trazum about money — a gate in CI, the
+ * terminal, the local endpoint an agent consults, the browser — and no
+ * guarantee any two of them agree about how much of a budget is left. Each
+ * computed its own answer from whatever it happened to be holding: a log, a
+ * store, a request body. Four right answers to four slightly different
+ * questions is how a CI failure and an agent's refusal come to disagree in
+ * front of somebody.
+ *
+ * This is that number. A budget becomes a **position**: a limit, a period, the
+ * measured spend inside it, and — the part that makes it honest — how much of
+ * that period was measured at all.
+ *
+ * **Nothing here forecasts.** "Sixty-one per cent of the budget, consumed over
+ * eleven of thirty days" is a measurement. "You will run out on the 24th" is a
+ * prediction, and this product has refused those since 1.27 at every scale it
+ * operates on. The burn-down below compares two shares that both already
+ * happened, and names the shape; it never produces a date.
+ *
+ * **A period nobody measured is not a period under budget.** The rule
+ * `fleetBudgetMissing` established for services in 1.37, applied to time: days
+ * inside the period with no measurement are counted and named, and a position
+ * standing on three measured days out of thirty says so rather than reporting
+ * a comfortable ninety per cent remaining.
+ */
+
+import type { SpendConfig } from './config-schema.js';
+import type { StoreRecord } from './store.js';
+import { effectivePricing } from './pricing.js';
+import type { PricingCatalogue } from './pricing.js';
+
+const DAY_MS = 86_400_000;
+
+/** The window a budget is spent over. Calendar months, UTC, like everything else. */
+export interface BudgetPeriod {
+  kind: 'month';
+  /** `YYYY-MM`, UTC. */
+  id: string;
+  fromMs: number;
+  /** Half-open: the first instant of the next month. */
+  toMs: number;
+  days: number;
+}
+
+export type BudgetScope =
+  | { kind: 'total' }
+  | { kind: 'label'; label: string }
+  | { kind: 'source'; source: string };
+
+/**
+ * How much of the period the measurement actually covers.
+ *
+ * Three values rather than a percentage, because the three lead to different
+ * decisions: act on it, act on it knowing it is a floor, or go and find out
+ * why nothing was measured.
+ */
+export type BudgetCoverage = 'complete' | 'partial' | 'none';
+
+/**
+ * The shape of the burn, named — never a date.
+ *
+ * A comparison of two shares that have both already happened: how much of the
+ * budget is gone against how much of the period is gone. `ahead` means the
+ * money is going faster than the calendar, which is a fact about the past
+ * eleven days and not a claim about the next nineteen.
+ */
+export type BurnShape = 'ahead' | 'on-pace' | 'behind' | 'cannot-tell';
+
+export interface BurnDown {
+  /** Share of the limit consumed, 0-1. Null when the limit is zero. */
+  consumedShare: number | null;
+  /** Share of the period elapsed at the instant this was computed, 0-1. */
+  elapsedShare: number;
+  shape: BurnShape;
+  /**
+   * Deliberately absent: any field naming a date the budget runs out.
+   *
+   * Stated here rather than left to be noticed, because it is the single most
+   * requested number this module will ever be asked for, and every future
+   * reader of this file will be tempted to add it. It cannot be measured; it
+   * can only be projected from a rate that the log has no reason to keep.
+   */
+  readonly forecast?: never;
+}
+
+export interface BudgetStanding {
+  schemaVersion: 1;
+  scope: BudgetScope;
+  limitUsd: number;
+  period: BudgetPeriod;
+  /** Measured spend inside the period. Never an estimate — see `provenance`. */
+  consumedUsd: number;
+  remainingUsd: number;
+  provenance: 'measured';
+  /** Distinct UTC days inside the period that carry any measurement. */
+  measuredDays: number;
+  /** Days of the period that have already elapsed at the instant asked. */
+  elapsedDays: number;
+  /**
+   * Elapsed days with no measurement at all, oldest first, capped for
+   * rendering. A day missing from a series is the thing a total cannot show.
+   */
+  unmeasuredDays: string[];
+  coverage: BudgetCoverage;
+  burn: BurnDown;
+  /**
+   * `cannot-tell` when nothing in the period was measured. A budget with no
+   * measurement behind it is not a budget under control, and reporting
+   * `within` would be the flattering direction — the one this repository
+   * refuses everywhere it can occur.
+   */
+  verdict: 'within' | 'over' | 'cannot-tell';
+}
+
+export interface BudgetReport {
+  schemaVersion: 1;
+  period: BudgetPeriod;
+  positions: BudgetStanding[];
+  /**
+   * Budgets configured with a scope nothing measured touches.
+   *
+   * Not a position of zero: a label that has no records may have been renamed,
+   * or may simply not have run. Both are worth knowing and neither is "under
+   * budget".
+   */
+  unmeasuredScopes: BudgetScope[];
+}
+
+/** The UTC month containing `at`, as a period. */
+export function monthOf(at: Date): BudgetPeriod {
+  const year = at.getUTCFullYear();
+  const month = at.getUTCMonth();
+  const fromMs = Date.UTC(year, month, 1);
+  const toMs = Date.UTC(year, month + 1, 1);
+  return {
+    kind: 'month',
+    id: `${year}-${String(month + 1).padStart(2, '0')}`,
+    fromMs,
+    toMs,
+    days: Math.round((toMs - fromMs) / DAY_MS),
+  };
+}
+
+/** What a store record's tokens cost, at the catalogue's rates for its window. */
+function priceOf(record: StoreRecord, catalogue: PricingCatalogue): number | null {
+  const model = catalogue.byId.get(record.model);
+  if (model === undefined) return null;
+  const rates = effectivePricing(model, new Date(record.fromMs));
+  const write5m = record.write5m * rates.inputPerMTok * 1.25;
+  const write1h = record.write1h * rates.inputPerMTok * 2;
+  return (
+    (record.input * rates.inputPerMTok +
+      record.cacheRead * rates.inputPerMTok * 0.1 +
+      write5m +
+      write1h +
+      record.output * rates.outputPerMTok) /
+    1_000_000
+  );
+}
+
+/**
+ * The share of a record's window that falls inside the period.
+ *
+ * A store record covers a bucket, and a bucket can straddle a month boundary.
+ * Counting it wholly in or wholly out would move real money between months by
+ * up to a day; apportioning by overlap is the only answer that keeps two
+ * adjacent months summing to the same total as the pair.
+ *
+ * This is arithmetic about a window, not an estimate of anything: the record
+ * says what the window cost, and the overlap is exact.
+ */
+function overlapShare(record: StoreRecord, period: BudgetPeriod): number {
+  const span = record.toMs - record.fromMs;
+  if (span <= 0) return record.fromMs >= period.fromMs && record.fromMs < period.toMs ? 1 : 0;
+  const from = Math.max(record.fromMs, period.fromMs);
+  const to = Math.min(record.toMs, period.toMs);
+  return to <= from ? 0 : (to - from) / span;
+}
+
+/** Every UTC day a record touches inside the period, as `YYYY-MM-DD`. */
+function daysTouched(record: StoreRecord, period: BudgetPeriod): string[] {
+  const from = Math.max(record.fromMs, period.fromMs);
+  const to = Math.min(Math.max(record.toMs, record.fromMs + 1), period.toMs);
+  if (to <= from) return [];
+  const days: string[] = [];
+  for (let ms = Math.floor(from / DAY_MS) * DAY_MS; ms < to; ms += DAY_MS) {
+    days.push(new Date(ms).toISOString().slice(0, 10));
+  }
+  return days;
+}
+
+function shapeOf(consumedShare: number | null, elapsedShare: number, coverage: BudgetCoverage): BurnShape {
+  // Nothing measured, or nothing to measure against: the comparison has no
+  // meaning, and inventing one from an elapsed share alone would be a shape
+  // drawn from the calendar rather than from the bill.
+  if (coverage === 'none' || consumedShare === null) return 'cannot-tell';
+
+  // A five-point band, so a budget tracking the calendar to within a rounding
+  // error is not reported as drifting every time somebody looks.
+  const drift = consumedShare - elapsedShare;
+  const ahead = drift > 0.05;
+
+  /**
+   * **A floor can prove `ahead` and can never prove `behind`.**
+   *
+   * Partial coverage means the consumed figure is a floor on the period: the
+   * unmeasured days spent *something*, and nobody knows how much. A floor that
+   * has already outrun the calendar is unarguably ahead — the real figure is
+   * higher still. A floor that looks comfortable proves nothing at all, and
+   * reporting it as `behind` would turn missing measurement into good news,
+   * which is the flattering direction this repository refuses everywhere.
+   *
+   * The first version of this returned `behind` for three measured days out of
+   * twenty, beside a warning that the figure was a floor. Two sentences that
+   * contradicted each other, and the reassuring one came second.
+   */
+  if (coverage === 'partial') return ahead ? 'ahead' : 'cannot-tell';
+
+  if (ahead) return 'ahead';
+  if (drift < -0.05) return 'behind';
+  return 'on-pace';
+}
+
+/** How many unmeasured days are worth naming before the list becomes noise. */
+export const MAX_UNMEASURED_NAMED = 10;
+
+export interface BudgetOptions {
+  catalogue: PricingCatalogue;
+  /** The instant the position is taken. Every share below is as of this moment. */
+  now?: Date;
+  /** Which period. Defaults to the month containing `now`. */
+  period?: BudgetPeriod;
+}
+
+/**
+ * The live position of every configured budget, from measured records alone.
+ *
+ * Per-label and per-source budgets are **not** computed here, and their
+ * absence is the honest answer rather than an omission: a store record carries
+ * a provider, a model and the account's own grouping, and it does not carry a
+ * workload label — labels live in a per-call usage log, which a bucketed
+ * provider API does not serve. Reporting a per-label position from records
+ * that cannot distinguish labels would be a number assembled from the wrong
+ * denominator. They appear in `unmeasuredScopes` instead, which says what is
+ * true: nothing measured here can answer for them.
+ */
+export function budgetPositions(
+  records: readonly StoreRecord[],
+  spend: SpendConfig | undefined,
+  options: BudgetOptions,
+): BudgetReport {
+  const { catalogue, now = new Date() } = options;
+  const period = options.period ?? monthOf(now);
+
+  const positions: BudgetStanding[] = [];
+  const unmeasuredScopes: BudgetScope[] = [];
+
+  const elapsedMs = Math.min(Math.max(0, now.getTime() - period.fromMs), period.toMs - period.fromMs);
+  const elapsedDays = Math.max(1, Math.ceil(elapsedMs / DAY_MS));
+  const elapsedShare = elapsedMs / (period.toMs - period.fromMs);
+
+  /**
+   * `monthlyUsd`, never `maxUsd`. The two are the same units over different
+   * denominators — one gates whatever period a log happens to cover, this
+   * gates a calendar month — and reading one for the other is exactly the
+   * disagreement this module exists to end.
+   */
+  if (spend?.monthlyUsd !== undefined) {
+    let consumedUsd = 0;
+    const measured = new Set<string>();
+    for (const record of records) {
+      const share = overlapShare(record, period);
+      if (share === 0) continue;
+      const usd = priceOf(record, catalogue);
+      // An unpriced model contributes no dollars **and no measured day**:
+      // counting the day would report the period as covered by money nobody
+      // can see, which is the same flattering omission in a different place.
+      if (usd === null) continue;
+      consumedUsd += usd * share;
+      for (const day of daysTouched(record, period)) measured.add(day);
+    }
+
+    const unmeasured: string[] = [];
+    for (let d = 0; d < elapsedDays; d += 1) {
+      const day = new Date(period.fromMs + d * DAY_MS).toISOString().slice(0, 10);
+      if (!measured.has(day)) unmeasured.push(day);
+    }
+
+    const coverage: BudgetCoverage =
+      measured.size === 0 ? 'none' : unmeasured.length === 0 ? 'complete' : 'partial';
+    const limitUsd = spend.monthlyUsd;
+    const consumedShare = limitUsd > 0 ? consumedUsd / limitUsd : null;
+
+    positions.push({
+      schemaVersion: 1,
+      scope: { kind: 'total' },
+      limitUsd,
+      period,
+      consumedUsd,
+      remainingUsd: limitUsd - consumedUsd,
+      provenance: 'measured',
+      measuredDays: measured.size,
+      elapsedDays,
+      unmeasuredDays: unmeasured.slice(0, MAX_UNMEASURED_NAMED),
+      coverage,
+      burn: { consumedShare, elapsedShare, shape: shapeOf(consumedShare, elapsedShare, coverage) },
+      verdict: coverage === 'none' ? 'cannot-tell' : consumedUsd > limitUsd ? 'over' : 'within',
+    });
+  }
+
+  for (const label of Object.keys(spend?.byLabel ?? {})) {
+    unmeasuredScopes.push({ kind: 'label', label });
+  }
+  for (const source of Object.keys(spend?.bySource ?? {})) {
+    unmeasuredScopes.push({ kind: 'source', source });
+  }
+
+  return { schemaVersion: 1, period, positions, unmeasuredScopes };
+}

package/src/config-schema.ts

@@ -68,6 +68,23 @@ export interface WaiveEntry {
 export interface SpendConfig {
   /** Whole-log budget. `--max-usd` overrides it. */
   maxUsd?: number;
+  /**
+   * The calendar-month budget, spent against **measured** store records.
+   *
+   * A separate key from `maxUsd` on purpose, and the reason is worth stating
+   * because reusing one would have been so much less code. `maxUsd` gates
+   * *this log* — whatever period the file somebody passed happens to cover.
+   * This gates *this month*. Same units, different denominators, and one key
+   * carrying both is precisely how two surfaces of the same product come to
+   * disagree about how much is left: `serve` read `maxUsd` and compared it
+   * against the whole store, which could be a year, and reported the result as
+   * a budget position with a straight face.
+   *
+   * Nothing infers one from the other. A repository with a per-log gate and no
+   * monthly budget has no monthly position, and the tools say so rather than
+   * picking a number that is the right shape.
+   */
+  monthlyUsd?: number;
   /**
    * Per-day budget — the gate a whole-log total cannot arm. `--max-day-usd`
    * overrides it, and it inherits that flag's refusals: a log with no clock
@@ -217,7 +234,7 @@ export const CONFIG_KEYS = [
 
 export const CONFIG_BASELINE_KEYS = ['path', 'maxGrowthTokens', 'maxGrowthPct'] as const;
 
-export const CONFIG_SPEND_KEYS = ['maxUsd', 'maxDayUsd', 'maxSessionUsd', 'maxCacheLossUsd', 'byLabel', 'bySource'] as const;
+export const CONFIG_SPEND_KEYS = ['maxUsd', 'monthlyUsd', 'maxDayUsd', 'maxSessionUsd', 'maxCacheLossUsd', 'byLabel', 'bySource'] as const;
 
 export const CONFIG_WAIVE_KEYS = ['gate', 'reason', 'until'] as const;
 
@@ -420,6 +437,9 @@ function parseSpend(raw: unknown, source: string): SpendConfig {
   if (raw.maxUsd !== undefined) {
     spend.maxUsd = requireNonNegativeNumber(raw.maxUsd, 'spend.maxUsd', source);
   }
+  if (raw.monthlyUsd !== undefined) {
+    spend.monthlyUsd = requireNonNegativeNumber(raw.monthlyUsd, 'spend.monthlyUsd', source);
+  }
   if (raw.maxCacheLossUsd !== undefined) {
     spend.maxCacheLossUsd = requireNonNegativeNumber(raw.maxCacheLossUsd, 'spend.maxCacheLossUsd', source);
   }

package/src/index.ts

@@ -49,6 +49,19 @@ export type { PlanParseFailure, PlanParseResult } from './plan.js';
 export type { PlanAction, PlanActionKind, PlanAssumption, PlanDocument } from './plan.js';
 export { verifyPlan } from './verify.js';
 export { buildHistory, storedReportFrom, MIN_RUN } from './history.js';
+export { budgetPositions, monthOf, MAX_UNMEASURED_NAMED } from './budget.js';
+export type {
+  BudgetCoverage,
+  BudgetOptions,
+  BudgetPeriod,
+  BudgetStanding,
+  BudgetReport,
+  BudgetScope,
+  BurnDown,
+  BurnShape,
+} from './budget.js';
+export { waiverHistory, waiverDay, isWaiverUse } from './waivers.js';
+export type { WaiverHabit, WaiverHistory, WaiverUse, WaiverVerdict } from './waivers.js';
 export { answerCost } from './answer.js';
 export { guardSpend } from './guard.js';
 export type { GuardAlternative, GuardAnswer, GuardRequest, GuardVerdict } from './guard.js';