@trazum/cli 1.41.0 → 1.43.0

package/dist/store-fs.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Where the store actually lives.
+ *
+ * The core decides what a record is and when two are the same; this decides
+ * where the bytes go. Split that way for the reason every module here is:
+ * `@trazum/core` stays browser-safe, and the CLI keeps its monopoly on I/O.
+ *
+ * **Append-only, one buffer per write.** A pull appends a single block and
+ * never rewrites what is already there. Two consequences worth stating: a
+ * crash during a write loses the tail of one block rather than a year of
+ * measurements, and two runs writing at once interleave whole blocks rather
+ * than half-lines. Compaction is a separate, explicit errand — `store
+ * --prune` — because collapsing a log is the one operation that destroys
+ * something, and it should never happen as a side effect of a pull.
+ *
+ * **A line that will not parse is kept, counted and skipped.** The store is a
+ * file a human may open, a backup may truncate and a merge may mangle. Losing
+ * the whole month because one line is broken would be the worst possible
+ * response; so would silently pretending the month is complete.
+ */
+import type { ResolvedStore, StoreRecord } from '@trazum/core';
+/** The directory name, relative to wherever the caller roots the store. */
+export declare const STORE_DIR = ".trazum/store";
+export interface StoreReadResult {
+    resolved: ResolvedStore;
+    /** Lines that would not parse: counted and named by file, never dropped quietly. */
+    unreadable: {
+        file: string;
+        line: number;
+    }[];
+    /** Files read, so an empty store can be told from an unread one. */
+    files: string[];
+}
+/**
+ * Reads every record in the store.
+ *
+ * Returns an empty result rather than throwing when the store does not exist:
+ * "you have not stored anything yet" is a state, not an error, and the caller
+ * says so in a sentence that names `trazum connect`.
+ */
+export declare function readStore(root: string): Promise<StoreReadResult>;
+/**
+ * Appends records, grouped into one write per month file.
+ *
+ * Nothing already on disk is read, rewritten or resolved here: convergence
+ * happens when the store is *read*, which is what keeps a write cheap enough
+ * to run on a schedule and impossible to corrupt by racing.
+ */
+export declare function appendRecords(root: string, records: readonly StoreRecord[]): Promise<number>;
+/**
+ * Rewrites the store with exactly the records given.
+ *
+ * The one operation that destroys something, so it is only ever reached from
+ * an explicit `--prune`. Each month file is written whole, and a month left
+ * with nothing is written empty rather than removed — a missing file and an
+ * empty one say different things to whoever looks next.
+ */
+export declare function rewriteStore(root: string, records: readonly StoreRecord[]): Promise<void>;
+//# sourceMappingURL=store-fs.d.ts.map

package/dist/store-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-fs.d.ts","sourceRoot":"","sources":["../src/store-fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE/D,2EAA2E;AAC3E,eAAO,MAAM,SAAS,kBAAkB,CAAC;AAOzC,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,aAAa,CAAC;IACxB,oFAAoF;IACpF,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC7C,oEAAoE;IACpE,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CA2CtE;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBlG;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA4B/F"}

package/dist/store-fs.js

@@ -0,0 +1,145 @@
+/**
+ * Where the store actually lives.
+ *
+ * The core decides what a record is and when two are the same; this decides
+ * where the bytes go. Split that way for the reason every module here is:
+ * `@trazum/core` stays browser-safe, and the CLI keeps its monopoly on I/O.
+ *
+ * **Append-only, one buffer per write.** A pull appends a single block and
+ * never rewrites what is already there. Two consequences worth stating: a
+ * crash during a write loses the tail of one block rather than a year of
+ * measurements, and two runs writing at once interleave whole blocks rather
+ * than half-lines. Compaction is a separate, explicit errand — `store
+ * --prune` — because collapsing a log is the one operation that destroys
+ * something, and it should never happen as a side effect of a pull.
+ *
+ * **A line that will not parse is kept, counted and skipped.** The store is a
+ * file a human may open, a backup may truncate and a merge may mangle. Losing
+ * the whole month because one line is broken would be the worst possible
+ * response; so would silently pretending the month is complete.
+ */
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { resolveStore } from '@trazum/core';
+/** The directory name, relative to wherever the caller roots the store. */
+export const STORE_DIR = '.trazum/store';
+/** Records are filed by the UTC month their window starts in. */
+function monthOf(record) {
+    return new Date(record.fromMs).toISOString().slice(0, 7);
+}
+/**
+ * Reads every record in the store.
+ *
+ * Returns an empty result rather than throwing when the store does not exist:
+ * "you have not stored anything yet" is a state, not an error, and the caller
+ * says so in a sentence that names `trazum connect`.
+ */
+export async function readStore(root) {
+    const dir = join(root, STORE_DIR);
+    const records = [];
+    const unreadable = [];
+    const files = [];
+    let providers;
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        providers = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return { resolved: resolveStore([]), unreadable, files };
+    }
+    for (const provider of providers.sort()) {
+        const providerDir = join(dir, provider);
+        let months;
+        try {
+            months = (await readdir(providerDir)).filter((name) => name.endsWith('.jsonl')).sort();
+        }
+        catch {
+            continue;
+        }
+        for (const month of months) {
+            const path = join(providerDir, month);
+            files.push(join(STORE_DIR, provider, month));
+            const text = await readFile(path, 'utf8');
+            for (const [index, line] of text.split('\n').entries()) {
+                if (line.trim() === '')
+                    continue;
+                try {
+                    const parsed = JSON.parse(line);
+                    if (typeof parsed?.provider === 'string' && typeof parsed?.fromMs === 'number') {
+                        records.push(parsed);
+                    }
+                    else {
+                        unreadable.push({ file: join(STORE_DIR, provider, month), line: index + 1 });
+                    }
+                }
+                catch {
+                    unreadable.push({ file: join(STORE_DIR, provider, month), line: index + 1 });
+                }
+            }
+        }
+    }
+    return { resolved: resolveStore(records), unreadable, files };
+}
+/**
+ * Appends records, grouped into one write per month file.
+ *
+ * Nothing already on disk is read, rewritten or resolved here: convergence
+ * happens when the store is *read*, which is what keeps a write cheap enough
+ * to run on a schedule and impossible to corrupt by racing.
+ */
+export async function appendRecords(root, records) {
+    if (records.length === 0)
+        return 0;
+    const byFile = new Map();
+    for (const record of records) {
+        const key = join(record.provider, `${monthOf(record)}.jsonl`);
+        const list = byFile.get(key) ?? [];
+        list.push(record);
+        byFile.set(key, list);
+    }
+    for (const [relative, list] of byFile) {
+        const path = join(root, STORE_DIR, relative);
+        await mkdir(join(path, '..'), { recursive: true });
+        const block = `${list.map((record) => JSON.stringify(record)).join('\n')}\n`;
+        await writeFile(path, block, { flag: 'a', mode: 0o600 });
+    }
+    return records.length;
+}
+/**
+ * Rewrites the store with exactly the records given.
+ *
+ * The one operation that destroys something, so it is only ever reached from
+ * an explicit `--prune`. Each month file is written whole, and a month left
+ * with nothing is written empty rather than removed — a missing file and an
+ * empty one say different things to whoever looks next.
+ */
+export async function rewriteStore(root, records) {
+    const dir = join(root, STORE_DIR);
+    const existing = new Set();
+    try {
+        for (const provider of await readdir(dir)) {
+            for (const month of await readdir(join(dir, provider)).catch(() => [])) {
+                if (month.endsWith('.jsonl'))
+                    existing.add(join(provider, month));
+            }
+        }
+    }
+    catch {
+        // Nothing stored yet: the writes below create what is needed.
+    }
+    const byFile = new Map();
+    for (const record of records) {
+        const key = join(record.provider, `${monthOf(record)}.jsonl`);
+        const list = byFile.get(key) ?? [];
+        list.push(record);
+        byFile.set(key, list);
+    }
+    for (const relative of new Set([...existing, ...byFile.keys()])) {
+        const list = byFile.get(relative) ?? [];
+        const path = join(dir, relative);
+        await mkdir(join(path, '..'), { recursive: true });
+        const block = list.length === 0 ? '' : `${list.map((r) => JSON.stringify(r)).join('\n')}\n`;
+        await writeFile(path, block, { mode: 0o600 });
+    }
+}
+//# sourceMappingURL=store-fs.js.map

package/dist/store-fs.js.map

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

package/dist/watch-run.d.ts

@@ -0,0 +1,69 @@
+/**
+ * One cycle of watching, and the state that survives a restart.
+ *
+ * `--once` is the primitive: pull the window, keep it, evaluate the gates,
+ * emit what crossed, save state. A cron entry runs exactly that, and so does
+ * every test. The foreground loop is this function in a timer, so there is one
+ * code path and no daemon-only behaviour that nobody exercises.
+ *
+ * **The state file is what makes a restart honest.** Without it a resumed
+ * watcher re-alerts on yesterday's crossing (noise nobody reads) and implies
+ * it was watching the whole time (a claim it cannot make). With it, the
+ * crossing stays quiet and the unwatched stretch gets named once.
+ */
+import type { WatchCrossing } from '@trazum/core';
+export declare const WATCH_STATE_FILE = ".trazum/watch.json";
+export declare const WATCH_STATE_VERSION = 1;
+export interface WatchState {
+    v: number;
+    /** When the last cycle ran, so a long silence can be told from a first run. */
+    lastCycleMs: number;
+    /** How far the measurements reached, for the coverage gap. */
+    lastCoveredToMs: number | null;
+    /** Gate keys already alerted on, so a restart is not amnesia. */
+    fired: Record<string, number>;
+}
+export declare function readWatchState(root: string): Promise<WatchState | null>;
+export declare function writeWatchState(root: string, state: WatchState): Promise<void>;
+/**
+ * Whether a webhook URL is one this tool will post to.
+ *
+ * **This is not the SSRF case and the difference matters.** `checkedEndpoint`
+ * exists because a *request body* must never name a host: an anonymous caller
+ * pointing a shared server at an internal address is somebody else's machine
+ * reaching somewhere it was never meant to. Here the URL is in the operator's
+ * own config, on their own machine, and pointing it at their own alerting
+ * daemon on loopback is the ordinary case rather than the attack.
+ *
+ * So loopback is allowed and plain http is allowed *only* there, while two
+ * rules stay absolute: no credentials embedded in the URL, because a URL ends
+ * up in logs and shell history; and https everywhere else, because an alert
+ * carries spend figures across a network.
+ */
+export type WebhookRejection = 'invalid-url' | 'credentials-in-url' | 'insecure-scheme';
+export declare function checkWebhook(raw: string): {
+    ok: true;
+    url: URL;
+} | {
+    ok: false;
+    reason: WebhookRejection;
+};
+/**
+ * The alert payload.
+ *
+ * Figures and gate names, never prompt text — the store has never held any and
+ * neither does this. Every crossing carries its own provenance, so a receiver
+ * that fans these into a dashboard cannot lose track of what kind of number it
+ * is holding.
+ */
+export interface WatchAlert {
+    schemaVersion: 1;
+    firedAtMs: number;
+    crossings: WatchCrossing[];
+}
+export declare function postWebhook(url: URL, alert: WatchAlert, fetchImpl?: typeof fetch): Promise<{
+    ok: boolean;
+    status: number | null;
+    error: string | null;
+}>;
+//# sourceMappingURL=watch-run.d.ts.map

package/dist/watch-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-run.d.ts","sourceRoot":"","sources":["../src/watch-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,eAAO,MAAM,gBAAgB,uBAAuB,CAAC;AAErD,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAC;IACV,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAU7E;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpF;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,oBAAoB,GAAG,iBAAiB,CAAC;AAExF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,GAAG,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,CAkB1G;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,CAAC,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED,wBAAsB,WAAW,CAC/B,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,UAAU,EACjB,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAmBvE"}

package/dist/watch-run.js

@@ -0,0 +1,79 @@
+/**
+ * One cycle of watching, and the state that survives a restart.
+ *
+ * `--once` is the primitive: pull the window, keep it, evaluate the gates,
+ * emit what crossed, save state. A cron entry runs exactly that, and so does
+ * every test. The foreground loop is this function in a timer, so there is one
+ * code path and no daemon-only behaviour that nobody exercises.
+ *
+ * **The state file is what makes a restart honest.** Without it a resumed
+ * watcher re-alerts on yesterday's crossing (noise nobody reads) and implies
+ * it was watching the whole time (a claim it cannot make). With it, the
+ * crossing stays quiet and the unwatched stretch gets named once.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { SAFE_FETCH_INIT } from '@trazum/core/node';
+export const WATCH_STATE_FILE = '.trazum/watch.json';
+export const WATCH_STATE_VERSION = 1;
+export async function readWatchState(root) {
+    try {
+        const parsed = JSON.parse(await readFile(join(root, WATCH_STATE_FILE), 'utf8'));
+        if (parsed?.v !== WATCH_STATE_VERSION)
+            return null;
+        return parsed;
+    }
+    catch {
+        // No state, or state this version cannot read: a first cycle either way,
+        // which is a state the caller reports rather than an error.
+        return null;
+    }
+}
+export async function writeWatchState(root, state) {
+    const path = join(root, WATCH_STATE_FILE);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+}
+export function checkWebhook(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return { ok: false, reason: 'invalid-url' };
+    }
+    if (url.username !== '' || url.password !== '') {
+        return { ok: false, reason: 'credentials-in-url' };
+    }
+    const loopback = url.hostname === 'localhost' ||
+        url.hostname === '127.0.0.1' ||
+        url.hostname === '[::1]' ||
+        url.hostname === '::1';
+    if (url.protocol === 'https:')
+        return { ok: true, url };
+    if (url.protocol === 'http:' && loopback)
+        return { ok: true, url };
+    return { ok: false, reason: 'insecure-scheme' };
+}
+export async function postWebhook(url, alert, fetchImpl = fetch) {
+    try {
+        const response = await fetchImpl(url.toString(), {
+            ...SAFE_FETCH_INIT,
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(alert),
+            signal: AbortSignal.timeout(10_000),
+        });
+        return { ok: response.ok, status: response.status, error: null };
+    }
+    catch (error) {
+        /**
+         * A webhook that will not deliver must not take the alert down with it.
+         * The exit code and the stdout event have already carried the crossing;
+         * losing those because a receiver is down would make the quietest failure
+         * the loudest one.
+         */
+        return { ok: false, status: null, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+//# sourceMappingURL=watch-run.js.map

package/dist/watch-run.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.41.0",
+  "version": "1.43.0",
   "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",
@@ -37,7 +37,7 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@trazum/core": "1.41.0"
+    "@trazum/core": "1.43.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -43,6 +43,8 @@ ${bold('USAGE')}
   trazum verify <plan.json> --against <newer.jsonl|dir> [options]
   trazum history <dir-of-stored-reports> [options]
   trazum connect <anthropic|openai> [options]
+  trazum store [--prune] [options]
+  trazum watch [--once | --interval 15m] [options]
   trazum diff <before> <after> [options]
   trazum diff --all <dir> <dir> [options]
   trazum rank <dir> [options]
@@ -320,6 +322,54 @@ ${bold('OPTIONS FOR plan')}
   a plan that hides its assumptions is advice pretending to be arithmetic.
   Projected savings and money already spent are separate totals throughout.
 
+${bold('OPTIONS FOR watch')}
+  --once                      One cycle: measure, keep, evaluate, emit,
+                              remember. What a cron entry runs. The default.
+  --interval <n>m|h           Stay in the foreground and repeat. Minimum five
+                              minutes: usage APIs are rate limited, and a tight
+                              loop is a way to get your own key throttled.
+  --webhook <url>             POST the crossings somewhere. https only, except
+                              loopback; a URL carrying credentials is refused,
+                              because URLs end up in logs and shell history.
+  --payload <file>            Evaluate a usage payload you already have,
+                              instead of the store.
+  --json                      The cycle as data: crossings, abstentions, gap.
+
+  Evaluates the spend gates from your config — maxUsd, maxDayUsd,
+  maxCacheLossUsd — against what has been measured, and tells you the
+  afternoon it happens rather than three weeks later. Exits 1 when something
+  crossed, so cron mails it and CI fails.
+
+  An alert fires on a measured crossing and never on a projection: "you have
+  spent $412 of a $400 budget" is a fact and "you will exceed" is a forecast,
+  which this tool does not make at any window length. A day still being
+  measured is reported as not yet judgeable rather than passed — but a day
+  already over budget fires whatever the hour, because it does not become less
+  over budget at midnight.
+
+  A restart does not re-alert on a crossing already reported, and names the
+  stretch it was not watching, because a watcher that resumes in silence
+  implies coverage it did not have.
+
+${bold('OPTIONS FOR store')}
+  --prune                     Drop measurements older than the retention
+                              policy, and compact the append log to what the
+                              store already resolves to. Says what went.
+  --keep <n>d                 Retention for this run, when the config has none.
+  --dry-run                   With --prune: say what would go, and delete
+                              nothing.
+  --json                      The inventory as data.
+
+  Says what the local store holds: how many measurements, over what span, per
+  provider, and what a prune would take. The store keeps aggregates and
+  billing fields — never prompt text, never completion text, never a
+  credential — so it is a file a team can back up without a privacy review.
+
+  Pruning is the one operation here that destroys something, so it refuses to
+  run without a retention policy: set "store": {"keepDays": 90} in the config
+  or pass --keep. Deleting measurements on a policy nobody wrote down is not a
+  default anybody should get by accident.
+
 ${bold('OPTIONS FOR connect')}
   --since <when>              The window to pull. A UTC day, an ISO timestamp,
   --until <when>              a relative window (7d, 24h) or "now". Defaults to
@@ -330,6 +380,9 @@ ${bold('OPTIONS FOR connect')}
   --payload <file>            Price a usage payload you already have, instead of
                               pulling one. No credential, no network — the same
                               arithmetic on the same shape.
+  --store                     Keep what was pulled in the local store, so the
+                              next run does not download it again and "trazum
+                              history --store" has a series.
   -o, --out <file>            Save the priced report as JSON.
   --markdown-out <file>       Also write it as Markdown, for a CI job summary.
   --json                      The report as data.
@@ -350,6 +403,12 @@ ${bold('OPTIONS FOR connect')}
   that quietly describes less traffic than you asked about.
 
 ${bold('OPTIONS FOR history')}
+  --store                     Build the series from the local store instead of
+                              a directory of stored reports. Bucketed sources
+                              carry no label, so the label series is absent and
+                              said to be — the model-share and cache-share
+                              series are what a series exists for, and both
+                              work.
   --markdown-out <file>       Also write the series as Markdown, for a CI job
                               summary or a pull request comment.
   --json                      The history as data.
@@ -1477,6 +1536,80 @@ ${bold('EXAMPLES')}
       `Plan written to ${path}, dated. Keep it: a prediction nobody wrote down is a prediction nobody can be held to.`,
   },
 
+  watch: {
+    noThresholds: () =>
+      'Watching needs something to watch for. Set spend.maxUsd, spend.maxDayUsd or spend.maxCacheLossUsd in trazum.config.json — a watcher with no threshold is a green light nobody earned.',
+    nothingToWatch: (dir) =>
+      `Nothing has been measured yet: the store at ${dir} is empty. Fill it with "trazum connect <provider> --store" first — watching nothing would report that everything is fine.`,
+    intervalTooTight: () =>
+      '--interval must be at least 5m. Usage APIs are rate limited, and a tight loop is a way to get your own key throttled by a tool that exists to save you money.',
+    badWebhook: (reason) =>
+      reason === 'credentials-in-url'
+        ? 'That webhook URL carries credentials. URLs end up in logs, shell history and error messages, so this one is refused — put the secret in a header your receiver checks, or in the receiver itself.'
+        : reason === 'insecure-scheme'
+          ? 'A webhook must be https, except on loopback. An alert carries your spend figures, and sending them in the clear across a network is a leak you did not ask for.'
+          : 'That webhook is not a URL this tool can parse.',
+    crossed: (gate, measured, limit, day) => {
+      const what =
+        gate === 'maxUsd'
+          ? 'Total spend'
+          : gate === 'maxDayUsd'
+            ? `Spend on ${day}`
+            : 'Money lost to caching';
+      return `CROSSED — ${what} is ${measured} against a limit of ${limit}. Measured, not projected.`;
+    },
+    stillOver: (gate, measured, limit, day) => {
+      const what =
+        gate === 'maxUsd'
+          ? 'Total spend'
+          : gate === 'maxDayUsd'
+            ? `Spend on ${day}`
+            : 'Money lost to caching';
+      return `STILL OVER — ${what} is ${measured} against a limit of ${limit}, and was already reported. Quiet is not clean.`;
+    },
+    notJudgeable: (gate, reason, covered) =>
+      reason === 'window-too-short'
+        ? `${gate} cannot be judged yet: this period is ${covered ?? 'partly'} measured, and a threshold over part of a day is a threshold over something else. Not a pass — it will be judged when the day is in.`
+        : `${gate} cannot be judged on this source, which does not serve what the gate is written against. Not a pass: a gate silently skipped reads exactly like a gate that keeps passing.`,
+    gap: (from, to) =>
+      `Nothing was watching between ${from} and ${to}. Whatever crossed in that stretch was not seen, and this line exists so a resumed watcher does not imply coverage it did not have.`,
+    allWithin: (gates) => `Within every threshold: ${gates} gates evaluated against measured spend.`,
+    webhookFailed: (status) =>
+      `The webhook did not deliver (${status}). The crossing is still in the exit code and in the output above — a receiver being down must not be the quietest failure in the room.`,
+    watching: (minutes) => `Watching every ${minutes} minutes. Ctrl-C stops it.`,
+  },
+
+  store: {
+    appended: (count, dir) => `Kept ${count} measurements in ${dir}.`,
+    empty: (dir) =>
+      `The store at ${dir} is empty. Fill it with "trazum connect <provider> --store" — that is a state, not an error.`,
+    heading: (records, usd, from, to) =>
+      `The store: ${records} measurements · ${usd} · ${from} → ${to}`,
+    providerRow: (provider, records, span, models) =>
+      `${provider}  ${records} measurements · ${span} · ${models} models`,
+    holds: (files) =>
+      `Held in ${files} files: token counts, billed dollars and the account's own workspace and key identifiers. Never prompt text, never completion text, never a credential — this is a file you can back up without a privacy review.`,
+    possiblyDouble: (count) =>
+      `${count} records could not be told apart from another — a window of no length, or a record naming no model. They are kept whole rather than merged, so a total built on them may count the same spend twice. Saying so beats a smaller number nobody can check.`,
+    unknownVersion: (count) =>
+      `${count} records come from a newer schema than this version knows, so they are kept and left out of the figures above rather than guessed at. Upgrade to read them.`,
+    unreadable: (file, line) =>
+      `${file} line ${line} would not parse, so it is not in the figures above. The rest of the file was read — one broken line must not lose a month.`,
+    retention: (days) => `Retention: ${days} days, from "store.keepDays". Run "trazum store --prune" to apply it.`,
+    noRetention: () =>
+      'No retention policy is configured, so nothing is ever deleted on its own. Set "store": {"keepDays": 90} when you want one.',
+    pruneNeedsPolicy: () =>
+      'Pruning needs a retention policy: set "store": {"keepDays": 90} in trazum.config.json, or pass --keep 90d for this run. Deleting measurements on a policy nobody wrote down is not a default you should get by accident.',
+    pruneDryRun: (count, days, span, usd) =>
+      span === null
+        ? `Nothing is older than ${days} days, so a prune would delete nothing.`
+        : `A prune would delete ${count} measurements older than ${days} days, covering ${span} and ${usd} of measured spend. Nothing was deleted — this was --dry-run.`,
+    pruned: (count, days, span, usd, kept) =>
+      span === null
+        ? `Nothing was older than ${days} days. ${kept} measurements kept, and the append log compacted.`
+        : `Deleted ${count} measurements older than ${days} days, covering ${span} and ${usd} of measured spend. ${kept} kept, and the append log compacted to what the store already resolved to.`,
+  },
+
   connect: {
     noTarget: (providers) =>
       `Name a provider to read your bill from: trazum connect anthropic. Available: ${providers}. The credential comes from the environment and is never stored — add --dry-run to see exactly what would be called and which variable it would be read from.`,
@@ -1514,7 +1647,8 @@ ${bold('EXAMPLES')}
     needsThree: (count) =>
       `A series needs at least three dated reports, and this directory has ${count}. Two reports is a comparison, and "trazum profile --against" already does that better.`,
     heading: (periods, from, to) => `The long run: ${periods} periods, ${from} → ${to}`,
-    periodRow: (name, usd, calls, days) => `${name}  ${usd} · ${calls} calls · ${days} days`,
+    periodRow: (name, usd, calls, days) =>
+      calls === null ? `${name}  ${usd} · ${days} days` : `${name}  ${usd} · ${calls} calls · ${days} days`,
     runLabel: (label, periods, sinceName, from, to) =>
       `${label} has climbed for ${periods} consecutive periods since ${sinceName}: ${from} → ${to}. A shape, not a forecast.`,
     runModel: (model, periods, sinceName, from, to) =>
@@ -1535,6 +1669,8 @@ ${bold('EXAMPLES')}
       const span = first !== null && last !== null ? ` (${first} → ${last})` : '';
       return `${what} has been planned ${appearances} times${span} and is still in the newest plan — a decision nobody is revisiting.`;
     },
+    storeNoLabels: () =>
+      'This series comes from the store, and a usage API groups by model and workspace rather than by workload — so there is no label series here at all. Absent, not empty: nothing above says a workload did or did not move.',
     undated: (name) => `${name} carries no span, so it is on no timeline above — named, never silently absorbed.`,
     unrecognized: (name) => `${name} is neither a stored report nor a saved plan, so it is in no series above.`,
     footer: () =>