@trazum/cli 1.40.0 → 1.42.0

package/README.md

@@ -26,6 +26,8 @@ npm install -g @trazum/cli
 | `trazum plan <log\|dir>` | the findings as a ranked plan: what to do first, route+batch combined never summed, projections and money already spent totalled apart, every assumption named. `-o` saves it dated for a later verify; `--min-usd` names what it drops |
 | `trazum verify <plan.json> --against <log>` | did the plan's savings arrive? Three outcomes, never two — arrived, did not, cannot be told — with the world's movement named beside each verdict. `--gate` fails CI on broken promises |
 | `trazum history <dir>` | the long run: series from stored `--json` reports, the climbs and decays no pairwise comparison finds, and plans nobody is executing. Shapes named, nothing forecast |
+| `trazum connect <provider>` | your bill read from the provider's usage API — no export by hand. The credential is borrowed from the environment and never stored; a connected report is restricted on purpose and names the findings a sum cannot support |
+| `trazum store` | what the local store holds and what a prune would take. Re-pulls converge instead of doubling; records it cannot tell apart are kept as two and named; pruning refuses without a retention policy and says what went |
 | `trazum doctor [dir]` | the whole workspace: what nothing is watching, and what fixing would be worth |
 | `trazum rank <dir>` | of these forty prompts, which is worth an afternoon |
 | `trazum prune <file> --cases <file>` | which few-shot examples earn their tokens — measured, and it asks before spending |

package/dist/connect.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 type { ConnectorDescriptor, ConnectorPull } from '@trazum/core';
+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 declare function findCredential(descriptor: ConnectorDescriptor, env: Record<string, string | undefined>): {
+    key: string;
+    source: CredentialSource;
+} | 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 declare function redact(text: string, key?: string): string;
+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 declare function fetchProviderUsage(options: FetchUsageOptions): Promise<FetchUsageResult>;
+//# sourceMappingURL=connect.d.ts.map

package/dist/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAW,MAAM,cAAc,CAAC;AAqBhF,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,mBAAmB,EAC/B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,GAAG,IAAI,CAQlD;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CASzD;AA2BD,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,mBAAmB,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAwG9F"}

package/dist/connect.js

@@ -0,0 +1,204 @@
+/**
+ * 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';
+/** Fixed, compiled in, never taken from the caller. See the module note. */
+const ENDPOINTS = {
+    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;
+/**
+ * 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, env) {
+    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, key) {
+    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, key) {
+    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, fromMs, toMs, page) {
+    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();
+}
+/**
+ * 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) {
+    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 = [];
+    const payloads = [];
+    let page = null;
+    let pages = 0;
+    while (pages < MAX_PAGES) {
+        const url = urlFor(descriptor.id, fromMs, toMs, page);
+        let 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;
+        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.has_more === true;
+        const next = payload.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 = {
+        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 };
+}
+//# sourceMappingURL=connect.js.map

package/dist/connect.js.map

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

package/dist/i18n/en.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"en.d.ts","sourceRoot":"","sources":["../../src/i18n/en.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAqB9C;;;;;;GAMG;AACH,eAAO,MAAM,EAAE,EAAE,WAyhDhB,CAAC"}
+{"version":3,"file":"en.d.ts","sourceRoot":"","sources":["../../src/i18n/en.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAqB9C;;;;;;GAMG;AACH,eAAO,MAAM,EAAE,EAAE,WAqpDhB,CAAC"}

package/dist/i18n/en.js

@@ -33,6 +33,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]
@@ -310,7 +312,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.
@@ -1136,11 +1195,49 @@ ${bold('EXAMPLES')}
         footer: () => 'Ranked by money, projected or already spent alike. The assumptions are yours to answer: this plan is arithmetic over the log, not knowledge of your product.',
         wrote: (path) => `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) => `${model}'s share of the bill has climbed for ${periods} consecutive periods since ${sinceName}: ${from} → ${to}. The totals can look flat while the mix moves under them.`,
         runCache: (periods, sinceName, from, to) => `The cache share has decayed for ${periods} consecutive periods since ${sinceName}: ${from} → ${to} — slowly enough that no single report called it a finding, which is exactly why a series exists.`,
@@ -1157,6 +1254,7 @@ ${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: () => 'A series names shapes, not futures. Twenty points make a trend visible; they do not make next month knowable — where these lines go next is yours to judge.',