@trazum/cli 1.40.0 → 1.42.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.40.0",
+  "version": "1.42.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.40.0"
+    "@trazum/core": "1.42.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/connect.ts

@@ -0,0 +1,245 @@
+/**
+ * The fetch half of the connector: credentials, pagination, and what went
+ * missing.
+ *
+ * The transformation lives in `@trazum/core`, where it is testable without a
+ * network. This module does the part that touches the outside world, and it
+ * is written under three rules the rest of the product does not need:
+ *
+ * **A credential is borrowed, never held.** Keys are read from the environment
+ * at the moment of the call and never written to a config, a cache, a report
+ * or an error message. `redact` runs over everything that can reach a terminal
+ * — a key pasted into a CI log by an error handler is a key that has to be
+ * rotated, and the tool that leaked it is the tool that promised to save money.
+ *
+ * **The endpoint is not user-supplied.** Each provider has one fixed base URL
+ * compiled in. Trazum's SSRF story has been, since 1.14, that a request body
+ * must never *name* a host — it selects one. A usage connector that accepted
+ * `--base-url` would hand that property back for the convenience of a
+ * self-hosted proxy nobody has asked for yet.
+ *
+ * **A partial pull is a partial pull, out loud.** Rate limits, page caps and
+ * windows the provider has aged out all return what was gathered, with the
+ * gap named. A bill quietly short by an unknown amount is the failure this
+ * repository refuses everywhere it can occur, and a paginated API is exactly
+ * where it occurs.
+ */
+
+import { SAFE_FETCH_INIT } from '@trazum/core/node';
+import { normalizeAnthropicUsage, normalizeOpenAIUsage } from '@trazum/core';
+import type { ConnectorDescriptor, ConnectorPull, PullGap } from '@trazum/core';
+
+/** Fixed, compiled in, never taken from the caller. See the module note. */
+const ENDPOINTS: Record<string, string> = {
+  anthropic: 'https://api.anthropic.com/v1/organizations/usage_report/messages',
+  openai: 'https://api.openai.com/v1/organizations/usage/completions',
+};
+
+/**
+ * How many pages a single pull will walk before it stops and says so.
+ *
+ * A cap rather than an unbounded loop: a wrong window against a busy
+ * organisation is otherwise a request storm against somebody's rate limit,
+ * paid for by them. Reaching it is reported as a gap, never as a complete
+ * bill.
+ */
+const MAX_PAGES = 50;
+
+/** Requests in flight is always one: usage endpoints are strictly rate limited. */
+const REQUEST_TIMEOUT_MS = 30_000;
+
+export interface CredentialSource {
+  /** The environment variable the key came from — the *name*, never the value. */
+  variable: string;
+}
+
+/**
+ * Finds the credential without ever returning it to a caller that might print
+ * it: the key stays inside this module, and the caller gets the variable name.
+ */
+export function findCredential(
+  descriptor: ConnectorDescriptor,
+  env: Record<string, string | undefined>,
+): { key: string; source: CredentialSource } | null {
+  for (const variable of descriptor.credentialEnv) {
+    const value = env[variable];
+    if (typeof value === 'string' && value.trim() !== '') {
+      return { key: value.trim(), source: { variable } };
+    }
+  }
+  return null;
+}
+
+/**
+ * Removes credential material from anything on its way to a terminal.
+ *
+ * Two layers on purpose. The exact key is redacted because we hold it; the
+ * shapes are redacted because an error body may quote a *different* key —
+ * the one the caller mistyped, a key from a proxy's log line — and a leak
+ * through somebody else's error message is still a leak through Trazum's
+ * output.
+ */
+export function redact(text: string, key?: string): string {
+  let out = text;
+  if (key !== undefined && key.length >= 8) {
+    out = out.split(key).join('[redacted]');
+  }
+  return out
+    .replace(/sk-ant-[A-Za-z0-9_-]{8,}/g, '[redacted]')
+    .replace(/sk-[A-Za-z0-9_-]{16,}/g, '[redacted]')
+    .replace(/\bBearer\s+[A-Za-z0-9._-]{8,}/gi, 'Bearer [redacted]');
+}
+
+function headersFor(provider: string, key: string): Record<string, string> {
+  if (provider === 'anthropic') {
+    return { 'x-api-key': key, 'anthropic-version': '2023-06-01', accept: 'application/json' };
+  }
+  return { authorization: `Bearer ${key}`, accept: 'application/json' };
+}
+
+function urlFor(provider: string, fromMs: number, toMs: number, page: string | null): string {
+  const url = new URL(ENDPOINTS[provider]!);
+  if (provider === 'anthropic') {
+    url.searchParams.set('starting_at', new Date(fromMs).toISOString());
+    url.searchParams.set('ending_at', new Date(toMs).toISOString());
+    url.searchParams.set('bucket_width', '1d');
+    url.searchParams.append('group_by[]', 'model');
+  } else {
+    url.searchParams.set('start_time', String(Math.floor(fromMs / 1000)));
+    url.searchParams.set('end_time', String(Math.floor(toMs / 1000)));
+    url.searchParams.set('bucket_width', '1d');
+    url.searchParams.append('group_by[]', 'model');
+    url.searchParams.set('limit', '31');
+  }
+  if (page !== null) url.searchParams.set('page', page);
+  return url.toString();
+}
+
+export interface FetchUsageOptions {
+  descriptor: ConnectorDescriptor;
+  fromMs: number;
+  toMs: number;
+  env: Record<string, string | undefined>;
+  /** Injected so the whole path is testable without a network. */
+  fetchImpl?: typeof fetch;
+}
+
+export interface FetchUsageResult {
+  pull: ConnectorPull;
+  source: CredentialSource;
+  pages: number;
+}
+
+/**
+ * Pulls a window of usage, page by page, and reports what it could not get.
+ *
+ * Returns whatever was gathered when a page fails partway through: half a
+ * month with the gap named beats an exception that throws away the half that
+ * arrived, and beats a total that silently describes less traffic than the
+ * caller asked about.
+ */
+export async function fetchProviderUsage(options: FetchUsageOptions): Promise<FetchUsageResult> {
+  const { descriptor, fromMs, toMs, env, fetchImpl = fetch } = options;
+  const found = findCredential(descriptor, env);
+  if (found === null) {
+    throw new Error(
+      `No credential for ${descriptor.displayName}. Trazum reads it from the environment and never stores it — set ${descriptor.credentialEnv.join(' or ')} to ${descriptor.keyKind}. See ${descriptor.docs}.`,
+    );
+  }
+
+  const gaps: PullGap[] = [];
+  const payloads: unknown[] = [];
+  let page: string | null = null;
+  let pages = 0;
+
+  while (pages < MAX_PAGES) {
+    const url = urlFor(descriptor.id, fromMs, toMs, page);
+    let response: Response;
+    try {
+      response = await fetchImpl(url, {
+        ...SAFE_FETCH_INIT,
+        method: 'GET',
+        headers: headersFor(descriptor.id, found.key),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      gaps.push({
+        kind: 'rate-limited',
+        detail: `the request for page ${pages + 1} did not complete (${redact(message, found.key)}), so everything after it is missing from this window`,
+      });
+      break;
+    }
+    pages += 1;
+
+    if (response.status === 429) {
+      gaps.push({
+        kind: 'rate-limited',
+        detail: `the provider rate-limited page ${pages}, so this window stops early and the rest of it was not measured`,
+      });
+      break;
+    }
+    if (response.status === 401 || response.status === 403) {
+      throw new Error(
+        `${descriptor.displayName} refused the credential in ${found.source.variable} (HTTP ${response.status}). This endpoint needs ${descriptor.keyKind}; an ordinary API key cannot read the usage report.`,
+      );
+    }
+    if (!response.ok) {
+      const body = await response.text().catch(() => '');
+      throw new Error(
+        `${descriptor.displayName} returned HTTP ${response.status}: ${redact(body.slice(0, 400), found.key) || '(no body)'}`,
+      );
+    }
+
+    let payload: unknown;
+    try {
+      payload = await response.json();
+    } catch {
+      gaps.push({
+        kind: 'unreadable-entry',
+        detail: `page ${pages} was not readable JSON, so its buckets are missing from this window`,
+      });
+      break;
+    }
+    payloads.push(payload);
+
+    const more = (payload as { has_more?: unknown }).has_more === true;
+    const next = (payload as { next_page?: unknown }).next_page;
+    if (!more) break;
+    if (typeof next !== 'string' || next === '') {
+      gaps.push({
+        kind: 'cursor-expired',
+        detail: 'the provider said there was more and served no cursor to reach it, so this window is short by an unknown amount',
+      });
+      break;
+    }
+    page = next;
+  }
+
+  if (pages >= MAX_PAGES) {
+    gaps.push({
+      kind: 'page-limit',
+      detail: `the pull stopped at ${MAX_PAGES} pages, so this window is incomplete — narrow it with --since and --until`,
+    });
+  }
+
+  const normalize = descriptor.id === 'anthropic' ? normalizeAnthropicUsage : normalizeOpenAIUsage;
+  const pulls = payloads.map((payload) => normalize(payload));
+  const pull: ConnectorPull = {
+    provider: descriptor.id,
+    granularity: descriptor.granularity,
+    buckets: pulls.flatMap((p) => p.buckets),
+    window:
+      pulls.length === 0
+        ? null
+        : {
+            fromMs: Math.min(...pulls.filter((p) => p.window).map((p) => p.window!.fromMs), Infinity),
+            toMs: Math.max(...pulls.filter((p) => p.window).map((p) => p.window!.toMs), -Infinity),
+          },
+    gaps: [...pulls.flatMap((p) => p.gaps), ...gaps],
+    unavailable: descriptor.unavailable,
+  };
+  if (pull.window !== null && !Number.isFinite(pull.window.fromMs)) pull.window = null;
+
+  return { pull, source: found.source, pages };
+}

package/src/i18n/en.ts

@@ -42,6 +42,8 @@ ${bold('USAGE')}
   trazum plan <log.jsonl|dir> [options]
   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 diff <before> <after> [options]
   trazum diff --all <dir> <dir> [options]
   trazum rank <dir> [options]
@@ -319,7 +321,64 @@ ${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 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
+                              the last 30 days.
+  --dry-run                   Say what would be called and which environment
+                              variable the key would come from. Sends nothing
+                              and needs no credential.
+  --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.
+
+  Reads your bill from the provider's usage API, so nothing has to be exported
+  by hand. The credential is read from the environment at the moment of the
+  call and never stored, never printed and never written to a config: set
+  TRAZUM_ANTHROPIC_ADMIN_KEY or TRAZUM_OPENAI_ADMIN_KEY. Each provider needs
+  the narrowest key that can read a usage report, and an ordinary API key
+  cannot.
+
+  These APIs serve sums over a window, not one row per call, so a connected
+  report is a restricted one and says so: the totals, the model split, the day
+  series and the cache verdict are all available, and the per-call findings —
+  input shapes, truncation retries, conversations, context pressure — are
+  listed as unavailable with what would unlock them. A rate limit, a page cap
+  or an expired cursor returns what arrived with the gap named, never a total
+  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.
@@ -1447,13 +1506,76 @@ ${bold('EXAMPLES')}
       `Plan written to ${path}, dated. Keep it: a prediction nobody wrote down is a prediction nobody can be held to.`,
   },
 
+  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.`,
+    unknownProvider: (id, providers) =>
+      `There is no connector for "${id}". The ones that exist are: ${providers}.`,
+    dryRun: (provider, from, to, envVars, keyKind) =>
+      `Would read ${provider} usage from ${from} to ${to}, using ${keyKind} taken from ${envVars}. Nothing was sent and no credential was needed to print this.`,
+    heading: (provider, from, to, usd, calls) =>
+      calls === null
+        ? `${provider} · ${from} → ${to} · ${usd}`
+        : `${provider} · ${from} → ${to} · ${usd} · ${calls} calls`,
+    modelRow: (model, usd, share, calls) =>
+      calls === null ? `${model}  ${usd}  ${share}` : `${model}  ${usd}  ${share} · ${calls} calls`,
+    nothingBilled: () =>
+      'The provider billed nothing in this window. That is a measurement, not an error — widen it with --since if you expected traffic.',
+    cachePaid: (saved) => `Caching paid for itself: ${saved} less than these tokens would have cost as ordinary input.`,
+    cacheLost: (added) => `Caching added ${added} to this bill against what the same tokens would have cost as ordinary input.`,
+    cacheUnsettled: () =>
+      'This source did not say which TTL the cache writes used, so the cheaper rate was assumed and the verdict moves under the other one. Unsettled, not settled in your favour.',
+    noCallCount: (provider) =>
+      `${provider}'s usage report serves token sums and no request count, so there is no call count here and no per-call average. A zero would read as "no traffic", so nothing is printed instead.`,
+    unpriced: (model, tokens) =>
+      `${model} is not in the price catalogue, so its ${tokens} tokens are counted and its money is not. Add it with --pricing rather than reading the total as complete.`,
+    gap: (detail) => `This window is incomplete: ${detail}.`,
+    unavailable: (findings) =>
+      `Findings this source cannot support: ${findings}. They need one row per call, and a sum has lost the rows — a per-call log still answers them.`,
+    wrote: (path) => `Report written to ${path}.`,
+    footer: () =>
+      'Every figure here is the provider\u2019s own billed token count at the catalogue\u2019s rates. Nothing was estimated, and nothing the provider did not serve was filled in.',
+  },
+
   history: {
     noTarget: () =>
       'Point this at a directory of stored reports: trazum history reports/. It reads the --json documents "trazum profile" writes (and any saved plans beside them) and builds the series no pairwise comparison can see.',
     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) =>
@@ -1474,6 +1596,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: () =>