@trazum/cli 1.65.0 → 1.67.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/serve.d.ts CHANGED
@@ -23,7 +23,7 @@
23
23
  * into a hot path.
24
24
  */
25
25
  import type { Server } from 'node:http';
26
- import type { PricingCatalogue } from '@trazum/core';
26
+ import type { LimitsConfig, MeasuredPosition, PricingCatalogue, WaiveEntry } from '@trazum/core';
27
27
  /** Compiled in. See the module note: this is the inbound SSRF posture. */
28
28
  export declare const BIND_HOST = "127.0.0.1";
29
29
  export declare const DEFAULT_PORT = 7317;
@@ -54,6 +54,18 @@ export interface ServeContext {
54
54
  toMs: number;
55
55
  } | null;
56
56
  };
57
+ /** The `limits` block, when the config carries one. */
58
+ limits?: LimitsConfig;
59
+ /**
60
+ * The measured position for one call's scopes — from an index built once
61
+ * at start, same staleness posture as `position`.
62
+ */
63
+ measured?: (call: {
64
+ label?: string;
65
+ session?: string;
66
+ }) => MeasuredPosition;
67
+ /** The config's `waive` list — a silenced limit answers within, on the record. */
68
+ waivers?: readonly WaiveEntry[];
57
69
  }
58
70
  export declare function buildServer(context: ServeContext): Server;
59
71
  export interface ListenTarget {
@@ -1 +1 @@
1
- {"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAmB,MAAM,EAAkB,MAAM,WAAW,CAAC;AAEzE,OAAO,KAAK,EAAc,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEjE,0EAA0E;AAC1E,eAAO,MAAM,SAAS,cAAc,CAAC;AAErC,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,UAAY,CAAC;AAExC,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,gBAAgB,CAAC;IAC5B;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAAE,CAAC;CAC/G;AAyBD,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CA8CzD;AAED,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAa5E"}
1
+ {"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAmB,MAAM,EAAkB,MAAM,WAAW,CAAC;AAEzE,OAAO,KAAK,EAAc,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE7G,0EAA0E;AAC1E,eAAO,MAAM,SAAS,cAAc,CAAC;AAErC,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,UAAY,CAAC;AAExC,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,gBAAgB,CAAC;IAC5B;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;KAAE,CAAC;IAC9G,uDAAuD;IACvD,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,gBAAgB,CAAC;IAC5E,kFAAkF;IAClF,OAAO,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CACjC;AAyBD,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CA+FzD;AAED,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAa5E"}
package/dist/serve.js CHANGED
@@ -23,7 +23,7 @@
23
23
  * into a hot path.
24
24
  */
25
25
  import { createServer } from 'node:http';
26
- import { answerCost } from '@trazum/core';
26
+ import { answerCost, judgeLimits } from '@trazum/core';
27
27
  /** Compiled in. See the module note: this is the inbound SSRF posture. */
28
28
  export const BIND_HOST = '127.0.0.1';
29
29
  export const DEFAULT_PORT = 7317;
@@ -87,14 +87,59 @@ export function buildServer(context) {
87
87
  return;
88
88
  }
89
89
  const position = context.position();
90
- const answer = answerCost({
90
+ const call = {
91
91
  model: typeof payload.model === 'string' ? payload.model : undefined,
92
92
  inputTokens: typeof payload.inputTokens === 'number' ? payload.inputTokens : undefined,
93
93
  outputTokens: typeof payload.outputTokens === 'number' ? payload.outputTokens : undefined,
94
- basis: payload.basis === 'heuristic' ? 'heuristic' : 'token-count',
95
- ...position,
96
- }, { catalogue: context.catalogue });
97
- send(response, 200, answer);
94
+ basis: (payload.basis === 'heuristic' ? 'heuristic' : 'token-count'),
95
+ /**
96
+ * `label` and `session` scope the limits judgement and nothing else.
97
+ * The session value is used to look up measured spend and is never
98
+ * echoed back — the answer's judgement names the scope, not the key.
99
+ */
100
+ label: typeof payload.label === 'string' && payload.label !== '' ? payload.label : undefined,
101
+ session: typeof payload.session === 'string' && payload.session !== '' ? payload.session : undefined,
102
+ };
103
+ let answer;
104
+ let policy;
105
+ try {
106
+ answer = answerCost({
107
+ model: call.model,
108
+ inputTokens: call.inputTokens,
109
+ outputTokens: call.outputTokens,
110
+ basis: call.basis,
111
+ ...position,
112
+ }, { catalogue: context.catalogue });
113
+ /**
114
+ * The limits policy, judged by the same function the gateway and the
115
+ * spend guard call — one judge, three doors. Always present: absent
116
+ * config answers `no-policy` rather than omitting the field, because
117
+ * a missing field and a judged absence are different answers.
118
+ */
119
+ policy = judgeLimits(context.limits, context.measured?.({
120
+ ...(call.label === undefined ? {} : { label: call.label }),
121
+ ...(call.session === undefined ? {} : { session: call.session }),
122
+ }) ?? { dayUsd: null, sessionUsd: null, labelUsd: null }, call, {
123
+ catalogue: context.catalogue,
124
+ ...(context.waivers === undefined ? {} : { waivers: context.waivers }),
125
+ });
126
+ }
127
+ catch (error) {
128
+ /*
129
+ The core refuses a figure that cannot mean what it says — a
130
+ negative token count, most importantly, because a negative estimate
131
+ lowers the projected spend and buys an approval. Before this catch
132
+ existed the refusal was an uncaught throw inside the request
133
+ handler: `{"inputTokens": -5}` took the whole oracle down. A bad
134
+ figure is the caller's error, and it gets the caller's status code.
135
+ */
136
+ send(response, 400, {
137
+ error: 'bad-request',
138
+ detail: error instanceof Error ? error.message : 'unjudgeable figures',
139
+ });
140
+ return;
141
+ }
142
+ send(response, 200, { ...answer, policy });
98
143
  })();
99
144
  });
100
145
  }
package/dist/serve.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"serve.js","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"serve.js","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trazum/cli",
3
- "version": "1.65.0",
3
+ "version": "1.67.0",
4
4
  "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
5
5
  "license": "MIT",
6
6
  "author": "David Mu\u00f1oz Rey",
@@ -37,7 +37,7 @@
37
37
  "prepublishOnly": "npm run build && npm test"
38
38
  },
39
39
  "dependencies": {
40
- "@trazum/core": "1.65.0"
40
+ "@trazum/core": "1.67.0"
41
41
  },
42
42
  "devDependencies": {
43
43
  "@types/node": "^26.2.0",
@@ -35,7 +35,15 @@ import { once } from 'node:events';
35
35
  import { createServer } from 'node:http';
36
36
  import type { IncomingMessage, Server, ServerResponse } from 'node:http';
37
37
  import { estimateTokens, gatewayDecision, streamingUsageReader, usageFromResponse } from '@trazum/core';
38
- import type { GatewayDecision, GatewayPolicy, GatewayStanding, PricingCatalogue } from '@trazum/core';
38
+ import type {
39
+ GatewayDecision,
40
+ GatewayPolicy,
41
+ GatewayStanding,
42
+ LimitsConfig,
43
+ MeasuredPosition,
44
+ PricingCatalogue,
45
+ WaiveEntry,
46
+ } from '@trazum/core';
39
47
 
40
48
  /** Compiled in. See the module note. */
41
49
  export const BIND_HOST = '127.0.0.1';
@@ -179,6 +187,15 @@ export interface GatewayContext {
179
187
  policy: GatewayPolicy;
180
188
  /** Where the budget stands, refreshed by the caller — never read per request. */
181
189
  standing: () => GatewayStanding | null;
190
+ /** The `limits` block, when the config carries one. */
191
+ limits?: LimitsConfig;
192
+ /**
193
+ * The measured position for one call's scopes — from an index built once
194
+ * at start, like `standing`. Never a file read in the request path.
195
+ */
196
+ position?: (call: { label?: string; session?: string }) => MeasuredPosition;
197
+ /** The config's `waive` list — a silenced limit forwards, on the record. */
198
+ waivers?: readonly WaiveEntry[];
182
199
  /**
183
200
  * Called after a forwarded call returns, with the provider's own counts.
184
201
  *
@@ -250,6 +267,7 @@ function describe(body: string, provider: string, modelFromPath: string | null):
250
267
  inputTokens: number | null;
251
268
  maxOutputTokens: number | null;
252
269
  label: string | null;
270
+ session: string | null;
253
271
  } | null {
254
272
  let parsed: unknown;
255
273
  try {
@@ -307,14 +325,26 @@ function describe(body: string, provider: string, modelFromPath: string | null):
307
325
  * workload they never named.
308
326
  */
309
327
  label: labelOf(request),
328
+ /**
329
+ * `metadata.trazum_session` — the same seam as the label, for the same
330
+ * reason: a per-session ceiling can only bind conversations that name
331
+ * themselves, and inferring one would attribute spend to a conversation
332
+ * nobody declared. The value is used to judge and never forwarded,
333
+ * recorded, or printed.
334
+ */
335
+ session: metadataField(request, 'trazum_session'),
310
336
  };
311
337
  }
312
338
 
313
339
  function labelOf(request: Record<string, unknown>): string | null {
340
+ return metadataField(request, 'trazum_label');
341
+ }
342
+
343
+ function metadataField(request: Record<string, unknown>, key: string): string | null {
314
344
  const metadata = request.metadata;
315
345
  if (typeof metadata !== 'object' || metadata === null || Array.isArray(metadata)) return null;
316
- const label = (metadata as Record<string, unknown>).trazum_label;
317
- return typeof label === 'string' && label.trim() !== '' ? label : null;
346
+ const value = (metadata as Record<string, unknown>)[key];
347
+ return typeof value === 'string' && value.trim() !== '' ? value : null;
318
348
  }
319
349
 
320
350
  /** The refusal, as the caller's SDK will receive it. */
@@ -329,6 +359,9 @@ function refusalBody(decision: Extract<GatewayDecision, { kind: 'refuse' }>): st
329
359
  standing: decision.standing,
330
360
  estimatedUsd: decision.estimatedUsd,
331
361
  alternatives: decision.alternatives,
362
+ // The limits policy, judged by the same function every door calls —
363
+ // the 402 body carries the judgement, not a paraphrase of it.
364
+ policy: decision.policy,
332
365
  },
333
366
  null,
334
367
  2,
@@ -379,7 +412,20 @@ export function buildGateway(context: GatewayContext): Server {
379
412
  const decision = gatewayDecision(
380
413
  { provider: context.provider, ...described },
381
414
  context.standing(),
382
- { catalogue: context.catalogue, policy: context.policy },
415
+ {
416
+ catalogue: context.catalogue,
417
+ policy: context.policy,
418
+ ...(context.limits === undefined ? {} : { limits: context.limits }),
419
+ ...(context.waivers === undefined ? {} : { waivers: context.waivers }),
420
+ ...(context.position === undefined
421
+ ? {}
422
+ : {
423
+ position: context.position({
424
+ ...(described.label === null ? {} : { label: described.label }),
425
+ ...(described.session === null ? {} : { session: described.session }),
426
+ }),
427
+ }),
428
+ },
383
429
  );
384
430
 
385
431
  if (decision.kind === 'refuse') {
package/src/html.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { UNLABELLED, formatUsd, sharesOf } from '@trazum/core';
2
- import type { RollupDocument, UsageBreakdown } from '@trazum/core';
2
+ import type { PositionDocument, RollupDocument, UsageBreakdown } from '@trazum/core';
3
3
  import type { CliMessages } from './i18n/index.js';
4
4
  import type { ProfileMarkdownInput } from './markdown.js';
5
5
  import { dayOf, spanDays } from './time.js';
@@ -341,3 +341,79 @@ export function renderRollupHtml(document: RollupDocument, t: CliMessages): stri
341
341
  parts,
342
342
  );
343
343
  }
344
+
345
+ /**
346
+ * The position as one self-contained page — the third door the 1.64 arc's
347
+ * discipline applies to: the input is the position document itself, the one
348
+ * `--json` prints and `conform` checks, so the page cannot disagree with
349
+ * the data. Every sentence is the terminal's own, through the same message
350
+ * catalogue, which is what keeps the two surfaces saying the same thing in
351
+ * the same words. The caveat block — what could not be measured, what is
352
+ * deliberately unanswered, the records nobody can price — renders BEFORE
353
+ * the positions, because a forwarded page gets cropped from the bottom.
354
+ */
355
+ export function renderPositionHtml(document: PositionDocument, t: CliMessages): string {
356
+ const scopeName = (entry: { scope: string; label: string | null }): string =>
357
+ entry.scope === 'month'
358
+ ? t.position.scopeMonth()
359
+ : entry.scope === 'day'
360
+ ? t.position.scopeDay()
361
+ : t.position.scopeLabel(entry.label ?? '');
362
+
363
+ const parts: string[] = [];
364
+ parts.push(`<h1>${esc(t.position.heading(document.month.id))}</h1>`);
365
+ parts.push(`<p class="muted">${esc(t.position.source())}</p>`);
366
+
367
+ const caveats = [
368
+ ...document.unmeasured.map((entry) => t.position.unmeasured(scopeName(entry), t.position.why(entry.why))),
369
+ ...document.cannotSay,
370
+ ...(document.unpricedRecords > 0 ? [t.position.unpriced(document.unpricedRecords)] : []),
371
+ ];
372
+ if (caveats.length > 0) {
373
+ parts.push(
374
+ `<div class="caveats"><h2>${esc(t.position.cannotSayHeading())}</h2><ul>${caveats
375
+ .map((line) => `<li>${esc(line)}</li>`)
376
+ .join('')}</ul></div>`,
377
+ );
378
+ }
379
+
380
+ parts.push(
381
+ `<ul class="findings">${document.positions
382
+ .map((position) => {
383
+ const name = scopeName(position);
384
+ const sentence =
385
+ position.verdict === 'cannot-tell'
386
+ ? t.position.cannotTell(name)
387
+ : position.verdict === 'over'
388
+ ? t.position.over(
389
+ name,
390
+ formatUsd(position.measuredUsd),
391
+ formatUsd(position.limitUsd),
392
+ formatUsd(-position.remainingUsd),
393
+ )
394
+ : t.position.within(
395
+ name,
396
+ formatUsd(position.measuredUsd),
397
+ formatUsd(position.limitUsd),
398
+ formatUsd(position.remainingUsd),
399
+ position.daysMeasured,
400
+ position.daysElapsed,
401
+ );
402
+ const distance =
403
+ position.distance === null
404
+ ? ''
405
+ : `<div class="muted">${esc(
406
+ t.position.distance(
407
+ position.distance.daysAway.toFixed(1),
408
+ formatUsd(position.distance.usdPerDay),
409
+ position.distance.overDays,
410
+ ),
411
+ )}</div>`;
412
+ return `<li>${esc(sentence)}${distance}</li>`;
413
+ })
414
+ .join('')}</ul>`,
415
+ );
416
+
417
+ parts.push(`<footer>${esc(t.html.footer())}</footer>`);
418
+ return page(t.position.heading(document.month.id), t.locale, parts);
419
+ }
package/src/i18n/en.ts CHANGED
@@ -58,6 +58,7 @@ ${bold('USAGE')}
58
58
  trazum conform <file|-> [--contract <name>]
59
59
  trazum schema <contract>
60
60
  trazum rollup <document...|dir> [--json] [--html-out <file>]
61
+ trazum position <usage.jsonl>
61
62
  trazum pulse [--max-stale-hours <n>]
62
63
  trazum bench [--workload <id>] [--record <file>] [--against <file> --max-ratio <n>] [--json]
63
64
  trazum write [--answers <file>] [--json] [-o <file>]
@@ -135,6 +136,19 @@ ${bold('OPTIONS FOR write')}
135
136
  --calls <n> Calls per month, for the estimate.
136
137
  --avg-output <n> Average output tokens per call, for the estimate.
137
138
 
139
+ ${bold('OPTIONS FOR position')}
140
+ --html-out <file> The position as one self-contained page — the
141
+ same sentences the terminal prints, caveats
142
+ first, for the person who does not run CLIs.
143
+ --json The position document, contract-checked like
144
+ everything (\`--contract position\`).
145
+
146
+ Where the month stands against every configured ceiling, measured from the
147
+ named log alone with the denominator on every figure. The distance line is
148
+ division on the past, labelled as such, and absent under the seven-day
149
+ floor, on an over, and on a zero rate: never a forecast, and no field in
150
+ the document names a date.
151
+
138
152
  ${bold('OPTIONS FOR pulse')}
139
153
  --max-stale-hours <n> Exit 1 when something that runs here has not run
140
154
  in over n hours. Without it, the ages are
@@ -212,6 +226,10 @@ ${bold('OPTIONS FOR gateway')}
212
226
  What happens when the gateway cannot judge a call
213
227
  — no budget, nothing measured, an unpriced model.
214
228
  --port <n> | --socket <p> Where to listen. Loopback only, always.
229
+ --log <usage.jsonl> The usage log the limits policy is measured
230
+ against, read once at start — same flag as
231
+ serve's, same reason: label and session spend
232
+ live in a usage log, not in the store.
215
233
 
216
234
  Stands between your SDK and the provider, speaking their wire format, so no
217
235
  code changes. Usage is measured from the provider's own response as it comes
@@ -431,6 +449,13 @@ ${bold('OPTIONS FOR check')}
431
449
  --baseline Gate on the recorded cost baseline. On by default whenever
432
450
  the config declares one, so CI needs no argument; the useful
433
451
  spelling is --no-baseline, which skips it for one run.
452
+ --files-from <file|-> Check only the files listed, one path per line — the shape
453
+ git diff --name-only produces, so a pre-commit hook is one
454
+ pipe: git diff --cached --name-only | trazum check --files-from -
455
+ Non-prompt paths and deletions are dropped and counted out
456
+ loud; a list with nothing checkable passes. Budgets apply
457
+ per file as always; the baseline needs the whole repository
458
+ and is skipped, and says so.
434
459
 
435
460
  Built for CI: exits with code 1 when the prompt busts the budget, so a
436
461
  template that grows unchecked breaks the build instead of the bill.
@@ -569,6 +594,11 @@ ${bold('OPTIONS FOR plan')}
569
594
  ${bold('OPTIONS FOR serve')}
570
595
  --port <n> Port on 127.0.0.1. Default: 7317.
571
596
  --socket <path> Listen on a Unix socket instead of a port.
597
+ --log <usage.jsonl> The usage log the limits policy is measured
598
+ against, read once at start. Per-label and
599
+ per-session spend live in a usage log, not in
600
+ the store; without this, every ceiling in
601
+ "limits" answers cannot-tell.
572
602
 
573
603
  Answers the two questions that matter at call time — what will this cost,
574
604
  and is there budget left — in single-digit milliseconds, so an agent or a
@@ -778,6 +808,13 @@ ${bold('CONFIG FILE')}
778
808
  spend { "maxUsd": 200, "byLabel": { "chat": 40 } } — money budgets for
779
809
  "trazum profile", in dollars. A budgeted label with no calls in
780
810
  the log is reported as not measured, never as a pass
811
+ limits { "dayUsd": 25, "sessionUsd": 1.5, "byLabel": { "chat": 5 } } —
812
+ the enforcement policy: USD ceilings judged before a call is
813
+ made, at whichever door it arrives (the gateway's 402, "serve",
814
+ spend_guard over MCP). Separate from "spend" because a report
815
+ gate and a call refusal are read at different moments; every
816
+ ceiling must be a positive number, because a ceiling of 0 is an
817
+ outage written as a policy
781
818
  owners { "patterns": { "payments": ["billing-*"] },
782
819
  "shared": { "search": { "payments": 0.6, "support": 0.4 } },
783
820
  "budgets": { "payments": 400 } } — whose budget each workload
@@ -1561,6 +1598,35 @@ ${bold('EXAMPLES')}
1561
1598
  },
1562
1599
  },
1563
1600
 
1601
+ position: {
1602
+ heading: (month) => `Where ${month} stands, measured`,
1603
+ scopeMonth: () => 'the month',
1604
+ scopeDay: () => 'today',
1605
+ scopeLabel: (label) => `"${label}"`,
1606
+ within: (scope, measured, limit, remaining, days, elapsed) =>
1607
+ `${scope}: ${measured} of ${limit} measured — ${remaining} left (${days} of ${elapsed} elapsed days measured)`,
1608
+ over: (scope, measured, limit, overBy) =>
1609
+ `${scope}: over — ${measured} measured against ${limit}, ${overBy} past the ceiling`,
1610
+ cannotTell: (scope) => `${scope}: cannot tell — nothing measured in this window`,
1611
+ distance: (days, rate, overDays) =>
1612
+ `at ${rate}/day over ${overDays} measured days, the ceiling is ${days} days away — division on the past, not a forecast`,
1613
+ unmeasuredHeading: () => 'Configured and not measurable from this log',
1614
+ unmeasured: (scope, why) => `${scope}: ${why}`,
1615
+ why: (reason) =>
1616
+ reason === 'no-clock'
1617
+ ? 'no record carries a timestamp, so no window can be measured'
1618
+ : reason === 'no-labels'
1619
+ ? 'no record carries a label, so per-label spend is unknowable here'
1620
+ : reason === 'nothing-recorded'
1621
+ ? 'the log is empty — nothing was recorded'
1622
+ : 'the log records labels and has never seen this one this month — possibly renamed, possibly idle, and neither is "under budget"',
1623
+ cannotSayHeading: () => 'What this deliberately does not answer',
1624
+ unpriced: (count) =>
1625
+ `${count} record(s) name a model the catalogue cannot price. They contribute nothing to any figure above — money nobody can see, said here rather than hidden.`,
1626
+ source: () =>
1627
+ 'Measured from this log alone, priced record by record. The store\'s provider-billed monthly standing is a different measurement — "trazum store" prints it — and the two are never merged into one figure.',
1628
+ noLog: () => 'position needs a usage log: trazum position usage.jsonl',
1629
+ },
1564
1630
  pulse: {
1565
1631
  heading: () => 'Did the things that are supposed to run, run?',
1566
1632
  kind: (kind) => {
@@ -1996,6 +2062,10 @@ ${bold('EXAMPLES')}
1996
2062
  noBudget: () => '(no budget)',
1997
2063
  walkTruncated: () =>
1998
2064
  'Stopped early: the directory is larger than the walk limit, so this is not the whole picture.',
2065
+ filesFromSummary: (checked, listed, dropped) =>
2066
+ `Checking ${checked} of ${listed} listed file(s) — ${dropped} dropped: not a prompt extension, ignored by config, or no longer on disk.`,
2067
+ filesFromNoBaseline: () =>
2068
+ 'The baseline gate is skipped under --files-from: it compares the whole repository against the committed record, and a partial list would read as removals. Budgets are checked per file as always; run "trazum check ." for the baseline.',
1999
2069
  exactCountsCost: (files) =>
2000
2070
  `Counting ${files} ${files === 1 ? 'file' : 'files'} through the API, one call each. This takes a moment.`,
2001
2071
  },
@@ -2460,6 +2530,10 @@ ${bold('EXAMPLES')}
2460
2530
 
2461
2531
  serve: {
2462
2532
  listening: (where) => `Answering on ${where}`,
2533
+ limitsNoLog: () =>
2534
+ 'A limits policy is configured and no --log was given, so every ceiling will answer cannot-tell: per-label and per-session spend live in a usage log, not in the store. Point --log at your usage log to make the ceilings judgeable.',
2535
+ limitsUnpriced: (count) =>
2536
+ `${count} record(s) in the --log name a model the catalogue cannot price. They contribute nothing to any measured figure — money the limits policy cannot see, said here rather than hidden.`,
2463
2537
  loopbackOnly: () =>
2464
2538
  'Loopback only, and there is no flag to change that: this holds your spend, your model mix and your budgets, and would answer whoever asked. There is no auth for the same reason — a token checked over loopback is theatre.',
2465
2539
  measuredFrom: (usd) =>
package/src/i18n/es.ts CHANGED
@@ -45,6 +45,7 @@ ${bold('USO')}
45
45
  trazum conform <fichero|-> [--contract <nombre>]
46
46
  trazum schema <contrato>
47
47
  trazum rollup <documento...|dir> [--json] [--html-out <fichero>]
48
+ trazum position <uso.jsonl>
48
49
  trazum pulse [--max-stale-hours <n>]
49
50
  trazum bench [--workload <id>] [--record <fichero>] [--against <fichero> --max-ratio <n>] [--json]
50
51
  trazum write [--answers <fichero>] [--json] [-o <fichero>]
@@ -124,6 +125,19 @@ ${bold('OPCIONES DE write')}
124
125
  --calls <n> Llamadas al mes, para la estimación.
125
126
  --avg-output <n> Tokens de salida por llamada, para la estimación.
126
127
 
128
+ ${bold('OPCIONES DE position')}
129
+ --html-out <fichero> La posición como una página autocontenida — las
130
+ mismas frases que imprime el terminal, caveats
131
+ primero, para quien no ejecuta CLIs.
132
+ --json El documento de posición, verificado por
133
+ contrato como todo (\`--contract position\`).
134
+
135
+ Dónde está el mes frente a cada techo configurado, medido solo desde el
136
+ log nombrado y con el denominador en cada cifra. La línea de distancia es
137
+ división sobre el pasado, etiquetada como tal, y ausente bajo el suelo de
138
+ siete días, con un techo superado o con tasa cero: nunca un pronóstico, y
139
+ ningún campo del documento nombra una fecha.
140
+
127
141
  ${bold('OPCIONES DE pulse')}
128
142
  --max-stale-hours <n> Sale con 1 cuando algo que corre aquí lleva más
129
143
  de n horas sin correr. Sin esto, se informan las
@@ -204,6 +218,11 @@ ${bold('OPCIONES DE gateway')}
204
218
  juzgar una llamada — sin presupuesto, sin nada
205
219
  medido, un modelo sin precio.
206
220
  --port <n> | --socket <p> Dónde escuchar. Solo loopback, siempre.
221
+ --log <uso.jsonl> El log de uso contra el que se mide la política
222
+ de limits, leído una vez al arrancar — el mismo
223
+ flag que en serve, por la misma razón: el gasto
224
+ por etiqueta y sesión vive en un log de uso, no
225
+ en el almacén.
207
226
 
208
227
  Se pone entre tu SDK y el proveedor, hablando su formato, así que no hay
209
228
  cambios de código. El consumo se mide desde la propia respuesta del proveedor
@@ -431,6 +450,15 @@ ${bold('OPCIONES DE check')}
431
450
  --baseline Aplica la línea base registrada. Activo por defecto siempre
432
451
  que el config declare una, así CI no necesita argumentos; la
433
452
  forma útil es --no-baseline, que la omite en una ejecución.
453
+ --files-from <fichero|-> Comprueba solo los ficheros listados, una ruta por línea —
454
+ la forma que produce git diff --name-only, así que un hook
455
+ de pre-commit es una tubería:
456
+ git diff --cached --name-only | trazum check --files-from -
457
+ Las rutas que no son prompts y las eliminaciones se
458
+ descartan y se cuentan en voz alta; una lista sin nada
459
+ comprobable pasa. Los presupuestos aplican por fichero como
460
+ siempre; el baseline necesita el repositorio entero y se
461
+ omite, diciéndolo.
434
462
 
435
463
  Pensado para CI: sale con código 1 si el prompt supera el presupuesto,
436
464
  así una plantilla que crece sin control rompe la build en vez de la factura.
@@ -583,6 +611,11 @@ ${bold('OPCIONES DE plan')}
583
611
  ${bold('OPCIONES DE serve')}
584
612
  --port <n> Puerto en 127.0.0.1. Por defecto: 7317.
585
613
  --socket <ruta> Escucha en un socket Unix en vez de un puerto.
614
+ --log <uso.jsonl> El log de uso contra el que se mide la política
615
+ de limits, leído una vez al arrancar. El gasto
616
+ por etiqueta y por sesión vive en un log de uso,
617
+ no en el almacén; sin esto, cada techo de
618
+ "limits" responde cannot-tell.
586
619
 
587
620
  Responde las dos preguntas que importan en el momento de la llamada — cuánto
588
621
  va a costar esto y si queda presupuesto — en milisegundos de un solo dígito,
@@ -802,6 +835,13 @@ ${bold('FICHERO DE CONFIGURACIÓN')}
802
835
  spend { "maxUsd": 200, "byLabel": { "chat": 40 } } — presupuestos en
803
836
  dólares para "trazum profile". Una etiqueta con presupuesto y sin
804
837
  llamadas se informa como no medida, nunca como aprobada
838
+ limits { "dayUsd": 25, "sessionUsd": 1.5, "byLabel": { "chat": 5 } } —
839
+ la política de aplicación: techos en USD juzgados antes de hacer
840
+ una llamada, en la puerta a la que llegue (el 402 del gateway,
841
+ "serve", spend_guard por MCP). Separado de "spend" porque una
842
+ puerta de informe y un rechazo de llamada se leen en momentos
843
+ distintos; cada techo debe ser un número positivo, porque un
844
+ techo de 0 es una caída escrita como política
805
845
  owners { "patterns": { "payments": ["billing-*"] },
806
846
  "shared": { "search": { "payments": 0.6, "support": 0.4 } },
807
847
  "budgets": { "payments": 400 } } — de quién es el presupuesto de
@@ -1572,6 +1612,35 @@ ${bold('EJEMPLOS')}
1572
1612
  },
1573
1613
  },
1574
1614
 
1615
+ position: {
1616
+ heading: (month) => `Dónde está ${month}, medido`,
1617
+ scopeMonth: () => 'el mes',
1618
+ scopeDay: () => 'hoy',
1619
+ scopeLabel: (label) => `«${label}»`,
1620
+ within: (scope, measured, limit, remaining, days, elapsed) =>
1621
+ `${scope}: ${measured} de ${limit} medidos — quedan ${remaining} (${days} de ${elapsed} días transcurridos con medición)`,
1622
+ over: (scope, measured, limit, overBy) =>
1623
+ `${scope}: superado — ${measured} medidos contra ${limit}, ${overBy} por encima del techo`,
1624
+ cannotTell: (scope) => `${scope}: no se puede saber — nada medido en esta ventana`,
1625
+ distance: (days, rate, overDays) =>
1626
+ `a ${rate}/día sobre ${overDays} días medidos, el techo queda a ${days} días — división sobre el pasado, no un pronóstico`,
1627
+ unmeasuredHeading: () => 'Configurado y no medible desde este log',
1628
+ unmeasured: (scope, why) => `${scope}: ${why}`,
1629
+ why: (reason) =>
1630
+ reason === 'no-clock'
1631
+ ? 'ningún registro lleva marca de tiempo, así que no se puede medir ninguna ventana'
1632
+ : reason === 'no-labels'
1633
+ ? 'ningún registro lleva etiqueta, así que el gasto por etiqueta es incognoscible aquí'
1634
+ : reason === 'nothing-recorded'
1635
+ ? 'el log está vacío — no se registró nada'
1636
+ : 'el log registra etiquetas y no ha visto esta en todo el mes — quizá renombrada, quizá parada, y ninguna de las dos es «dentro del presupuesto»',
1637
+ cannotSayHeading: () => 'Lo que deliberadamente no responde',
1638
+ unpriced: (count) =>
1639
+ `${count} registro(s) nombran un modelo que el catálogo no puede tasar. No aportan nada a ninguna cifra de arriba — dinero que nadie ve, dicho aquí en vez de escondido.`,
1640
+ source: () =>
1641
+ 'Medido solo desde este log, registro a registro. La posición mensual facturada por el proveedor que guarda el almacén es otra medición — la imprime «trazum store» — y las dos nunca se funden en una cifra.',
1642
+ noLog: () => 'position necesita un log de uso: trazum position uso.jsonl',
1643
+ },
1575
1644
  pulse: {
1576
1645
  heading: () => '¿Corrieron las cosas que tienen que correr?',
1577
1646
  kind: (kind) => {
@@ -2006,6 +2075,10 @@ ${bold('EJEMPLOS')}
2006
2075
  noBudget: () => '(sin presupuesto)',
2007
2076
  walkTruncated: () =>
2008
2077
  'Se ha parado antes de tiempo: el directorio supera el límite de recorrido, así que esto no es el cuadro completo.',
2078
+ filesFromSummary: (checked, listed, dropped) =>
2079
+ `Comprobando ${checked} de ${listed} fichero(s) listados — ${dropped} descartados: sin extensión de prompt, ignorados por la config, o ya no están en disco.`,
2080
+ filesFromNoBaseline: () =>
2081
+ 'La puerta de baseline se omite con --files-from: compara el repositorio entero contra el registro comprometido, y una lista parcial se leería como eliminaciones. Los presupuestos se comprueban por fichero como siempre; ejecuta «trazum check .» para el baseline.',
2009
2082
  exactCountsCost: (files) =>
2010
2083
  `Contando ${files} ${files === 1 ? 'fichero' : 'ficheros'} con la API, una llamada por cada uno. Esto tarda un momento.`,
2011
2084
  },
@@ -2469,6 +2542,10 @@ ${bold('EJEMPLOS')}
2469
2542
 
2470
2543
  serve: {
2471
2544
  listening: (where) => `Respondiendo en ${where}`,
2545
+ limitsNoLog: () =>
2546
+ 'Hay una política de limits configurada y no se dio --log, así que cada techo responderá cannot-tell: el gasto por etiqueta y por sesión vive en un log de uso, no en el almacén. Apunta --log a tu log de uso para que los techos sean juzgables.',
2547
+ limitsUnpriced: (count) =>
2548
+ `${count} registro(s) del --log nombran un modelo que el catálogo no puede tasar. No aportan nada a ninguna cifra medida — dinero que la política de limits no puede ver, dicho aquí en vez de escondido.`,
2472
2549
  loopbackOnly: () =>
2473
2550
  'Solo loopback, y no hay flag para cambiarlo: esto guarda tu gasto, tu mezcla de modelos y tus presupuestos, y le respondería a quien preguntara. No hay autenticación por la misma razón — un token comprobado sobre loopback es teatro.',
2474
2551
  measuredFrom: (usd) =>