@trazum/core 1.41.0 → 1.43.0

package/dist/store.js

@@ -0,0 +1,177 @@
+/**
+ * A year of measured spend on disk, and not one prompt inside it.
+ *
+ * A connector that re-downloads a month every time it runs is a connector
+ * nobody leaves on, and `history` needs stored reports — which until now meant
+ * a human curating a directory of `--json` files. The store is where pulled
+ * usage lands so neither is true any more.
+ *
+ * **Pure, and in the core.** This module decides what a record *is*, when two
+ * records are the same record, and what a set of them adds up to. The
+ * filesystem lives in the CLI, the same split every other browser-safe module
+ * here keeps.
+ *
+ * **Convergence, not accumulation.** Re-pulling an overlapping window must not
+ * double the bill. Two records covering the same window, from the same
+ * provider, for the same model and grouping, are the *same fact restated* —
+ * the later pull wins, because a window pulled again is at worst as complete
+ * as it was. That makes overlapping pulls idempotent, which is what lets a
+ * scheduled job run every hour over a rolling day without inventing money.
+ *
+ * **Deduplication that cannot lie.** Two records the store cannot tell apart —
+ * a source that served no window, or no model — are kept as *two* and reported
+ * as possibly-double. Merging them on a guess makes a bill quietly smaller,
+ * and quietly smaller is the flattering direction this repository refuses
+ * everywhere it can occur.
+ */
+/** Bump when the meaning of a field changes. Readers keep what they cannot read. */
+export const STORE_SCHEMA_VERSION = 1;
+/** What makes two records the same record. See the module note. */
+export function identityOf(record) {
+    return [
+        record.provider,
+        record.fromMs,
+        record.toMs,
+        record.model,
+        JSON.stringify(record.group),
+    ].join('\n');
+}
+/**
+ * A record whose identity is not trustworthy enough to converge on.
+ *
+ * A window of zero length, or a record with no model, cannot be told apart
+ * from another like it. Those are kept whole and counted separately.
+ */
+function identifiable(record) {
+    return record.model !== '' && record.toMs > record.fromMs;
+}
+/**
+ * Collapses an append-only log into the current truth.
+ *
+ * Append-only on disk and last-wins at read time, rather than rewriting a file
+ * in place: a crash during a rewrite can lose a year, and a crash during an
+ * append loses the tail of one line.
+ */
+export function resolveStore(records) {
+    const byIdentity = new Map();
+    const possiblyDouble = [];
+    let unknownVersion = 0;
+    for (const record of records) {
+        if (record.v > STORE_SCHEMA_VERSION) {
+            unknownVersion += 1;
+            continue;
+        }
+        if (!identifiable(record)) {
+            possiblyDouble.push(record);
+            continue;
+        }
+        const key = identityOf(record);
+        const seen = byIdentity.get(key);
+        if (seen === undefined || record.pulledAtMs >= seen.pulledAtMs) {
+            byIdentity.set(key, record);
+        }
+    }
+    return {
+        records: [...byIdentity.values()].sort((a, b) => a.fromMs - b.fromMs || a.model.localeCompare(b.model)),
+        possiblyDouble,
+        unknownVersion,
+    };
+}
+/** Turns a connector's buckets into records ready to append. */
+export function recordsFromBuckets(provider, buckets, pulledAtMs) {
+    return buckets.map((bucket) => ({
+        v: STORE_SCHEMA_VERSION,
+        provider,
+        fromMs: bucket.fromMs,
+        toMs: bucket.toMs,
+        model: bucket.model,
+        calls: bucket.calls,
+        input: bucket.inputTokens,
+        cacheRead: bucket.cacheReadTokens,
+        write5m: bucket.cacheWrite5mTokens,
+        write1h: bucket.cacheWrite1hTokens,
+        ttlKnown: bucket.writeTtlKnown,
+        output: bucket.outputTokens,
+        group: bucket.group,
+        pulledAtMs,
+    }));
+}
+/** The reverse, so a stored month prices exactly as a fresh pull does. */
+export function bucketsFromRecords(records) {
+    return records.map((record) => ({
+        fromMs: record.fromMs,
+        toMs: record.toMs,
+        model: record.model,
+        calls: record.calls,
+        inputTokens: record.input,
+        cacheReadTokens: record.cacheRead,
+        cacheWrite5mTokens: record.write5m,
+        cacheWrite1hTokens: record.write1h,
+        writeTtlKnown: record.ttlKnown,
+        outputTokens: record.output,
+        group: record.group,
+    }));
+}
+export function storeInventory(resolved) {
+    const byProvider = new Map();
+    for (const record of resolved.records) {
+        const list = byProvider.get(record.provider) ?? [];
+        list.push(record);
+        byProvider.set(record.provider, list);
+    }
+    const providers = [...byProvider.entries()]
+        .map(([provider, records]) => {
+        const anyUnknown = records.some((r) => r.calls === null);
+        return {
+            provider,
+            records: records.length,
+            span: {
+                fromMs: Math.min(...records.map((r) => r.fromMs)),
+                toMs: Math.max(...records.map((r) => r.toMs)),
+            },
+            calls: anyUnknown ? null : records.reduce((sum, r) => sum + (r.calls ?? 0), 0),
+            models: [...new Set(records.map((r) => r.model))].sort(),
+        };
+    })
+        .sort((a, b) => a.provider.localeCompare(b.provider));
+    const all = resolved.records;
+    return {
+        schemaVersion: 1,
+        providers,
+        totalRecords: all.length,
+        span: all.length === 0
+            ? null
+            : {
+                fromMs: Math.min(...all.map((r) => r.fromMs)),
+                toMs: Math.max(...all.map((r) => r.toMs)),
+            },
+        possiblyDouble: resolved.possiblyDouble.length,
+        unknownVersion: resolved.unknownVersion,
+    };
+}
+/**
+ * Drops records whose window ended before the cutoff.
+ *
+ * Judged on `toMs`: a bucket that *ends* inside the retained period is
+ * retained whole, because half a bucket is a measurement of nothing. What goes
+ * is returned rather than counted, so the caller can say what went — silence
+ * about deleted measurements is the one thing a store must not do.
+ */
+export function pruneRecords(records, cutoffMs) {
+    const kept = [];
+    const dropped = [];
+    for (const record of records) {
+        (record.toMs < cutoffMs ? dropped : kept).push(record);
+    }
+    return {
+        kept,
+        dropped,
+        droppedSpan: dropped.length === 0
+            ? null
+            : {
+                fromMs: Math.min(...dropped.map((r) => r.fromMs)),
+                toMs: Math.max(...dropped.map((r) => r.toMs)),
+            },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

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

package/dist/watch.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The afternoon the loop burned a quarter of the month, said that afternoon.
+ *
+ * Every gate in this product fires when a human runs a command. The failures
+ * worth catching — a retry loop, a prompt that grew, a model swapped in a
+ * deploy — happen at 3pm on a Tuesday, and a report that arrives three weeks
+ * later is an obituary.
+ *
+ * This module decides **what has crossed**, given what is measured and what
+ * the operator asked to be told about. The pulling, the storing, the sleeping
+ * and the sending live in the CLI; everything here is arithmetic over figures
+ * somebody already has, which is what makes an alerting rule testable without
+ * waiting for 3pm.
+ *
+ * **An alert fires on a measured crossing, never on a projection.** "You will
+ * exceed" is a forecast, and this product has refused those at every window
+ * length since 1.27. "You have spent $412 of a $400 budget, measured over
+ * these calls" is a fact, and the difference is the only reason an alert at
+ * 3am can be trusted.
+ *
+ * **A window too short to mean anything does not fire.** A day gate needs a
+ * whole day of measurement before it can fail: the first ten minutes of a day
+ * are not a day, and a watcher that cries at every dawn gets muted — which is
+ * how alerting tools actually fail.
+ */
+import type { BucketedReport } from './connector.js';
+export type WatchGate = 'maxUsd' | 'maxDayUsd' | 'maxCacheLossUsd';
+/** Why a gate could not be judged rather than passed. */
+export type NotJudgeable = 
+/** Not enough of the period is measured for the threshold to mean anything. */
+'window-too-short'
+/** The source cannot serve the dimension this gate is written against. */
+ | 'dimension-unavailable';
+export interface WatchCrossing {
+    gate: WatchGate;
+    /** The measured figure that crossed, and the threshold it crossed. */
+    measuredUsd: number;
+    limitUsd: number;
+    /** Which slice of time the figure covers — a day gate names its day. */
+    window: {
+        fromMs: number;
+        toMs: number;
+    };
+    /** A day gate's UTC day, so the alert names the afternoon it means. */
+    day: string | null;
+    /**
+     * Everything a machine reader needs to know what kind of number this is.
+     *
+     * `measured` is the only value this module will ever emit: a projected
+     * crossing is not a crossing. The field exists anyway, because a consumer
+     * that cannot see the provenance will treat whatever arrives as fact — and
+     * a later version of this file must not be able to smuggle an estimate past
+     * a reader by leaving the question unasked.
+     */
+    provenance: 'measured';
+}
+export interface WatchAbstention {
+    gate: WatchGate;
+    reason: NotJudgeable;
+    /** What is missing, as a figure the operator can act on. */
+    detail: {
+        coveredMs: number;
+        neededMs: number;
+    } | null;
+}
+export interface WatchResult {
+    crossings: WatchCrossing[];
+    /**
+     * Still over the limit, and already reported on an earlier cycle.
+     *
+     * These are the reason a quiet cycle is not the same as a clean one. A
+     * restart that reported "within every threshold" while the budget was still
+     * blown would be the flattering reading this product refuses everywhere:
+     * the alert was suppressed, the *crossing* was not, and only one of those
+     * is news.
+     */
+    suppressed: WatchCrossing[];
+    /**
+     * Gates that could not be judged, which is neither a pass nor a failure.
+     *
+     * Reported rather than swallowed: a gate silently skipped for a week reads
+     * exactly like a gate that has been passing for a week, and those are very
+     * different states to be in.
+     */
+    abstentions: WatchAbstention[];
+    /**
+     * The stretch this cycle did not watch, when a watcher was down or is
+     * starting for the first time. A resumed watcher that says nothing implies
+     * coverage it did not have.
+     */
+    gap: {
+        fromMs: number;
+        toMs: number;
+    } | null;
+}
+export interface WatchThresholds {
+    maxUsd?: number;
+    maxDayUsd?: number;
+    maxCacheLossUsd?: number;
+}
+export interface WatchOptions {
+    /** Priced measurements for the period being watched. */
+    report: BucketedReport;
+    thresholds: WatchThresholds;
+    /** The cache verdict over the same report, when the caller computed one. */
+    cacheDeltaUsd?: number;
+    /** Now, so a partly-elapsed day can be told from a whole one. */
+    nowMs: number;
+    /** Where the previous cycle finished, for the coverage gap. */
+    lastCoveredToMs?: number;
+    /**
+     * Gates already fired, by gate and by day, so a restart is not amnesia.
+     *
+     * Keyed `gate` for whole-period gates and `gate\nYYYY-MM-DD` for a day, so
+     * a day that already alerted stays quiet while a *new* day crossing still
+     * speaks.
+     */
+    alreadyFired?: ReadonlySet<string>;
+}
+/** A day gate cannot judge a day that has not finished being measured. */
+export declare const DAY_MS = 86400000;
+/**
+ * How much of a period must be measured before a threshold over it means
+ * anything. Nine tenths rather than all of it: a usage API's last bucket is
+ * often minutes behind, and a gate that waits for perfection never fires.
+ */
+export declare const COVERAGE_FLOOR = 0.9;
+export declare function firedKey(gate: WatchGate, day: string | null): string;
+export declare function evaluateWatch(options: WatchOptions): WatchResult;
+//# sourceMappingURL=watch.d.ts.map

package/dist/watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../src/watch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,iBAAiB,CAAC;AAEnE,yDAAyD;AACzD,MAAM,MAAM,YAAY;AACtB,+EAA+E;AAC7E,kBAAkB;AACpB,0EAA0E;GACxE,uBAAuB,CAAC;AAE5B,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,uEAAuE;IACvE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB;;;;;;;;OAQG;IACH,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;IACrB,4DAA4D;IAC5D,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACxD;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B;;;;;;;;OAQG;IACH,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B;;;;;;OAMG;IACH,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B;;;;OAIG;IACH,GAAG,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,wDAAwD;IACxD,MAAM,EAAE,cAAc,CAAC;IACvB,UAAU,EAAE,eAAe,CAAC;IAC5B,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACpC;AAED,0EAA0E;AAC1E,eAAO,MAAM,MAAM,WAAa,CAAC;AAEjC;;;;GAIG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAEpE;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,WAAW,CAqEhE"}

package/dist/watch.js

@@ -0,0 +1,104 @@
+/**
+ * The afternoon the loop burned a quarter of the month, said that afternoon.
+ *
+ * Every gate in this product fires when a human runs a command. The failures
+ * worth catching — a retry loop, a prompt that grew, a model swapped in a
+ * deploy — happen at 3pm on a Tuesday, and a report that arrives three weeks
+ * later is an obituary.
+ *
+ * This module decides **what has crossed**, given what is measured and what
+ * the operator asked to be told about. The pulling, the storing, the sleeping
+ * and the sending live in the CLI; everything here is arithmetic over figures
+ * somebody already has, which is what makes an alerting rule testable without
+ * waiting for 3pm.
+ *
+ * **An alert fires on a measured crossing, never on a projection.** "You will
+ * exceed" is a forecast, and this product has refused those at every window
+ * length since 1.27. "You have spent $412 of a $400 budget, measured over
+ * these calls" is a fact, and the difference is the only reason an alert at
+ * 3am can be trusted.
+ *
+ * **A window too short to mean anything does not fire.** A day gate needs a
+ * whole day of measurement before it can fail: the first ten minutes of a day
+ * are not a day, and a watcher that cries at every dawn gets muted — which is
+ * how alerting tools actually fail.
+ */
+/** A day gate cannot judge a day that has not finished being measured. */
+export const DAY_MS = 86_400_000;
+/**
+ * How much of a period must be measured before a threshold over it means
+ * anything. Nine tenths rather than all of it: a usage API's last bucket is
+ * often minutes behind, and a gate that waits for perfection never fires.
+ */
+export const COVERAGE_FLOOR = 0.9;
+export function firedKey(gate, day) {
+    return day === null ? gate : `${gate}\n${day}`;
+}
+export function evaluateWatch(options) {
+    const { report, thresholds, cacheDeltaUsd, nowMs, lastCoveredToMs, alreadyFired } = options;
+    const fired = alreadyFired ?? new Set();
+    const crossings = [];
+    const suppressed = [];
+    const abstentions = [];
+    const span = report.span;
+    const push = (gate, measuredUsd, limitUsd, day, window) => {
+        if (measuredUsd <= limitUsd)
+            return;
+        const crossing = { gate, measuredUsd, limitUsd, window, day, provenance: 'measured' };
+        // Already told: quiet, but still crossed. The two are kept apart because
+        // "we alerted about this" and "this is fine now" are different sentences.
+        (fired.has(firedKey(gate, day)) ? suppressed : crossings).push(crossing);
+    };
+    if (thresholds.maxUsd !== undefined) {
+        if (span === null) {
+            abstentions.push({ gate: 'maxUsd', reason: 'dimension-unavailable', detail: null });
+        }
+        else {
+            push('maxUsd', report.total.totalUsd, thresholds.maxUsd, null, span);
+        }
+    }
+    if (thresholds.maxCacheLossUsd !== undefined) {
+        if (cacheDeltaUsd === undefined || span === null) {
+            abstentions.push({ gate: 'maxCacheLossUsd', reason: 'dimension-unavailable', detail: null });
+        }
+        else {
+            push('maxCacheLossUsd', cacheDeltaUsd, thresholds.maxCacheLossUsd, null, span);
+        }
+    }
+    if (thresholds.maxDayUsd !== undefined) {
+        if (report.byDay.length === 0) {
+            abstentions.push({ gate: 'maxDayUsd', reason: 'dimension-unavailable', detail: null });
+        }
+        else {
+            for (const entry of report.byDay) {
+                const dayStart = Date.parse(`${entry.day}T00:00:00Z`);
+                const dayEnd = dayStart + DAY_MS;
+                /**
+                 * The day still running is measured only up to now, so a threshold
+                 * over it is a threshold over a fraction of a day. Once it *has*
+                 * crossed, the crossing is real whatever the hour — a day that is
+                 * already over budget at noon does not become less over budget at
+                 * midnight — so the abstention only applies while the figure is
+                 * still under the limit.
+                 */
+                const covered = Math.min(nowMs, dayEnd) - dayStart;
+                const whole = covered >= DAY_MS * COVERAGE_FLOOR;
+                if (entry.usd > thresholds.maxDayUsd) {
+                    push('maxDayUsd', entry.usd, thresholds.maxDayUsd, entry.day, { fromMs: dayStart, toMs: dayEnd });
+                }
+                else if (!whole) {
+                    abstentions.push({
+                        gate: 'maxDayUsd',
+                        reason: 'window-too-short',
+                        detail: { coveredMs: Math.max(0, covered), neededMs: DAY_MS },
+                    });
+                }
+            }
+        }
+    }
+    const gap = lastCoveredToMs !== undefined && span !== null && span.fromMs > lastCoveredToMs
+        ? { fromMs: lastCoveredToMs, toMs: span.fromMs }
+        : null;
+    return { crossings, suppressed, abstentions, gap };
+}
+//# sourceMappingURL=watch.js.map

package/dist/watch.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/core",
-  "version": "1.41.0",
+  "version": "1.43.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/config-schema.ts

@@ -80,6 +80,17 @@ export interface SpendConfig {
    * for the day budget's reason.
    */
   maxSessionUsd?: number;
+  /**
+   * What caching may add to the bill before it is a failure.
+   *
+   * `--max-cache-loss-usd` has gated this since 1.21 and only as a flag,
+   * which made it a gate `watch` could not read: a policy that lives in one
+   * invocation is a policy nothing else can act on. It inherits the flag's
+   * refusal — the worst case is read when the log did not record the write
+   * TTL, because a gate reading the flattering half passes the bills it
+   * exists to catch.
+   */
+  maxCacheLossUsd?: number;
   /** Per-label budgets, each gated against that label's own spend. */
   byLabel?: Record<string, number>;
   /**
@@ -147,6 +158,16 @@ export interface TrazumConfig {
    * one is a silence nobody can audit. Waived failures render as waived,
    * never hidden — the bill still counts them; only the exit code is quiet.
    */
+  /**
+   * How long the local usage store keeps a measurement.
+   *
+   * Retention is a policy, so it lives in the repository beside the budgets
+   * rather than in whichever invocation happened to run the prune. There is
+   * deliberately **no default**: deleting measurements on a policy nobody
+   * wrote down is not something anybody should get by accident, so `--prune`
+   * with neither this nor `--keep` refuses and says so.
+   */
+  store?: { keepDays?: number };
   waive?: WaiveEntry[];
   /** Default for `trazum diff --max-growth`, in tokens. */
   maxGrowth?: number;
@@ -186,6 +207,7 @@ export const CONFIG_KEYS = [
   'labels',
   'spend',
   'sources',
+  'store',
   'waive',
   'maxGrowth',
   'baseline',
@@ -195,10 +217,12 @@ export const CONFIG_KEYS = [
 
 export const CONFIG_BASELINE_KEYS = ['path', 'maxGrowthTokens', 'maxGrowthPct'] as const;
 
-export const CONFIG_SPEND_KEYS = ['maxUsd', 'maxDayUsd', 'maxSessionUsd', 'byLabel', 'bySource'] as const;
+export const CONFIG_SPEND_KEYS = ['maxUsd', 'maxDayUsd', 'maxSessionUsd', 'maxCacheLossUsd', 'byLabel', 'bySource'] as const;
 
 export const CONFIG_WAIVE_KEYS = ['gate', 'reason', 'until'] as const;
 
+export const CONFIG_STORE_KEYS = ['keepDays'] as const;
+
 /**
  * The gates a waiver can silence. The list is closed on purpose: a waiver
  * naming a gate that does not exist is a decision about nothing, and the
@@ -396,6 +420,9 @@ function parseSpend(raw: unknown, source: string): SpendConfig {
   if (raw.maxUsd !== undefined) {
     spend.maxUsd = requireNonNegativeNumber(raw.maxUsd, 'spend.maxUsd', source);
   }
+  if (raw.maxCacheLossUsd !== undefined) {
+    spend.maxCacheLossUsd = requireNonNegativeNumber(raw.maxCacheLossUsd, 'spend.maxCacheLossUsd', source);
+  }
   if (raw.maxDayUsd !== undefined) {
     spend.maxDayUsd = requireNonNegativeNumber(raw.maxDayUsd, 'spend.maxDayUsd', source);
   }
@@ -466,6 +493,32 @@ function parseSources(raw: unknown, source: string): Record<string, string[]> {
  * nothing. The expiry is *not* checked against today here — a config file is
  * timeless, and whether a waiver is expired is judged where the gate runs.
  */
+/**
+ * `store.keepDays` — retention, in whole days.
+ *
+ * A fraction of a day is refused rather than rounded: retention decides what
+ * gets deleted, and a policy the tool rounded on the operator's behalf is a
+ * policy nobody agreed to.
+ */
+function parseStore(raw: unknown, source: string): { keepDays?: number } {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    throw new Error(`"store" in ${source} must be an object, for example {"keepDays": 90}.`);
+  }
+  const entry = raw as Record<string, unknown>;
+  rejectUnknownKeys(entry, CONFIG_STORE_KEYS, source, 'store.');
+  const out: { keepDays?: number } = {};
+  if (entry.keepDays !== undefined) {
+    const days = entry.keepDays;
+    if (typeof days !== 'number' || !Number.isInteger(days) || days <= 0) {
+      throw new Error(
+        `"store.keepDays" in ${source} must be a whole number of days above zero, and it is ${JSON.stringify(days)}.`,
+      );
+    }
+    out.keepDays = days;
+  }
+  return out;
+}
+
 function parseWaive(raw: unknown, source: string): WaiveEntry[] {
   if (!Array.isArray(raw)) throw new ConfigError('"waive" must be an array', source);
   return raw.map((entry, index) => {
@@ -654,6 +707,7 @@ export function parseConfig(raw: string, source = CONFIG_FILENAME): TrazumConfig
   if (document.labels !== undefined) config.labels = parseLabels(document.labels, source);
   if (document.spend !== undefined) config.spend = parseSpend(document.spend, source);
   if (document.sources !== undefined) config.sources = parseSources(document.sources, source);
+  if (document.store !== undefined) config.store = parseStore(document.store, source);
   if (document.waive !== undefined) config.waive = parseWaive(document.waive, source);
   if (document.baseline !== undefined) {
     config.baseline = parseBaselineConfig(document.baseline, source);

package/src/history.ts

@@ -29,7 +29,12 @@ export interface StoredReport {
   name: string;
   span: { fromMs: number; toMs: number } | null;
   totalUsd: number;
-  calls: number;
+  /**
+   * null when the source serves no request count — a bucketed usage API. Zero
+   * would read as "no traffic" against real spend, which is the reading this
+   * product refuses everywhere it can occur.
+   */
+  calls: number | null;
   /** Label → dollars this period. */
   byLabel: Map<string, number>;
   /** Model → dollars this period. */
@@ -70,7 +75,7 @@ export interface RepeatedPlanAction {
 export interface HistoryDocument {
   schemaVersion: 1;
   /** Ordered oldest first by span start. */
-  periods: { name: string; fromMs: number; toMs: number; totalUsd: number; calls: number }[];
+  periods: { name: string; fromMs: number; toMs: number; totalUsd: number; calls: number | null }[];
   /** Per label, dollars per period — null where the label had no traffic. */
   labelSeries: { label: string; points: (number | null)[] }[];
   /** Per model, share of that period's total — null where absent. */

package/src/index.ts

@@ -48,6 +48,26 @@ export { buildPlan, planLabelName } 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 { evaluateWatch, firedKey, COVERAGE_FLOOR, DAY_MS } from './watch.js';
+export type {
+  NotJudgeable,
+  WatchAbstention,
+  WatchCrossing,
+  WatchGate,
+  WatchOptions,
+  WatchResult,
+  WatchThresholds,
+} from './watch.js';
+export {
+  STORE_SCHEMA_VERSION,
+  identityOf,
+  resolveStore,
+  recordsFromBuckets,
+  bucketsFromRecords,
+  storeInventory,
+  pruneRecords,
+} from './store.js';
+export type { PruneResult, ResolvedStore, StoreInventory, StoreRecord } from './store.js';
 export {
   CONNECTORS,
   connectorFor,