@trazum/core 1.40.0 → 1.42.0

package/dist/store.d.ts

@@ -0,0 +1,134 @@
+/**
+ * A year of measured spend on disk, and not one prompt inside it.
+ *
+ * A connector that re-downloads a month every time it runs is a connector
+ * nobody leaves on, and `history` needs stored reports — which until now meant
+ * a human curating a directory of `--json` files. The store is where pulled
+ * usage lands so neither is true any more.
+ *
+ * **Pure, and in the core.** This module decides what a record *is*, when two
+ * records are the same record, and what a set of them adds up to. The
+ * filesystem lives in the CLI, the same split every other browser-safe module
+ * here keeps.
+ *
+ * **Convergence, not accumulation.** Re-pulling an overlapping window must not
+ * double the bill. Two records covering the same window, from the same
+ * provider, for the same model and grouping, are the *same fact restated* —
+ * the later pull wins, because a window pulled again is at worst as complete
+ * as it was. That makes overlapping pulls idempotent, which is what lets a
+ * scheduled job run every hour over a rolling day without inventing money.
+ *
+ * **Deduplication that cannot lie.** Two records the store cannot tell apart —
+ * a source that served no window, or no model — are kept as *two* and reported
+ * as possibly-double. Merging them on a guess makes a bill quietly smaller,
+ * and quietly smaller is the flattering direction this repository refuses
+ * everywhere it can occur.
+ */
+import type { UsageBucket } from './connector.js';
+/** Bump when the meaning of a field changes. Readers keep what they cannot read. */
+export declare const STORE_SCHEMA_VERSION = 1;
+/**
+ * One stored measurement.
+ *
+ * Short keys because a year of these is a file somebody has to keep, and the
+ * shape is documented rather than inferred from its own verbosity.
+ */
+export interface StoreRecord {
+    /** Schema version of this line, so an old reader keeps what it cannot parse. */
+    v: number;
+    provider: string;
+    fromMs: number;
+    toMs: number;
+    model: string;
+    /** null when the source serves no request count. Never zero for absent. */
+    calls: number | null;
+    input: number;
+    cacheRead: number;
+    write5m: number;
+    write1h: number;
+    /** False when the source reported writes without saying which TTL. */
+    ttlKnown: boolean;
+    output: number;
+    /**
+     * The account's own opaque identifiers — workspace, key, tier — as the
+     * provider served them.
+     *
+     * These are identifiers, not secrets: they name a workspace, not a way into
+     * it, and per-owner attribution needs them. Prompt text, completion text and
+     * credentials are never here, and the documentation says exactly what a
+     * store holds rather than leaving somebody to guess about their own file.
+     */
+    group: Record<string, string>;
+    /** When this record was pulled, which is how the later restatement wins. */
+    pulledAtMs: number;
+}
+/** What makes two records the same record. See the module note. */
+export declare function identityOf(record: StoreRecord): string;
+export interface ResolvedStore {
+    /** One record per identity, newest pull winning. */
+    records: StoreRecord[];
+    /**
+     * Records the store could not tell apart, kept in full rather than merged.
+     *
+     * Reported so a total built on them can be read for what it is: possibly
+     * counting the same spend twice, and saying so beats a smaller number
+     * nobody can check.
+     */
+    possiblyDouble: StoreRecord[];
+    /** Lines from a schema version this binary does not know, kept and counted. */
+    unknownVersion: number;
+}
+/**
+ * Collapses an append-only log into the current truth.
+ *
+ * Append-only on disk and last-wins at read time, rather than rewriting a file
+ * in place: a crash during a rewrite can lose a year, and a crash during an
+ * append loses the tail of one line.
+ */
+export declare function resolveStore(records: readonly StoreRecord[]): ResolvedStore;
+/** Turns a connector's buckets into records ready to append. */
+export declare function recordsFromBuckets(provider: string, buckets: readonly UsageBucket[], pulledAtMs: number): StoreRecord[];
+/** The reverse, so a stored month prices exactly as a fresh pull does. */
+export declare function bucketsFromRecords(records: readonly StoreRecord[]): UsageBucket[];
+export interface StoreInventory {
+    schemaVersion: 1;
+    /** Per provider, oldest first by the span it covers. */
+    providers: {
+        provider: string;
+        records: number;
+        span: {
+            fromMs: number;
+            toMs: number;
+        } | null;
+        /** null when no provider in the set serves request counts. */
+        calls: number | null;
+        models: string[];
+    }[];
+    totalRecords: number;
+    span: {
+        fromMs: number;
+        toMs: number;
+    } | null;
+    possiblyDouble: number;
+    unknownVersion: number;
+}
+export declare function storeInventory(resolved: ResolvedStore): StoreInventory;
+export interface PruneResult {
+    kept: StoreRecord[];
+    dropped: StoreRecord[];
+    /** The span the dropped records covered — what a reader loses by pruning. */
+    droppedSpan: {
+        fromMs: number;
+        toMs: number;
+    } | null;
+}
+/**
+ * Drops records whose window ended before the cutoff.
+ *
+ * Judged on `toMs`: a bucket that *ends* inside the retained period is
+ * retained whole, because half a bucket is a measurement of nothing. What goes
+ * is returned rather than counted, so the caller can say what went — silence
+ * about deleted measurements is the one thing a store must not do.
+ */
+export declare function pruneRecords(records: readonly StoreRecord[], cutoffMs: number): PruneResult;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD,oFAAoF;AACpF,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,CAAC,EAAE,MAAM,CAAC;IACV,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAQtD;AAYD,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB;;;;;;OAMG;IACH,cAAc,EAAE,WAAW,EAAE,CAAC;IAC9B,+EAA+E;IAC/E,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,aAAa,CA4B3E;AAED,gEAAgE;AAChE,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,UAAU,EAAE,MAAM,GACjB,WAAW,EAAE,CAiBf;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,WAAW,EAAE,CAcjF;AAMD,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,CAAC,CAAC;IACjB,wDAAwD;IACxD,SAAS,EAAE;QACT,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAC;QAC9C,8DAA8D;QAC9D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,MAAM,EAAE,MAAM,EAAE,CAAC;KAClB,EAAE,CAAC;IACJ,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,aAAa,GAAG,cAAc,CAuCtE;AAMD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,EAAE,CAAC;IACpB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,6EAA6E;IAC7E,WAAW,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACtD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,CAiB3F"}

package/dist/store.js

@@ -0,0 +1,177 @@
+/**
+ * A year of measured spend on disk, and not one prompt inside it.
+ *
+ * A connector that re-downloads a month every time it runs is a connector
+ * nobody leaves on, and `history` needs stored reports — which until now meant
+ * a human curating a directory of `--json` files. The store is where pulled
+ * usage lands so neither is true any more.
+ *
+ * **Pure, and in the core.** This module decides what a record *is*, when two
+ * records are the same record, and what a set of them adds up to. The
+ * filesystem lives in the CLI, the same split every other browser-safe module
+ * here keeps.
+ *
+ * **Convergence, not accumulation.** Re-pulling an overlapping window must not
+ * double the bill. Two records covering the same window, from the same
+ * provider, for the same model and grouping, are the *same fact restated* —
+ * the later pull wins, because a window pulled again is at worst as complete
+ * as it was. That makes overlapping pulls idempotent, which is what lets a
+ * scheduled job run every hour over a rolling day without inventing money.
+ *
+ * **Deduplication that cannot lie.** Two records the store cannot tell apart —
+ * a source that served no window, or no model — are kept as *two* and reported
+ * as possibly-double. Merging them on a guess makes a bill quietly smaller,
+ * and quietly smaller is the flattering direction this repository refuses
+ * everywhere it can occur.
+ */
+/** Bump when the meaning of a field changes. Readers keep what they cannot read. */
+export const STORE_SCHEMA_VERSION = 1;
+/** What makes two records the same record. See the module note. */
+export function identityOf(record) {
+    return [
+        record.provider,
+        record.fromMs,
+        record.toMs,
+        record.model,
+        JSON.stringify(record.group),
+    ].join('\n');
+}
+/**
+ * A record whose identity is not trustworthy enough to converge on.
+ *
+ * A window of zero length, or a record with no model, cannot be told apart
+ * from another like it. Those are kept whole and counted separately.
+ */
+function identifiable(record) {
+    return record.model !== '' && record.toMs > record.fromMs;
+}
+/**
+ * Collapses an append-only log into the current truth.
+ *
+ * Append-only on disk and last-wins at read time, rather than rewriting a file
+ * in place: a crash during a rewrite can lose a year, and a crash during an
+ * append loses the tail of one line.
+ */
+export function resolveStore(records) {
+    const byIdentity = new Map();
+    const possiblyDouble = [];
+    let unknownVersion = 0;
+    for (const record of records) {
+        if (record.v > STORE_SCHEMA_VERSION) {
+            unknownVersion += 1;
+            continue;
+        }
+        if (!identifiable(record)) {
+            possiblyDouble.push(record);
+            continue;
+        }
+        const key = identityOf(record);
+        const seen = byIdentity.get(key);
+        if (seen === undefined || record.pulledAtMs >= seen.pulledAtMs) {
+            byIdentity.set(key, record);
+        }
+    }
+    return {
+        records: [...byIdentity.values()].sort((a, b) => a.fromMs - b.fromMs || a.model.localeCompare(b.model)),
+        possiblyDouble,
+        unknownVersion,
+    };
+}
+/** Turns a connector's buckets into records ready to append. */
+export function recordsFromBuckets(provider, buckets, pulledAtMs) {
+    return buckets.map((bucket) => ({
+        v: STORE_SCHEMA_VERSION,
+        provider,
+        fromMs: bucket.fromMs,
+        toMs: bucket.toMs,
+        model: bucket.model,
+        calls: bucket.calls,
+        input: bucket.inputTokens,
+        cacheRead: bucket.cacheReadTokens,
+        write5m: bucket.cacheWrite5mTokens,
+        write1h: bucket.cacheWrite1hTokens,
+        ttlKnown: bucket.writeTtlKnown,
+        output: bucket.outputTokens,
+        group: bucket.group,
+        pulledAtMs,
+    }));
+}
+/** The reverse, so a stored month prices exactly as a fresh pull does. */
+export function bucketsFromRecords(records) {
+    return records.map((record) => ({
+        fromMs: record.fromMs,
+        toMs: record.toMs,
+        model: record.model,
+        calls: record.calls,
+        inputTokens: record.input,
+        cacheReadTokens: record.cacheRead,
+        cacheWrite5mTokens: record.write5m,
+        cacheWrite1hTokens: record.write1h,
+        writeTtlKnown: record.ttlKnown,
+        outputTokens: record.output,
+        group: record.group,
+    }));
+}
+export function storeInventory(resolved) {
+    const byProvider = new Map();
+    for (const record of resolved.records) {
+        const list = byProvider.get(record.provider) ?? [];
+        list.push(record);
+        byProvider.set(record.provider, list);
+    }
+    const providers = [...byProvider.entries()]
+        .map(([provider, records]) => {
+        const anyUnknown = records.some((r) => r.calls === null);
+        return {
+            provider,
+            records: records.length,
+            span: {
+                fromMs: Math.min(...records.map((r) => r.fromMs)),
+                toMs: Math.max(...records.map((r) => r.toMs)),
+            },
+            calls: anyUnknown ? null : records.reduce((sum, r) => sum + (r.calls ?? 0), 0),
+            models: [...new Set(records.map((r) => r.model))].sort(),
+        };
+    })
+        .sort((a, b) => a.provider.localeCompare(b.provider));
+    const all = resolved.records;
+    return {
+        schemaVersion: 1,
+        providers,
+        totalRecords: all.length,
+        span: all.length === 0
+            ? null
+            : {
+                fromMs: Math.min(...all.map((r) => r.fromMs)),
+                toMs: Math.max(...all.map((r) => r.toMs)),
+            },
+        possiblyDouble: resolved.possiblyDouble.length,
+        unknownVersion: resolved.unknownVersion,
+    };
+}
+/**
+ * Drops records whose window ended before the cutoff.
+ *
+ * Judged on `toMs`: a bucket that *ends* inside the retained period is
+ * retained whole, because half a bucket is a measurement of nothing. What goes
+ * is returned rather than counted, so the caller can say what went — silence
+ * about deleted measurements is the one thing a store must not do.
+ */
+export function pruneRecords(records, cutoffMs) {
+    const kept = [];
+    const dropped = [];
+    for (const record of records) {
+        (record.toMs < cutoffMs ? dropped : kept).push(record);
+    }
+    return {
+        kept,
+        dropped,
+        droppedSpan: dropped.length === 0
+            ? null
+            : {
+                fromMs: Math.min(...dropped.map((r) => r.fromMs)),
+                toMs: Math.max(...dropped.map((r) => r.toMs)),
+            },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/core",
-  "version": "1.40.0",
+  "version": "1.42.0",
   "description": "Trazum core: priced advisories for LLM prompts (caching, model tier, batching, schemas), plus deterministic trimming, token counting and pricing.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",

package/src/config-schema.ts

@@ -147,6 +147,16 @@ export interface TrazumConfig {
    * one is a silence nobody can audit. Waived failures render as waived,
    * never hidden — the bill still counts them; only the exit code is quiet.
    */
+  /**
+   * How long the local usage store keeps a measurement.
+   *
+   * Retention is a policy, so it lives in the repository beside the budgets
+   * rather than in whichever invocation happened to run the prune. There is
+   * deliberately **no default**: deleting measurements on a policy nobody
+   * wrote down is not something anybody should get by accident, so `--prune`
+   * with neither this nor `--keep` refuses and says so.
+   */
+  store?: { keepDays?: number };
   waive?: WaiveEntry[];
   /** Default for `trazum diff --max-growth`, in tokens. */
   maxGrowth?: number;
@@ -186,6 +196,7 @@ export const CONFIG_KEYS = [
   'labels',
   'spend',
   'sources',
+  'store',
   'waive',
   'maxGrowth',
   'baseline',
@@ -199,6 +210,8 @@ export const CONFIG_SPEND_KEYS = ['maxUsd', 'maxDayUsd', 'maxSessionUsd', 'byLab
 
 export const CONFIG_WAIVE_KEYS = ['gate', 'reason', 'until'] as const;
 
+export const CONFIG_STORE_KEYS = ['keepDays'] as const;
+
 /**
  * The gates a waiver can silence. The list is closed on purpose: a waiver
  * naming a gate that does not exist is a decision about nothing, and the
@@ -466,6 +479,32 @@ function parseSources(raw: unknown, source: string): Record<string, string[]> {
  * nothing. The expiry is *not* checked against today here — a config file is
  * timeless, and whether a waiver is expired is judged where the gate runs.
  */
+/**
+ * `store.keepDays` — retention, in whole days.
+ *
+ * A fraction of a day is refused rather than rounded: retention decides what
+ * gets deleted, and a policy the tool rounded on the operator's behalf is a
+ * policy nobody agreed to.
+ */
+function parseStore(raw: unknown, source: string): { keepDays?: number } {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    throw new Error(`"store" in ${source} must be an object, for example {"keepDays": 90}.`);
+  }
+  const entry = raw as Record<string, unknown>;
+  rejectUnknownKeys(entry, CONFIG_STORE_KEYS, source, 'store.');
+  const out: { keepDays?: number } = {};
+  if (entry.keepDays !== undefined) {
+    const days = entry.keepDays;
+    if (typeof days !== 'number' || !Number.isInteger(days) || days <= 0) {
+      throw new Error(
+        `"store.keepDays" in ${source} must be a whole number of days above zero, and it is ${JSON.stringify(days)}.`,
+      );
+    }
+    out.keepDays = days;
+  }
+  return out;
+}
+
 function parseWaive(raw: unknown, source: string): WaiveEntry[] {
   if (!Array.isArray(raw)) throw new ConfigError('"waive" must be an array', source);
   return raw.map((entry, index) => {
@@ -654,6 +693,7 @@ export function parseConfig(raw: string, source = CONFIG_FILENAME): TrazumConfig
   if (document.labels !== undefined) config.labels = parseLabels(document.labels, source);
   if (document.spend !== undefined) config.spend = parseSpend(document.spend, source);
   if (document.sources !== undefined) config.sources = parseSources(document.sources, source);
+  if (document.store !== undefined) config.store = parseStore(document.store, source);
   if (document.waive !== undefined) config.waive = parseWaive(document.waive, source);
   if (document.baseline !== undefined) {
     config.baseline = parseBaselineConfig(document.baseline, source);