@trazum/cli 1.48.0 → 1.50.0

package/dist/index.js

@@ -2,7 +2,7 @@
 import { open, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { join, resolve as resolvePath } from 'node:path';
 import { gunzipSync } from 'node:zlib';
-import { applyRewrites, BASELINE_FILENAME, BASELINE_VERSION, breaches, cacheableMinimum, analyzeCachePrefix, billLevers, bucketedCacheEconomics, bucketedProfile, buildHistory, buildPlan, connectorFor, CONNECTORS, normalizeAnthropicUsage, normalizeOpenAIUsage, bucketsFromRecords, evaluateWatch, firedKey, pruneRecords, recordsFromBuckets, storeInventory, storedReportFrom, verifyPlan, cacheEconomics, cacheHitRate, contextPressure, comparePrompts, compareToBaseline, computeSavings, countTokensAnthropic, DEFAULT_USAGE, detectFromSource, matchLocale, parsePlanDocument, waiverDay, waiverHistory, proposeInit, MIN_RATE_DAYS, parseConfig, coverageDrift, driversBetween, explainGateFailure, assignSources, fleetRollup, labelCoverage, measuredUsage, gateMargin, GATE_MARGIN_TIGHT, estimateTokens, evaluate, extractPrompts, findExamples, formatBaseline, formatSignedUsd, formatUsd, getMessages, getModel, hasMarker, LOCALES, MAX_BASELINE_BYTES, moneyIsComparable, mostSpecificMatch, nearestName, optimize, parseBaseline, PHRASE_LANGUAGES, plannedCalls, profilePrompt, profileToCsv, profileUsage, promptId, providerFromEnv, pruneExamples, refineWithLlm, rejectionText, reorderForCache, repriceProfile, reviewAgeDays, reviewExamples, RULES, sharedPrefixes, sharesOf, SOURCE_EXTENSIONS, suggestRewrites, toOtlpMetrics, toPromptfoo, TTL_1H_MS, UNLABELLED, withExactTokenCounts, } from '@trazum/core';
+import { applyRewrites, BASELINE_FILENAME, BASELINE_VERSION, breaches, cacheableMinimum, analyzeCachePrefix, billLevers, bucketedCacheEconomics, bucketedProfile, buildHistory, buildPlan, connectorFor, CONNECTORS, normalizeAnthropicUsage, normalizeOpenAIUsage, bucketsFromRecords, evaluateWatch, firedKey, pruneRecords, recordsFromBuckets, storeInventory, storedReportFrom, verifyPlan, cacheEconomics, cacheHitRate, contextPressure, comparePrompts, compareToBaseline, computeSavings, countTokensAnthropic, DEFAULT_USAGE, budgetPositions, conform, detectFromSource, matchLocale, parsePlanDocument, waiverDay, waiverHistory, proposeInit, MIN_RATE_DAYS, parseConfig, coverageDrift, driversBetween, explainGateFailure, assignSources, fleetRollup, labelCoverage, measuredUsage, gateMargin, GATE_MARGIN_TIGHT, estimateTokens, evaluate, extractPrompts, findExamples, formatBaseline, formatSignedUsd, formatUsd, getMessages, getModel, hasMarker, LOCALES, MAX_BASELINE_BYTES, moneyIsComparable, mostSpecificMatch, nearestName, optimize, parseBaseline, PHRASE_LANGUAGES, plannedCalls, profilePrompt, profileToCsv, profileUsage, promptId, providerFromEnv, pruneExamples, refineWithLlm, rejectionText, reorderForCache, repriceProfile, reviewAgeDays, reviewExamples, RULES, sharedPrefixes, sharesOf, SOURCE_EXTENSIONS, suggestRewrites, toOtlpMetrics, toPromptfoo, TTL_1H_MS, UNLABELLED, withExactTokenCounts, } from '@trazum/core';
 import { cacheDir, cacheStats, cachingProvider, clearCache } from './suggest-cache.js';
 import { dayOf, formatGap, median, spanDays } from './time.js';
 // Everything that reads the filesystem, on its own entry point so the web
@@ -30,6 +30,7 @@ const c = {
 };
 const VALUE_FLAGS = new Set([
     'against',
+    'contract',
     'from-log',
     'min-usd',
     'payload',
@@ -311,6 +312,7 @@ const COMMAND_FLAGS = {
     models: [],
     rank: ['level', 'model', 'calls', 'output-tokens', 'batch', 'disable', 'prompt', 'markdown-out'],
     init: ['dry-run', 'yes', 'json', 'pricing', 'pricing-live'],
+    conform: ['contract', 'json'],
     where: [],
     rules: [],
     blame: ['limit', 'model', 'calls', 'output-tokens', 'batch', 'prompt', 'markdown-out'],
@@ -1037,6 +1039,18 @@ const INIT_LOG_CANDIDATES = [
  * answers for a file somebody named while this answers for a repository
  * nobody has vouched for.
  */
+/** Problems listed before the rest are counted. A wall of them helps nobody. */
+const MAX_CONFORM_PROBLEMS = 20;
+/** The contracts `--contract` accepts, so a typo is refused with the list. */
+const CONTRACT_NAMES = [
+    'usage-log',
+    'profile',
+    'plan',
+    'verification',
+    'history',
+    'connected',
+    'cost-answer',
+];
 /** How many source files, and how large each may be. Both reported when they bite. */
 const INIT_MAX_SOURCE_FILES = 400;
 const INIT_MAX_SOURCE_BYTES = 256 * 1024;
@@ -1381,6 +1395,78 @@ async function commandInit(args, config, pricing, t) {
     console.log(c.green(t.init.wrote(configPath)));
     console.log();
 }
+/**
+ * `trazum conform <file>` — does this document conform, and what will it not
+ * be able to answer?
+ *
+ * The command that makes the five contracts something to build against rather
+ * than something to read about. An emitter — a logging wrapper somebody wrote
+ * this afternoon, a connector for a provider this repository has never heard
+ * of, a dashboard writing profile documents of its own — points this at what
+ * it produced and finds out before shipping.
+ *
+ * **The second half is the useful half.** "Valid" is a yes or no. "Here is
+ * what a valid document of this shape cannot tell you, and the field that
+ * would unlock each" is the answer somebody acts on: a usage log with no
+ * `session` is perfectly conformant and simply has no conversation growth in
+ * it, and an emitter that only ever hears "valid" ships it and never finds out
+ * why half the report is empty.
+ *
+ * Exits 1 on a problem, so it gates. It never exits 1 on an *unavailable
+ * finding*: choosing not to log sessions is a decision, not a defect, and a
+ * gate that failed on it would be this tool telling somebody what to record.
+ */
+async function commandConform(args, t) {
+    const target = args.positional[0];
+    if (target === undefined)
+        throw new Error(t.conform.noTarget());
+    const named = stringFlag(args, 'contract');
+    if (named !== undefined && !CONTRACT_NAMES.includes(named)) {
+        throw new Error(t.conform.badContract(named, CONTRACT_NAMES.join(', ')));
+    }
+    const text = target === '-' ? await readInput('-', t) : await readUsageLog(target, t);
+    const report = conform(text, named === undefined ? {} : { contract: named });
+    if (boolFlag(args, 'json')) {
+        console.log(JSON.stringify(report, null, 2));
+        if (!report.conforms)
+            process.exitCode = 1;
+        return;
+    }
+    console.log();
+    if (report.contract === null) {
+        console.log(c.red(t.conform.unrecognised(target)));
+        console.log(`  ${c.dim(wrap(report.because ?? '', 74, '    '))}`);
+        console.log();
+        process.exitCode = 1;
+        return;
+    }
+    console.log(c.bold(report.records === null
+        ? t.conform.heading(target, report.contract)
+        : t.conform.headingLog(target, report.contract, report.records)));
+    if (report.problems.length === 0) {
+        console.log(`  ${c.green(t.conform.conforms())}`);
+    }
+    else {
+        for (const problem of report.problems.slice(0, MAX_CONFORM_PROBLEMS)) {
+            console.log(`  ${c.red(t.conform.problem(problem.at, problem.kind, problem.detail))}`);
+        }
+        if (report.problems.length > MAX_CONFORM_PROBLEMS) {
+            console.log(`  ${c.dim(t.conform.moreProblems(report.problems.length - MAX_CONFORM_PROBLEMS))}`);
+        }
+        process.exitCode = 1;
+    }
+    if (report.unavailable.length > 0) {
+        console.log();
+        console.log(c.bold(t.conform.unavailableHeading()));
+        for (const gap of report.unavailable) {
+            console.log(`  ${c.dim(wrap(t.conform.unavailable(gap.finding, gap.because, gap.unlockedBy), 74, '    '))}`);
+        }
+        // Said out loud, because the exit code says it silently and somebody
+        // reading a red-and-yellow screen will assume both halves gated.
+        console.log(`  ${c.dim(wrap(t.conform.unavailableNeverGates(), 74, '    '))}`);
+    }
+    console.log();
+}
 function commandModels(t, pricing) {
     const n = (value) => value.toLocaleString(t.numberLocale);
     const col = t.models.columns;
@@ -2082,36 +2168,36 @@ function parseWhen(args, flag, endOfDay, t, now) {
  */
 async function commandServe(args, config, pricing, t) {
     const root = process.cwd();
-    const limitUsd = config.spend?.maxUsd;
     const { resolved } = await readStore(root);
-    const measured = resolved.records.length > 0;
     /**
-     * The window the measurement covers, carried into every answer.
+     * The live budget, from `budgetPositions` — the same number `store` prints
+     * and the same one the MCP guard consults.
      *
-     * The position is read once at start, so a caller has to be able to see how
-     * old it is. A null window here would let a figure from last month read as
-     * current, which is the staleness this endpoint is otherwise honest about.
+     * **This used to read `spend.maxUsd` against the whole store**, which is a
+     * per-log gate compared against however much history the store happened to
+     * hold. A year of records against a monthly limit reported as a budget
+     * position, with a straight face and no way for a caller to tell. Same
+     * units, different denominators, and the two surfaces disagreed by exactly
+     * as much history as the machine had. `spend.monthlyUsd` is the key for a
+     * calendar month and nothing infers one key from the other: a repository
+     * with a per-log gate and no monthly budget has no monthly position, and
+     * this says so rather than picking a number that is the right shape.
      */
-    const window = measured
-        ? {
-            fromMs: Math.min(...resolved.records.map((record) => record.fromMs)),
-            toMs: Math.max(...resolved.records.map((record) => record.toMs)),
-        }
-        : null;
-    const report = bucketedProfile({
-        provider: 'store',
-        granularity: 'bucketed',
-        buckets: bucketsFromRecords(resolved.records),
-        window,
-        gaps: [],
-        unavailable: [],
-    }, { catalogue: pricing });
+    const budget = budgetPositions(resolved.records, config.spend, { catalogue: pricing });
+    const standing = budget.positions[0] ?? null;
+    const limitUsd = config.spend?.monthlyUsd;
+    const measured = standing !== null && standing.coverage !== 'none';
     const server = buildServer({
         catalogue: pricing,
         position: () => ({
-            consumedUsd: measured ? report.total.totalUsd : undefined,
+            // Nothing measured inside the period is `undefined`, never zero: the
+            // endpoint's `cannot-tell` exists for exactly this, and a $0 consumed
+            // would be the healthiest-looking budget a dead store can produce.
+            consumedUsd: measured ? standing.consumedUsd : undefined,
             limitUsd,
-            window: report.span,
+            // The period, not the store's span. A caller judging staleness needs to
+            // know which month the figure is about.
+            window: standing === null ? null : { fromMs: standing.period.fromMs, toMs: standing.period.toMs },
         }),
     });
     const socket = stringFlag(args, 'socket');
@@ -2123,7 +2209,10 @@ async function commandServe(args, config, pricing, t) {
     const where = await listen(server, socket !== undefined ? { socket } : { port });
     console.log(c.bold(t.serve.listening(where)));
     console.log(`  ${c.dim(wrap(t.serve.loopbackOnly(), 74, '    '))}`);
-    console.log(`  ${c.dim(wrap(measured ? t.serve.measuredFrom(formatUsd(report.total.totalUsd)) : t.serve.nothingMeasured(STORE_DIR), 74, '    '))}`);
+    console.log(`  ${c.dim(wrap(measured ? t.serve.measuredFrom(formatUsd(standing.consumedUsd)) : t.serve.nothingMeasured(STORE_DIR), 74, '    '))}`);
+    if (standing !== null && standing.coverage === 'partial') {
+        console.log(`  ${c.yellow(wrap(t.serve.partialCoverage(standing.measuredDays, standing.elapsedDays, standing.period.id), 74, '    '))}`);
+    }
     if (limitUsd === undefined) {
         console.log(`  ${c.dim(wrap(t.serve.noBudget(), 74, '    '))}`);
     }
@@ -2376,6 +2465,51 @@ async function commandStore(args, config, pricing, t) {
     }
     const keepDays = config.store?.keepDays;
     console.log(`  ${c.dim(wrap(keepDays === undefined ? t.store.noRetention() : t.store.retention(String(keepDays)), 74, '    '))}`);
+    /**
+     * The live budget, printed here because this is where the measurement lives.
+     *
+     * The same call `serve` makes and the same call the MCP guard makes, so the
+     * three cannot disagree about how much of the month is gone — which is the
+     * whole point of the number existing in one place.
+     */
+    renderBudget(budgetPositions(resolved.records, config.spend, { catalogue: pricing }), t, n);
+}
+/**
+ * One budget standing, rendered.
+ *
+ * Coverage before the money, deliberately. A reader who sees "$61 of $100"
+ * first has already formed a view by the time they reach "over three of
+ * nineteen elapsed days", and the second sentence has to undo the first.
+ */
+function renderBudget(report, t, n) {
+    const standing = report.positions[0];
+    if (standing === undefined) {
+        if (report.unmeasuredScopes.length > 0) {
+            console.log();
+            console.log(`  ${c.dim(wrap(t.store.budgetScopesUnmeasured(report.unmeasuredScopes.length), 74, '    '))}`);
+        }
+        return;
+    }
+    console.log();
+    console.log(c.bold(t.store.budgetHeading(standing.period.id)));
+    if (standing.coverage === 'none') {
+        // Nothing measured is never rendered as nothing spent. A dead store and a
+        // quiet month produce the same zero, and only one of them is good news.
+        console.log(`  ${c.red(wrap(t.store.budgetNothingMeasured(standing.elapsedDays), 74, '    '))}`);
+        return;
+    }
+    if (standing.coverage === 'partial') {
+        console.log(`  ${c.yellow(wrap(t.store.budgetPartial(standing.measuredDays, standing.elapsedDays, standing.unmeasuredDays.join(', ')), 74, '    '))}`);
+    }
+    const share = standing.burn.consumedShare;
+    console.log(`  ${t.store.budgetStanding(formatUsd(standing.consumedUsd), formatUsd(standing.limitUsd), share === null ? '—' : `${Math.round(share * 100)}%`, n(standing.measuredDays), n(standing.period.days))}`);
+    const line = t.store.budgetShape(standing.burn.shape, Math.round(standing.burn.elapsedShare * 100), standing.coverage);
+    console.log(`  ${standing.verdict === 'over' ? c.red(line) : c.dim(wrap(line, 74, '    '))}`);
+    // Only where there is a shape to disclaim. "That is a shape, not a forecast"
+    // under "nothing to compare against" is a disclaimer about nothing.
+    if (standing.burn.shape !== 'cannot-tell') {
+        console.log(`  ${c.dim(wrap(t.store.budgetNeverForecast(), 74, '    '))}`);
+    }
 }
 /**
  * `trazum connect <provider>` — the bill, read from the provider.
@@ -6231,6 +6365,9 @@ async function main() {
         case 'models':
             commandModels(t, pricing);
             break;
+        case 'conform':
+            await commandConform(args, t);
+            break;
         case 'init':
             await commandInit(args, config, pricing, t);
             break;