@trazum/core 1.41.0 → 1.43.0

package/src/store.ts

@@ -0,0 +1,281 @@
+/**
+ * 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 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 function identityOf(record: StoreRecord): string {
+  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: StoreRecord): boolean {
+  return record.model !== '' && record.toMs > record.fromMs;
+}
+
+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 function resolveStore(records: readonly StoreRecord[]): ResolvedStore {
+  const byIdentity = new Map<string, StoreRecord>();
+  const possiblyDouble: StoreRecord[] = [];
+  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: string,
+  buckets: readonly UsageBucket[],
+  pulledAtMs: number,
+): StoreRecord[] {
+  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: readonly StoreRecord[]): UsageBucket[] {
+  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,
+  }));
+}
+
+// --------------------------------------------------------------------------
+// What is in the store
+// --------------------------------------------------------------------------
+
+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 function storeInventory(resolved: ResolvedStore): StoreInventory {
+  const byProvider = new Map<string, StoreRecord[]>();
+  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,
+  };
+}
+
+// --------------------------------------------------------------------------
+// Retention
+// --------------------------------------------------------------------------
+
+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 function pruneRecords(records: readonly StoreRecord[], cutoffMs: number): PruneResult {
+  const kept: StoreRecord[] = [];
+  const dropped: StoreRecord[] = [];
+  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)),
+          },
+  };
+}

package/src/watch.ts

@@ -0,0 +1,203 @@
+/**
+ * The afternoon the loop burned a quarter of the month, said that afternoon.
+ *
+ * Every gate in this product fires when a human runs a command. The failures
+ * worth catching — a retry loop, a prompt that grew, a model swapped in a
+ * deploy — happen at 3pm on a Tuesday, and a report that arrives three weeks
+ * later is an obituary.
+ *
+ * This module decides **what has crossed**, given what is measured and what
+ * the operator asked to be told about. The pulling, the storing, the sleeping
+ * and the sending live in the CLI; everything here is arithmetic over figures
+ * somebody already has, which is what makes an alerting rule testable without
+ * waiting for 3pm.
+ *
+ * **An alert fires on a measured crossing, never on a projection.** "You will
+ * exceed" is a forecast, and this product has refused those at every window
+ * length since 1.27. "You have spent $412 of a $400 budget, measured over
+ * these calls" is a fact, and the difference is the only reason an alert at
+ * 3am can be trusted.
+ *
+ * **A window too short to mean anything does not fire.** A day gate needs a
+ * whole day of measurement before it can fail: the first ten minutes of a day
+ * are not a day, and a watcher that cries at every dawn gets muted — which is
+ * how alerting tools actually fail.
+ */
+
+import type { BucketedReport } from './connector.js';
+
+export type WatchGate = 'maxUsd' | 'maxDayUsd' | 'maxCacheLossUsd';
+
+/** Why a gate could not be judged rather than passed. */
+export type NotJudgeable =
+  /** Not enough of the period is measured for the threshold to mean anything. */
+  | 'window-too-short'
+  /** The source cannot serve the dimension this gate is written against. */
+  | 'dimension-unavailable';
+
+export interface WatchCrossing {
+  gate: WatchGate;
+  /** The measured figure that crossed, and the threshold it crossed. */
+  measuredUsd: number;
+  limitUsd: number;
+  /** Which slice of time the figure covers — a day gate names its day. */
+  window: { fromMs: number; toMs: number };
+  /** A day gate's UTC day, so the alert names the afternoon it means. */
+  day: string | null;
+  /**
+   * Everything a machine reader needs to know what kind of number this is.
+   *
+   * `measured` is the only value this module will ever emit: a projected
+   * crossing is not a crossing. The field exists anyway, because a consumer
+   * that cannot see the provenance will treat whatever arrives as fact — and
+   * a later version of this file must not be able to smuggle an estimate past
+   * a reader by leaving the question unasked.
+   */
+  provenance: 'measured';
+}
+
+export interface WatchAbstention {
+  gate: WatchGate;
+  reason: NotJudgeable;
+  /** What is missing, as a figure the operator can act on. */
+  detail: { coveredMs: number; neededMs: number } | null;
+}
+
+export interface WatchResult {
+  crossings: WatchCrossing[];
+  /**
+   * Still over the limit, and already reported on an earlier cycle.
+   *
+   * These are the reason a quiet cycle is not the same as a clean one. A
+   * restart that reported "within every threshold" while the budget was still
+   * blown would be the flattering reading this product refuses everywhere:
+   * the alert was suppressed, the *crossing* was not, and only one of those
+   * is news.
+   */
+  suppressed: WatchCrossing[];
+  /**
+   * Gates that could not be judged, which is neither a pass nor a failure.
+   *
+   * Reported rather than swallowed: a gate silently skipped for a week reads
+   * exactly like a gate that has been passing for a week, and those are very
+   * different states to be in.
+   */
+  abstentions: WatchAbstention[];
+  /**
+   * The stretch this cycle did not watch, when a watcher was down or is
+   * starting for the first time. A resumed watcher that says nothing implies
+   * coverage it did not have.
+   */
+  gap: { fromMs: number; toMs: number } | null;
+}
+
+export interface WatchThresholds {
+  maxUsd?: number;
+  maxDayUsd?: number;
+  maxCacheLossUsd?: number;
+}
+
+export interface WatchOptions {
+  /** Priced measurements for the period being watched. */
+  report: BucketedReport;
+  thresholds: WatchThresholds;
+  /** The cache verdict over the same report, when the caller computed one. */
+  cacheDeltaUsd?: number;
+  /** Now, so a partly-elapsed day can be told from a whole one. */
+  nowMs: number;
+  /** Where the previous cycle finished, for the coverage gap. */
+  lastCoveredToMs?: number;
+  /**
+   * Gates already fired, by gate and by day, so a restart is not amnesia.
+   *
+   * Keyed `gate` for whole-period gates and `gate\nYYYY-MM-DD` for a day, so
+   * a day that already alerted stays quiet while a *new* day crossing still
+   * speaks.
+   */
+  alreadyFired?: ReadonlySet<string>;
+}
+
+/** A day gate cannot judge a day that has not finished being measured. */
+export const DAY_MS = 86_400_000;
+
+/**
+ * How much of a period must be measured before a threshold over it means
+ * anything. Nine tenths rather than all of it: a usage API's last bucket is
+ * often minutes behind, and a gate that waits for perfection never fires.
+ */
+export const COVERAGE_FLOOR = 0.9;
+
+export function firedKey(gate: WatchGate, day: string | null): string {
+  return day === null ? gate : `${gate}\n${day}`;
+}
+
+export function evaluateWatch(options: WatchOptions): WatchResult {
+  const { report, thresholds, cacheDeltaUsd, nowMs, lastCoveredToMs, alreadyFired } = options;
+  const fired = alreadyFired ?? new Set<string>();
+  const crossings: WatchCrossing[] = [];
+  const suppressed: WatchCrossing[] = [];
+  const abstentions: WatchAbstention[] = [];
+
+  const span = report.span;
+
+  const push = (gate: WatchGate, measuredUsd: number, limitUsd: number, day: string | null, window: { fromMs: number; toMs: number }): void => {
+    if (measuredUsd <= limitUsd) return;
+    const crossing: WatchCrossing = { gate, measuredUsd, limitUsd, window, day, provenance: 'measured' };
+    // Already told: quiet, but still crossed. The two are kept apart because
+    // "we alerted about this" and "this is fine now" are different sentences.
+    (fired.has(firedKey(gate, day)) ? suppressed : crossings).push(crossing);
+  };
+
+  if (thresholds.maxUsd !== undefined) {
+    if (span === null) {
+      abstentions.push({ gate: 'maxUsd', reason: 'dimension-unavailable', detail: null });
+    } else {
+      push('maxUsd', report.total.totalUsd, thresholds.maxUsd, null, span);
+    }
+  }
+
+  if (thresholds.maxCacheLossUsd !== undefined) {
+    if (cacheDeltaUsd === undefined || span === null) {
+      abstentions.push({ gate: 'maxCacheLossUsd', reason: 'dimension-unavailable', detail: null });
+    } else {
+      push('maxCacheLossUsd', cacheDeltaUsd, thresholds.maxCacheLossUsd, null, span);
+    }
+  }
+
+  if (thresholds.maxDayUsd !== undefined) {
+    if (report.byDay.length === 0) {
+      abstentions.push({ gate: 'maxDayUsd', reason: 'dimension-unavailable', detail: null });
+    } else {
+      for (const entry of report.byDay) {
+        const dayStart = Date.parse(`${entry.day}T00:00:00Z`);
+        const dayEnd = dayStart + DAY_MS;
+        /**
+         * The day still running is measured only up to now, so a threshold
+         * over it is a threshold over a fraction of a day. Once it *has*
+         * crossed, the crossing is real whatever the hour — a day that is
+         * already over budget at noon does not become less over budget at
+         * midnight — so the abstention only applies while the figure is
+         * still under the limit.
+         */
+        const covered = Math.min(nowMs, dayEnd) - dayStart;
+        const whole = covered >= DAY_MS * COVERAGE_FLOOR;
+        if (entry.usd > thresholds.maxDayUsd) {
+          push('maxDayUsd', entry.usd, thresholds.maxDayUsd, entry.day, { fromMs: dayStart, toMs: dayEnd });
+        } else if (!whole) {
+          abstentions.push({
+            gate: 'maxDayUsd',
+            reason: 'window-too-short',
+            detail: { coveredMs: Math.max(0, covered), neededMs: DAY_MS },
+          });
+        }
+      }
+    }
+  }
+
+  const gap =
+    lastCoveredToMs !== undefined && span !== null && span.fromMs > lastCoveredToMs
+      ? { fromMs: lastCoveredToMs, toMs: span.fromMs }
+      : null;
+
+  return { crossings, suppressed, abstentions, gap };
+}