@trazum/core 1.8.0

package/dist/aws-sigv4.d.ts

@@ -0,0 +1,88 @@
+/**
+ * AWS Signature Version 4, by hand.
+ *
+ * **Why by hand.** `@trazum/core` has zero runtime dependencies and a test that
+ * fails the build if one appears. That is a security property rather than a
+ * packaging preference: this library reads people's prompts, and every
+ * dependency is somebody else's code reading them too. The AWS SDK is roughly
+ * a hundred packages to sign one request.
+ *
+ * **WebCrypto, not `node:crypto`.** The browser-safe entry point cannot reach a
+ * Node builtin — `apps/web` bundles this library, and a single `node:` import
+ * anywhere in that graph fails the build. `crypto.subtle` exists in both, so
+ * signing works in a browser and in the CLI without a second implementation.
+ * Everything here is therefore async, which HMAC-SHA256 does not need to be and
+ * `crypto.subtle` insists on anyway.
+ *
+ * **What is not asserted, and it matters.** There is no AWS-published
+ * known-answer vector in the tests. This environment cannot reach the internet
+ * to fetch one and cannot reach AWS to try a real call, so the tests check the
+ * canonical strings this builds — which are derivable from the specification by
+ * reading — plus the cryptographic properties that any correct signer has. A
+ * systematically wrong canonicalisation that is wrong *consistently* would pass
+ * all of them. The first real request against Bedrock is the proof, and until
+ * somebody makes one this is careful code rather than verified code.
+ */
+/**
+ * `20260810T140102Z` and `20260810`, from one instant.
+ *
+ * Both derive from the same `Date` rather than being formatted twice. The
+ * classic SigV4 bug is a request signed at 23:59:59.9 whose date stamp comes
+ * from the next day: the credential scope and the timestamp disagree by one
+ * day, AWS rejects it, and it happens roughly once per thousand requests at
+ * midnight UTC and never in a test.
+ */
+export declare function amzDates(now: Date): {
+    amzDate: string;
+    dateStamp: string;
+};
+/**
+ * The signing key: four chained HMACs, each keyed by the last.
+ *
+ * The chain is what scopes a signature to one day, one region and one service,
+ * so a leaked signature is not a leaked credential. `AWS4` prefixes the secret
+ * and is part of the specification rather than decoration.
+ */
+export declare function signingKey(secretAccessKey: string, dateStamp: string, region: string, service: string): Promise<ArrayBuffer>;
+export interface SignInput {
+    method: string;
+    /** Already-encoded path, e.g. `/model/anthropic.claude-v2/invoke`. */
+    path: string;
+    host: string;
+    region: string;
+    service: string;
+    body: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** Present for temporary credentials, and signed when it is. */
+    sessionToken?: string;
+    now: Date;
+}
+/**
+ * The headers a signed request carries.
+ *
+ * Returned rather than mutated onto a request, so this is a pure function of its
+ * input and a test can read every byte of what it produced.
+ */
+export interface SignedHeaders {
+    authorization: string;
+    'x-amz-date': string;
+    'x-amz-content-sha256': string;
+    'x-amz-security-token'?: string;
+}
+/**
+ * Builds the canonical request, exactly as the specification orders it.
+ *
+ * Exported for the tests, because this string is where a signer goes wrong.
+ * Every field is joined with a newline, headers are lowercased and sorted, and
+ * the trailing newline after the header block is required — omit it and every
+ * signature is wrong in a way whose only symptom is `403 SignatureDoesNotMatch`.
+ */
+export declare function canonicalRequest(input: SignInput): Promise<{
+    canonical: string;
+    signedHeaderNames: string;
+    payloadHash: string;
+}>;
+/** The full `Authorization` header value, and the headers that go with it. */
+export declare function signRequest(input: SignInput): Promise<SignedHeaders>;
+//# sourceMappingURL=aws-sigv4.d.ts.map

package/dist/aws-sigv4.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aws-sigv4.d.ts","sourceRoot":"","sources":["../src/aws-sigv4.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAyBH;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,IAAI,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAG1E;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,WAAW,CAAC,CAKtB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,IAAI,CAAC;CACX;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC,CA6BD;AAED,8EAA8E;AAC9E,wBAAsB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,CAmB1E"}

package/dist/aws-sigv4.js

@@ -0,0 +1,117 @@
+/**
+ * AWS Signature Version 4, by hand.
+ *
+ * **Why by hand.** `@trazum/core` has zero runtime dependencies and a test that
+ * fails the build if one appears. That is a security property rather than a
+ * packaging preference: this library reads people's prompts, and every
+ * dependency is somebody else's code reading them too. The AWS SDK is roughly
+ * a hundred packages to sign one request.
+ *
+ * **WebCrypto, not `node:crypto`.** The browser-safe entry point cannot reach a
+ * Node builtin — `apps/web` bundles this library, and a single `node:` import
+ * anywhere in that graph fails the build. `crypto.subtle` exists in both, so
+ * signing works in a browser and in the CLI without a second implementation.
+ * Everything here is therefore async, which HMAC-SHA256 does not need to be and
+ * `crypto.subtle` insists on anyway.
+ *
+ * **What is not asserted, and it matters.** There is no AWS-published
+ * known-answer vector in the tests. This environment cannot reach the internet
+ * to fetch one and cannot reach AWS to try a real call, so the tests check the
+ * canonical strings this builds — which are derivable from the specification by
+ * reading — plus the cryptographic properties that any correct signer has. A
+ * systematically wrong canonicalisation that is wrong *consistently* would pass
+ * all of them. The first real request against Bedrock is the proof, and until
+ * somebody makes one this is careful code rather than verified code.
+ */
+const ALGORITHM = 'AWS4-HMAC-SHA256';
+const encoder = new TextEncoder();
+function hex(bytes) {
+    return [...new Uint8Array(bytes)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+async function sha256Hex(text) {
+    return hex(await crypto.subtle.digest('SHA-256', encoder.encode(text)));
+}
+async function hmac(key, message) {
+    const imported = await crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return crypto.subtle.sign('HMAC', imported, encoder.encode(message));
+}
+/**
+ * `20260810T140102Z` and `20260810`, from one instant.
+ *
+ * Both derive from the same `Date` rather than being formatted twice. The
+ * classic SigV4 bug is a request signed at 23:59:59.9 whose date stamp comes
+ * from the next day: the credential scope and the timestamp disagree by one
+ * day, AWS rejects it, and it happens roughly once per thousand requests at
+ * midnight UTC and never in a test.
+ */
+export function amzDates(now) {
+    const amzDate = `${now.toISOString().replace(/[:-]|\.\d{3}/g, '')}`;
+    return { amzDate, dateStamp: amzDate.slice(0, 8) };
+}
+/**
+ * The signing key: four chained HMACs, each keyed by the last.
+ *
+ * The chain is what scopes a signature to one day, one region and one service,
+ * so a leaked signature is not a leaked credential. `AWS4` prefixes the secret
+ * and is part of the specification rather than decoration.
+ */
+export async function signingKey(secretAccessKey, dateStamp, region, service) {
+    const kDate = await hmac(encoder.encode(`AWS4${secretAccessKey}`), dateStamp);
+    const kRegion = await hmac(kDate, region);
+    const kService = await hmac(kRegion, service);
+    return hmac(kService, 'aws4_request');
+}
+/**
+ * Builds the canonical request, exactly as the specification orders it.
+ *
+ * Exported for the tests, because this string is where a signer goes wrong.
+ * Every field is joined with a newline, headers are lowercased and sorted, and
+ * the trailing newline after the header block is required — omit it and every
+ * signature is wrong in a way whose only symptom is `403 SignatureDoesNotMatch`.
+ */
+export async function canonicalRequest(input) {
+    const { amzDate } = amzDates(input.now);
+    const payloadHash = await sha256Hex(input.body);
+    // `host` and the two `x-amz-` headers are what Bedrock requires signed. Sorted
+    // by name because the specification says sorted, not because it looks tidier.
+    const headers = [
+        ['host', input.host],
+        ['x-amz-content-sha256', payloadHash],
+        ['x-amz-date', amzDate],
+    ];
+    if (input.sessionToken)
+        headers.push(['x-amz-security-token', input.sessionToken]);
+    headers.sort((a, b) => (a[0] < b[0] ? -1 : 1));
+    const canonicalHeaders = headers.map(([name, value]) => `${name}:${value.trim()}\n`).join('');
+    const signedHeaderNames = headers.map(([name]) => name).join(';');
+    const canonical = [
+        input.method,
+        input.path,
+        // No query string on any request this signs. Present and empty, because the
+        // field is positional: dropping it shifts everything below it up a line.
+        '',
+        canonicalHeaders,
+        signedHeaderNames,
+        payloadHash,
+    ].join('\n');
+    return { canonical, signedHeaderNames, payloadHash };
+}
+/** The full `Authorization` header value, and the headers that go with it. */
+export async function signRequest(input) {
+    const { amzDate, dateStamp } = amzDates(input.now);
+    const { canonical, signedHeaderNames, payloadHash } = await canonicalRequest(input);
+    const scope = `${dateStamp}/${input.region}/${input.service}/aws4_request`;
+    const stringToSign = [ALGORITHM, amzDate, scope, await sha256Hex(canonical)].join('\n');
+    const key = await signingKey(input.secretAccessKey, dateStamp, input.region, input.service);
+    const signature = hex(await hmac(key, stringToSign));
+    const headers = {
+        authorization: `${ALGORITHM} Credential=${input.accessKeyId}/${scope}, ` +
+            `SignedHeaders=${signedHeaderNames}, Signature=${signature}`,
+        'x-amz-date': amzDate,
+        'x-amz-content-sha256': payloadHash,
+    };
+    if (input.sessionToken)
+        headers['x-amz-security-token'] = input.sessionToken;
+    return headers;
+}
+//# sourceMappingURL=aws-sigv4.js.map

package/dist/aws-sigv4.js.map

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

package/dist/baseline.d.ts

@@ -0,0 +1,171 @@
+import type { UsageProfile } from './types.js';
+/**
+ * The cost baseline: what this repository's prompts cost as of a commit, and
+ * what has happened to them since.
+ *
+ * **Why this exists.** `budgets` in `trazum.config.json` is a ceiling — it
+ * answers "does this file fit". It cannot answer "did this change make things
+ * worse", and those are different questions with different failure modes. A
+ * repository sitting at 95% of every budget passes every gate forever while a
+ * pull request quietly adds four hundred tokens across a dozen files. A ceiling
+ * catches the absolute; only a baseline catches the drift.
+ *
+ * **Why the gate is in tokens and the money is only reported.** A dollar figure
+ * is derived from three things: the token count, the usage scenario, and the
+ * price list. Two of those change for reasons that have nothing to do with the
+ * prompts — a repriced model, an edited `callsPerMonth` — so a baseline holding
+ * dollars would fail a build the day the catalogue was updated, calling a price
+ * change a regression. A gate that cries wolf is a gate somebody deletes.
+ *
+ * Tokens depend on the text and nothing else. They are what is compared, they
+ * are what the threshold is written in, and the monthly figure is recomputed at
+ * comparison time and shown next to it — with an explicit note when the scenario
+ * or the price list moved, because a dollar delta across a reprice is two
+ * different measurements subtracted from each other.
+ *
+ * No filesystem access here, deliberately: `apps/web` bundles this package for
+ * the browser, and one `node:fs` import anywhere in the graph fails that build.
+ * Reading and writing the file is the CLI's job.
+ */
+/**
+ * The document version.
+ *
+ * Written into every baseline and checked on read. A baseline is committed and
+ * outlives the version of Trazum that wrote it, so a future shape change has to
+ * be able to say "this file is from an older format, re-record it" rather than
+ * misreading fields that moved.
+ */
+export declare const BASELINE_VERSION = 1;
+export declare const BASELINE_FILENAME = "trazum.baseline.json";
+/**
+ * Largest baseline this will read.
+ *
+ * Bigger than the config limit because this one scales with the repository: a
+ * thousand prompts is a thousand entries. Still bounded, so a corrupt or hostile
+ * file is refused before `JSON.parse` is handed the whole thing.
+ */
+export declare const MAX_BASELINE_BYTES: number;
+export interface BaselineDocument {
+    version: number;
+    /** ISO date the baseline was recorded, for the report to cite. */
+    recorded: string;
+    /**
+     * The scenario the monthly figure was computed under. Recorded so a later
+     * comparison can say whether the money is comparable, not to gate on.
+     */
+    scenario: UsageProfile;
+    /** `PRICING_LAST_REVIEWED` at the time, for the same reason. */
+    pricingReviewed: string;
+    totals: {
+        tokens: number;
+        monthlyUsd: number;
+    };
+    /**
+     * Repository-relative path to token count, forward slashes always.
+     *
+     * Per file rather than one total, because a gate that reports "the repository
+     * grew by 400 tokens" without naming the file is a gate people learn to
+     * ignore. Sorted on write so re-recording produces a reviewable diff instead
+     * of a reordered one.
+     */
+    files: Record<string, number>;
+}
+export declare class BaselineError extends Error {
+    readonly source: string;
+    constructor(message: string, source: string);
+}
+/**
+ * Validates a baseline document.
+ *
+ * **Every failure throws**, for the reason the config parser gives: this file
+ * decides whether a build passes. A lenient read of a malformed baseline is a
+ * gate that measured nothing and reported success, which is worse than no gate,
+ * because the repository now believes it has one.
+ */
+export declare function parseBaseline(raw: string, source?: string): BaselineDocument;
+/**
+ * The document as text, ready to commit.
+ *
+ * Keys are emitted in a fixed order and file paths sorted, so re-recording an
+ * unchanged repository produces a byte-identical file. A baseline that reshuffles
+ * itself on every write turns every pull request into an unreviewable diff, and
+ * the first thing anyone does with an unreviewable diff is stop reading it.
+ */
+export declare function formatBaseline(document: BaselineDocument): string;
+export interface BaselineChange {
+    path: string;
+    before: number;
+    after: number;
+    /** `after - before`, so positive is growth — the direction that costs money. */
+    delta: number;
+}
+export interface BaselineComparison {
+    grown: BaselineChange[];
+    shrunk: BaselineChange[];
+    /**
+     * Present now, absent from the baseline.
+     *
+     * Counted toward the total, which is the whole reason this field exists: a new
+     * prompt is new cost, and a comparison over only the files present in both
+     * would let a five-thousand-token addition through every threshold.
+     */
+    added: BaselineChange[];
+    /** In the baseline, gone from the tree. Never a regression — it is a saving. */
+    removed: BaselineChange[];
+    tokensBefore: number;
+    tokensAfter: number;
+    delta: number;
+    /** Growth as a percentage of the baseline, or 0 when the baseline was empty. */
+    deltaPct: number;
+}
+/**
+ * Compares a set of current token counts against a baseline.
+ *
+ * Pure arithmetic over two maps. It takes counts rather than file contents so
+ * the caller decides what a prompt is — directory mode, extracted markers, a
+ * hand-picked list — and this stays the one place the comparison is defined.
+ */
+export declare function compareToBaseline(baseline: BaselineDocument, current: Record<string, number>): BaselineComparison;
+export interface BaselineThresholds {
+    /** Absolute token growth allowed. */
+    maxGrowthTokens?: number;
+    /** Growth allowed as a percentage of the baseline total. */
+    maxGrowthPct?: number;
+}
+/** Why a comparison failed. Structured, so the CLI owns the wording. */
+export type BaselineBreach = {
+    kind: 'tokens';
+    limit: number;
+    actual: number;
+} | {
+    kind: 'pct';
+    limit: number;
+    actual: number;
+};
+/**
+ * Whether a comparison breaches its thresholds.
+ *
+ * Both thresholds are checked and **either one failing fails the gate** — they
+ * are not alternatives to pick between. A percentage alone lets a small
+ * repository absorb a large absolute addition; an absolute number alone means a
+ * large repository never trips. Whichever is exceeded is reported, so the output
+ * names the limit that was actually crossed rather than a generic failure.
+ *
+ * Shrinking never fails. There is no such thing as a prompt that got too cheap.
+ */
+export declare function breaches(comparison: BaselineComparison, thresholds: BaselineThresholds): BaselineBreach[];
+/**
+ * Whether the baseline's money is comparable to today's.
+ *
+ * Tokens are always comparable — they depend on the text and nothing else, which
+ * is why the gate is written in them. The monthly figure is not: a repriced model
+ * or an edited scenario changes it without a single prompt moving. When either
+ * has shifted the report says so instead of subtracting two different
+ * measurements and presenting the difference as a saving.
+ */
+export declare function moneyIsComparable(baseline: BaselineDocument, scenario: UsageProfile, pricingReviewed: string): {
+    comparable: boolean;
+    scenarioChanged: boolean;
+    pricingChanged: boolean;
+};
+//# sourceMappingURL=baseline.d.ts.map

package/dist/baseline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.d.ts","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,eAAO,MAAM,iBAAiB,yBAAyB,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,QAAkB,CAAC;AAElD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,EAAE,YAAY,CAAC;IACvB,gEAAgE;IAChE,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,qBAAa,aAAc,SAAQ,KAAK;IAGpC,QAAQ,CAAC,MAAM,EAAE,MAAM;IAFzB,YACE,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,EAIxB;CACF;AA2CD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,SAAoB,GAAG,gBAAgB,CAgFvF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAsBjE;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB;;;;;;OAMG;IACH,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,gFAAgF;IAChF,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,kBAAkB,CAuCpB;AAED,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wEAAwE;AACxE,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CACtB,UAAU,EAAE,kBAAkB,EAC9B,UAAU,EAAE,kBAAkB,GAC7B,cAAc,EAAE,CAWlB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,YAAY,EACtB,eAAe,EAAE,MAAM,GACtB;IAAE,UAAU,EAAE,OAAO,CAAC;IAAC,eAAe,EAAE,OAAO,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,CAU5E"}

package/dist/baseline.js

@@ -0,0 +1,273 @@
+/**
+ * The cost baseline: what this repository's prompts cost as of a commit, and
+ * what has happened to them since.
+ *
+ * **Why this exists.** `budgets` in `trazum.config.json` is a ceiling — it
+ * answers "does this file fit". It cannot answer "did this change make things
+ * worse", and those are different questions with different failure modes. A
+ * repository sitting at 95% of every budget passes every gate forever while a
+ * pull request quietly adds four hundred tokens across a dozen files. A ceiling
+ * catches the absolute; only a baseline catches the drift.
+ *
+ * **Why the gate is in tokens and the money is only reported.** A dollar figure
+ * is derived from three things: the token count, the usage scenario, and the
+ * price list. Two of those change for reasons that have nothing to do with the
+ * prompts — a repriced model, an edited `callsPerMonth` — so a baseline holding
+ * dollars would fail a build the day the catalogue was updated, calling a price
+ * change a regression. A gate that cries wolf is a gate somebody deletes.
+ *
+ * Tokens depend on the text and nothing else. They are what is compared, they
+ * are what the threshold is written in, and the monthly figure is recomputed at
+ * comparison time and shown next to it — with an explicit note when the scenario
+ * or the price list moved, because a dollar delta across a reprice is two
+ * different measurements subtracted from each other.
+ *
+ * No filesystem access here, deliberately: `apps/web` bundles this package for
+ * the browser, and one `node:fs` import anywhere in the graph fails that build.
+ * Reading and writing the file is the CLI's job.
+ */
+/**
+ * The document version.
+ *
+ * Written into every baseline and checked on read. A baseline is committed and
+ * outlives the version of Trazum that wrote it, so a future shape change has to
+ * be able to say "this file is from an older format, re-record it" rather than
+ * misreading fields that moved.
+ */
+export const BASELINE_VERSION = 1;
+export const BASELINE_FILENAME = 'trazum.baseline.json';
+/**
+ * Largest baseline this will read.
+ *
+ * Bigger than the config limit because this one scales with the repository: a
+ * thousand prompts is a thousand entries. Still bounded, so a corrupt or hostile
+ * file is refused before `JSON.parse` is handed the whole thing.
+ */
+export const MAX_BASELINE_BYTES = 4 * 1024 * 1024;
+export class BaselineError extends Error {
+    source;
+    constructor(message, source) {
+        super(`${source}: ${message}`);
+        this.source = source;
+        this.name = 'BaselineError';
+    }
+}
+/**
+ * An absolute path in any shape a committed file might carry one.
+ *
+ * Same regex, and the same reasoning, as `config-schema.ts`: written out rather
+ * than delegating to `path.isAbsolute` because that is platform-dependent, and a
+ * baseline recorded on Windows must be judged identically on a Linux runner or
+ * the gate silently matches nothing.
+ */
+const IS_ABSOLUTE = /^(?:[/\\]|[A-Za-z]:[/\\])/;
+const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function requireWholeCount(value, label, source) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new BaselineError(`"${label}" must be a whole number of 0 or more`, source);
+    }
+    return value;
+}
+function requireString(value, label, source) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new BaselineError(`"${label}" must be a non-empty string`, source);
+    }
+    return value;
+}
+function cacheHitRateOf(value, source) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1) {
+        throw new BaselineError('"scenario.cacheHitRate" is a fraction between 0 and 1', source);
+    }
+    return value;
+}
+function batchEligibleOf(value, source) {
+    if (typeof value !== 'boolean') {
+        throw new BaselineError('"scenario.batchEligible" must be true or false', source);
+    }
+    return value;
+}
+/**
+ * Validates a baseline document.
+ *
+ * **Every failure throws**, for the reason the config parser gives: this file
+ * decides whether a build passes. A lenient read of a malformed baseline is a
+ * gate that measured nothing and reported success, which is worse than no gate,
+ * because the repository now believes it has one.
+ */
+export function parseBaseline(raw, source = BASELINE_FILENAME) {
+    let document;
+    try {
+        document = JSON.parse(raw);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new BaselineError(`not valid JSON — ${detail}`, source);
+    }
+    if (!isPlainObject(document)) {
+        throw new BaselineError('the top level must be an object', source);
+    }
+    const version = document.version;
+    if (version !== BASELINE_VERSION) {
+        throw new BaselineError(`is version ${JSON.stringify(version)}, and this Trazum reads version ${BASELINE_VERSION}. ` +
+            're-record it with "trazum baseline"', source);
+    }
+    if (!isPlainObject(document.totals)) {
+        throw new BaselineError('"totals" must be an object', source);
+    }
+    if (!isPlainObject(document.files)) {
+        throw new BaselineError('"files" must be an object of path to token count', source);
+    }
+    if (!isPlainObject(document.scenario)) {
+        throw new BaselineError('"scenario" must be an object', source);
+    }
+    const files = {};
+    for (const [path, tokens] of Object.entries(document.files)) {
+        if (path.length === 0)
+            throw new BaselineError('"files" has an empty path', source);
+        if (IS_ABSOLUTE.test(path) || path.includes('..')) {
+            throw new BaselineError(`"files" path ${JSON.stringify(path)} must be relative to the project`, source);
+        }
+        files[path] = requireWholeCount(tokens, `files["${path}"]`, source);
+    }
+    const totalUsd = document.totals.monthlyUsd;
+    if (typeof totalUsd !== 'number' || !Number.isFinite(totalUsd) || totalUsd < 0) {
+        throw new BaselineError('"totals.monthlyUsd" must be a number of 0 or more', source);
+    }
+    const recorded = requireWholeCount(document.totals.tokens, 'totals.tokens', source);
+    const summed = Object.values(files).reduce((a, b) => a + b, 0);
+    if (recorded !== summed) {
+        // A hand-edited total is the one corruption that looks completely normal:
+        // the file parses, the gate runs, and it compares against a number nobody
+        // measured. Cheap to check, so it is checked.
+        throw new BaselineError(`"totals.tokens" is ${recorded} but the per-file counts sum to ${summed}`, source);
+    }
+    const scenario = document.scenario;
+    return {
+        version: BASELINE_VERSION,
+        recorded: requireString(document.recorded, 'recorded', source),
+        pricingReviewed: requireString(document.pricingReviewed, 'pricingReviewed', source),
+        scenario: {
+            model: requireString(scenario.model, 'scenario.model', source),
+            callsPerMonth: requireWholeCount(scenario.callsPerMonth, 'scenario.callsPerMonth', source),
+            avgOutputTokens: requireWholeCount(scenario.avgOutputTokens, 'scenario.avgOutputTokens', source),
+            cacheHitRate: cacheHitRateOf(scenario.cacheHitRate, source),
+            batchEligible: batchEligibleOf(scenario.batchEligible, source),
+        },
+        totals: { tokens: recorded, monthlyUsd: totalUsd },
+        files,
+    };
+}
+/**
+ * The document as text, ready to commit.
+ *
+ * Keys are emitted in a fixed order and file paths sorted, so re-recording an
+ * unchanged repository produces a byte-identical file. A baseline that reshuffles
+ * itself on every write turns every pull request into an unreviewable diff, and
+ * the first thing anyone does with an unreviewable diff is stop reading it.
+ */
+export function formatBaseline(document) {
+    const files = {};
+    for (const path of Object.keys(document.files).sort())
+        files[path] = document.files[path];
+    return `${JSON.stringify({
+        version: BASELINE_VERSION,
+        recorded: document.recorded,
+        scenario: {
+            model: document.scenario.model,
+            callsPerMonth: document.scenario.callsPerMonth,
+            avgOutputTokens: document.scenario.avgOutputTokens,
+            cacheHitRate: document.scenario.cacheHitRate,
+            batchEligible: document.scenario.batchEligible,
+        },
+        pricingReviewed: document.pricingReviewed,
+        totals: document.totals,
+        files,
+    }, null, 2)}\n`;
+}
+/**
+ * Compares a set of current token counts against a baseline.
+ *
+ * Pure arithmetic over two maps. It takes counts rather than file contents so
+ * the caller decides what a prompt is — directory mode, extracted markers, a
+ * hand-picked list — and this stays the one place the comparison is defined.
+ */
+export function compareToBaseline(baseline, current) {
+    const grown = [];
+    const shrunk = [];
+    const added = [];
+    const removed = [];
+    for (const path of Object.keys(current).sort()) {
+        const after = current[path];
+        const before = baseline.files[path];
+        if (before === undefined) {
+            added.push({ path, before: 0, after, delta: after });
+        }
+        else if (after > before) {
+            grown.push({ path, before, after, delta: after - before });
+        }
+        else if (after < before) {
+            shrunk.push({ path, before, after, delta: after - before });
+        }
+    }
+    for (const path of Object.keys(baseline.files).sort()) {
+        if (current[path] === undefined) {
+            const before = baseline.files[path];
+            removed.push({ path, before, after: 0, delta: -before });
+        }
+    }
+    const tokensBefore = baseline.totals.tokens;
+    const tokensAfter = Object.values(current).reduce((a, b) => a + b, 0);
+    const delta = tokensAfter - tokensBefore;
+    return {
+        grown,
+        shrunk,
+        added,
+        removed,
+        tokensBefore,
+        tokensAfter,
+        delta,
+        deltaPct: tokensBefore === 0 ? 0 : (delta / tokensBefore) * 100,
+    };
+}
+/**
+ * Whether a comparison breaches its thresholds.
+ *
+ * Both thresholds are checked and **either one failing fails the gate** — they
+ * are not alternatives to pick between. A percentage alone lets a small
+ * repository absorb a large absolute addition; an absolute number alone means a
+ * large repository never trips. Whichever is exceeded is reported, so the output
+ * names the limit that was actually crossed rather than a generic failure.
+ *
+ * Shrinking never fails. There is no such thing as a prompt that got too cheap.
+ */
+export function breaches(comparison, thresholds) {
+    const found = [];
+    if (comparison.delta <= 0)
+        return found;
+    if (thresholds.maxGrowthTokens !== undefined && comparison.delta > thresholds.maxGrowthTokens) {
+        found.push({ kind: 'tokens', limit: thresholds.maxGrowthTokens, actual: comparison.delta });
+    }
+    if (thresholds.maxGrowthPct !== undefined && comparison.deltaPct > thresholds.maxGrowthPct) {
+        found.push({ kind: 'pct', limit: thresholds.maxGrowthPct, actual: comparison.deltaPct });
+    }
+    return found;
+}
+/**
+ * Whether the baseline's money is comparable to today's.
+ *
+ * Tokens are always comparable — they depend on the text and nothing else, which
+ * is why the gate is written in them. The monthly figure is not: a repriced model
+ * or an edited scenario changes it without a single prompt moving. When either
+ * has shifted the report says so instead of subtracting two different
+ * measurements and presenting the difference as a saving.
+ */
+export function moneyIsComparable(baseline, scenario, pricingReviewed) {
+    const scenarioChanged = baseline.scenario.model !== scenario.model ||
+        baseline.scenario.callsPerMonth !== scenario.callsPerMonth ||
+        baseline.scenario.avgOutputTokens !== scenario.avgOutputTokens ||
+        baseline.scenario.cacheHitRate !== scenario.cacheHitRate ||
+        baseline.scenario.batchEligible !== scenario.batchEligible;
+    const pricingChanged = baseline.pricingReviewed !== pricingReviewed;
+    return { comparable: !scenarioChanged && !pricingChanged, scenarioChanged, pricingChanged };
+}
+//# sourceMappingURL=baseline.js.map