niceeval 0.12.2-canary.31 → 0.13.1

package/dist/analysis/cost-decimal.cjs

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INDEPENDENTLY_BILLABLE_TOKEN_BUCKETS = void 0;
+exports.isIndependentlyBillableTokenBucket = isIndependentlyBillableTokenBucket;
+exports.parseCanonicalDecimal = parseCanonicalDecimal;
+exports.normalizeCanonicalDecimal = normalizeCanonicalDecimal;
+exports.addCanonicalDecimals = addCanonicalDecimals;
+exports.addDecimalCoefficients = addDecimalCoefficients;
+exports.multiplyCanonicalDecimals = multiplyCanonicalDecimals;
+exports.multiplyCanonicalDecimalByInteger = multiplyCanonicalDecimalByInteger;
+exports.costForPerMillionTokens = costForPerMillionTokens;
+exports.rationalFromDecimal = rationalFromDecimal;
+exports.divideDecimalCoefficient = divideDecimalCoefficient;
+exports.roundDecimalRationalHalfAway = roundDecimalRationalHalfAway;
+/**
+ * Private exact-decimal primitives for the future cost projection. Monetary
+ * inputs are always canonical strings; JavaScript numbers and decimal-library
+ * values never enter this boundary.
+ */
+const model_ts_1 = require("../o11y/record/model.cjs");
+const TOKENS_PER_MILLION_SCALE = 6;
+/**
+ * Reasoning is already included in the recorded output bucket and therefore
+ * must never become a second independently priced token bucket.
+ */
+exports.INDEPENDENTLY_BILLABLE_TOKEN_BUCKETS = Object.freeze([
+    "input",
+    "output",
+    "cache-read",
+    "cache-write",
+]);
+function isIndependentlyBillableTokenBucket(value) {
+    return exports.INDEPENDENTLY_BILLABLE_TOKEN_BUCKETS.includes(value);
+}
+/** Parses one validated, non-negative canonical decimal without Number coercion. */
+function parseCanonicalDecimal(value) {
+    const canonical = (0, model_ts_1.makeCanonicalDecimal)(value);
+    if (canonical === undefined) {
+        throw new TypeError("Cost decimal must be a non-negative canonical decimal string");
+    }
+    const point = canonical.indexOf(".");
+    const scale = point === -1 ? 0 : canonical.length - point - 1;
+    const digits = point === -1 ? canonical : `${canonical.slice(0, point)}${canonical.slice(point + 1)}`;
+    return Object.freeze({ coefficient: BigInt(digits), scale });
+}
+/** Normalizes a non-negative coefficient × 10^-scale back to CanonicalDecimal. */
+function normalizeCanonicalDecimal(value) {
+    if (value.coefficient < 0n) {
+        throw new RangeError("Cost decimal coefficient must be non-negative");
+    }
+    if (!Number.isSafeInteger(value.scale) || value.scale < 0) {
+        throw new RangeError("Cost decimal scale must be a non-negative safe integer");
+    }
+    if (value.coefficient === 0n)
+        return canonicalDecimal("0");
+    let coefficient = value.coefficient;
+    let scale = value.scale;
+    while (scale > 0 && coefficient % 10n === 0n) {
+        coefficient /= 10n;
+        scale -= 1;
+    }
+    const digits = coefficient.toString();
+    const text = scale === 0
+        ? digits
+        : digits.length > scale
+            ? `${digits.slice(0, digits.length - scale)}.${digits.slice(digits.length - scale)}`
+            : `0.${"0".repeat(scale - digits.length)}${digits}`;
+    return canonicalDecimal(text);
+}
+/** Adds canonical amounts exactly. An empty sequence has the valid amount zero. */
+function addCanonicalDecimals(values) {
+    return normalizeCanonicalDecimal(addDecimalCoefficients(values.map(parseCanonicalDecimal)));
+}
+/** Adds non-negative decimal coefficients exactly, retaining the shared scale. */
+function addDecimalCoefficients(values) {
+    if (values.length === 0)
+        return Object.freeze({ coefficient: 0n, scale: 0 });
+    const scale = Math.max(...values.map((value) => checkedScale(value.scale)));
+    const coefficient = values.reduce((total, value) => total + checkedCoefficient(value) * tenTo(scale - checkedScale(value.scale)), 0n);
+    return Object.freeze({ coefficient, scale });
+}
+/** Multiplies two canonical amounts exactly, without accepting Number operands. */
+function multiplyCanonicalDecimals(left, right) {
+    const first = parseCanonicalDecimal(left);
+    const second = parseCanonicalDecimal(right);
+    return normalizeCanonicalDecimal({
+        coefficient: first.coefficient * second.coefficient,
+        scale: first.scale + second.scale,
+    });
+}
+/** Multiplies one canonical amount by a recorded non-negative integer quantity. */
+function multiplyCanonicalDecimalByInteger(value, multiplier) {
+    if (!Number.isSafeInteger(multiplier) || multiplier < 0) {
+        throw new TypeError("Cost quantity must be a non-negative safe integer");
+    }
+    const decimal = parseCanonicalDecimal(value);
+    return normalizeCanonicalDecimal({
+        coefficient: decimal.coefficient * BigInt(multiplier),
+        scale: decimal.scale,
+    });
+}
+/**
+ * Prices an exact recorded token count against a canonical per-million amount.
+ * The fixed 10^6 unit preserves a terminating decimal; arbitrary token units
+ * are intentionally unsupported until a public pricing contract exists.
+ */
+function costForPerMillionTokens(amountPerMillion, tokens) {
+    if (!Number.isSafeInteger(tokens) || tokens < 0) {
+        throw new TypeError("Recorded token quantity must be a non-negative safe integer");
+    }
+    const decimal = parseCanonicalDecimal(amountPerMillion);
+    return normalizeCanonicalDecimal({
+        coefficient: decimal.coefficient * BigInt(tokens),
+        scale: decimal.scale + TOKENS_PER_MILLION_SCALE,
+    });
+}
+/** Turns an exact decimal into an exact rational without Number coercion. */
+function rationalFromDecimal(value) {
+    return Object.freeze({
+        numerator: checkedCoefficient(value),
+        denominator: 1n,
+        scale: checkedScale(value.scale),
+    });
+}
+/** Divides an exact decimal by a positive integral denominator for a mean. */
+function divideDecimalCoefficient(value, denominator) {
+    if (!Number.isSafeInteger(denominator) || denominator <= 0) {
+        throw new RangeError("Cost mean denominator must be a positive safe integer");
+    }
+    return Object.freeze({
+        numerator: checkedCoefficient(value),
+        denominator: BigInt(denominator),
+        scale: checkedScale(value.scale),
+    });
+}
+/**
+ * Rounds a non-negative rational to a Profile display scale. All monetary
+ * inputs are non-negative, so half-away-from-zero is exact half-up here.
+ */
+function roundDecimalRationalHalfAway(value, decimalPlaces) {
+    if (!Number.isSafeInteger(decimalPlaces) || decimalPlaces < 0 || decimalPlaces > 9) {
+        throw new RangeError("Cost display decimalPlaces must be an integer from 0 through 9");
+    }
+    if (value.numerator < 0n || value.denominator <= 0n) {
+        throw new RangeError("Cost rational must be non-negative with a positive denominator");
+    }
+    const scale = checkedScale(value.scale);
+    const scaledNumerator = value.numerator * tenTo(decimalPlaces);
+    const scaledDenominator = value.denominator * tenTo(scale);
+    const coefficient = (scaledNumerator * 2n + scaledDenominator) / (scaledDenominator * 2n);
+    return normalizeCanonicalDecimal({ coefficient, scale: decimalPlaces });
+}
+function tenTo(exponent) {
+    if (!Number.isSafeInteger(exponent) || exponent < 0) {
+        throw new RangeError("Cost decimal exponent must be a non-negative safe integer");
+    }
+    return 10n ** BigInt(exponent);
+}
+function checkedCoefficient(value) {
+    if (value.coefficient < 0n)
+        throw new RangeError("Cost decimal coefficient must be non-negative");
+    return value.coefficient;
+}
+function checkedScale(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError("Cost decimal scale must be a non-negative safe integer");
+    }
+    return value;
+}
+function canonicalDecimal(value) {
+    const canonical = (0, model_ts_1.makeCanonicalDecimal)(value);
+    if (canonical === undefined) {
+        throw new RangeError("Cost decimal result exceeds canonical decimal limits");
+    }
+    return canonical;
+}
+//# sourceMappingURL=cost-decimal.cjs.map

package/dist/analysis/cost-decimal.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-decimal.js","sourceRoot":"","sources":["cost-decimal.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Private exact-decimal primitives for the future cost projection. Monetary\n * inputs are always canonical strings; JavaScript numbers and decimal-library\n * values never enter this boundary.\n */\nimport { makeCanonicalDecimal, type CanonicalDecimal, type NonNegativeSafeInteger, } from \"../o11y/record/model.ts\";\nconst TOKENS_PER_MILLION_SCALE = 6;\n/** Internal coefficient × 10^-scale representation. */\nexport interface DecimalCoefficient {\n    readonly coefficient: bigint;\n    readonly scale: number;\n}\n/** Internal exact quotient used for a mean before its display rounding. */\nexport interface DecimalRational {\n    readonly numerator: bigint;\n    readonly denominator: bigint;\n    readonly scale: number;\n}\n/**\n * Reasoning is already included in the recorded output bucket and therefore\n * must never become a second independently priced token bucket.\n */\nexport const INDEPENDENTLY_BILLABLE_TOKEN_BUCKETS = Object.freeze([\n    \"input\",\n    \"output\",\n    \"cache-read\",\n    \"cache-write\",\n] as const);\nexport type IndependentlyBillableTokenBucket = (typeof INDEPENDENTLY_BILLABLE_TOKEN_BUCKETS)[number];\nexport function isIndependentlyBillableTokenBucket(value: string): value is IndependentlyBillableTokenBucket {\n    return (INDEPENDENTLY_BILLABLE_TOKEN_BUCKETS as readonly string[]).includes(value);\n}\n/** Parses one validated, non-negative canonical decimal without Number coercion. */\nexport function parseCanonicalDecimal(value: CanonicalDecimal): DecimalCoefficient {\n    const canonical = makeCanonicalDecimal(value);\n    if (canonical === undefined) {\n        throw new TypeError(\"Cost decimal must be a non-negative canonical decimal string\");\n    }\n    const point = canonical.indexOf(\".\");\n    const scale = point === -1 ? 0 : canonical.length - point - 1;\n    const digits = point === -1 ? canonical : `${canonical.slice(0, point)}${canonical.slice(point + 1)}`;\n    return Object.freeze({ coefficient: BigInt(digits), scale });\n}\n/** Normalizes a non-negative coefficient × 10^-scale back to CanonicalDecimal. */\nexport function normalizeCanonicalDecimal(value: DecimalCoefficient): CanonicalDecimal {\n    if (value.coefficient < 0n) {\n        throw new RangeError(\"Cost decimal coefficient must be non-negative\");\n    }\n    if (!Number.isSafeInteger(value.scale) || value.scale < 0) {\n        throw new RangeError(\"Cost decimal scale must be a non-negative safe integer\");\n    }\n    if (value.coefficient === 0n)\n        return canonicalDecimal(\"0\");\n    let coefficient = value.coefficient;\n    let scale = value.scale;\n    while (scale > 0 && coefficient % 10n === 0n) {\n        coefficient /= 10n;\n        scale -= 1;\n    }\n    const digits = coefficient.toString();\n    const text = scale === 0\n        ? digits\n        : digits.length > scale\n            ? `${digits.slice(0, digits.length - scale)}.${digits.slice(digits.length - scale)}`\n            : `0.${\"0\".repeat(scale - digits.length)}${digits}`;\n    return canonicalDecimal(text);\n}\n/** Adds canonical amounts exactly. An empty sequence has the valid amount zero. */\nexport function addCanonicalDecimals(values: readonly CanonicalDecimal[]): CanonicalDecimal {\n    return normalizeCanonicalDecimal(addDecimalCoefficients(values.map(parseCanonicalDecimal)));\n}\n/** Adds non-negative decimal coefficients exactly, retaining the shared scale. */\nexport function addDecimalCoefficients(values: readonly DecimalCoefficient[]): DecimalCoefficient {\n    if (values.length === 0)\n        return Object.freeze({ coefficient: 0n, scale: 0 });\n    const scale = Math.max(...values.map((value) => checkedScale(value.scale)));\n    const coefficient = values.reduce((total, value) => total + checkedCoefficient(value) * tenTo(scale - checkedScale(value.scale)), 0n);\n    return Object.freeze({ coefficient, scale });\n}\n/** Multiplies two canonical amounts exactly, without accepting Number operands. */\nexport function multiplyCanonicalDecimals(left: CanonicalDecimal, right: CanonicalDecimal): CanonicalDecimal {\n    const first = parseCanonicalDecimal(left);\n    const second = parseCanonicalDecimal(right);\n    return normalizeCanonicalDecimal({\n        coefficient: first.coefficient * second.coefficient,\n        scale: first.scale + second.scale,\n    });\n}\n/** Multiplies one canonical amount by a recorded non-negative integer quantity. */\nexport function multiplyCanonicalDecimalByInteger(value: CanonicalDecimal, multiplier: NonNegativeSafeInteger): CanonicalDecimal {\n    if (!Number.isSafeInteger(multiplier) || multiplier < 0) {\n        throw new TypeError(\"Cost quantity must be a non-negative safe integer\");\n    }\n    const decimal = parseCanonicalDecimal(value);\n    return normalizeCanonicalDecimal({\n        coefficient: decimal.coefficient * BigInt(multiplier),\n        scale: decimal.scale,\n    });\n}\n/**\n * Prices an exact recorded token count against a canonical per-million amount.\n * The fixed 10^6 unit preserves a terminating decimal; arbitrary token units\n * are intentionally unsupported until a public pricing contract exists.\n */\nexport function costForPerMillionTokens(amountPerMillion: CanonicalDecimal, tokens: NonNegativeSafeInteger): CanonicalDecimal {\n    if (!Number.isSafeInteger(tokens) || tokens < 0) {\n        throw new TypeError(\"Recorded token quantity must be a non-negative safe integer\");\n    }\n    const decimal = parseCanonicalDecimal(amountPerMillion);\n    return normalizeCanonicalDecimal({\n        coefficient: decimal.coefficient * BigInt(tokens),\n        scale: decimal.scale + TOKENS_PER_MILLION_SCALE,\n    });\n}\n/** Turns an exact decimal into an exact rational without Number coercion. */\nexport function rationalFromDecimal(value: DecimalCoefficient): DecimalRational {\n    return Object.freeze({\n        numerator: checkedCoefficient(value),\n        denominator: 1n,\n        scale: checkedScale(value.scale),\n    });\n}\n/** Divides an exact decimal by a positive integral denominator for a mean. */\nexport function divideDecimalCoefficient(value: DecimalCoefficient, denominator: number): DecimalRational {\n    if (!Number.isSafeInteger(denominator) || denominator <= 0) {\n        throw new RangeError(\"Cost mean denominator must be a positive safe integer\");\n    }\n    return Object.freeze({\n        numerator: checkedCoefficient(value),\n        denominator: BigInt(denominator),\n        scale: checkedScale(value.scale),\n    });\n}\n/**\n * Rounds a non-negative rational to a Profile display scale. All monetary\n * inputs are non-negative, so half-away-from-zero is exact half-up here.\n */\nexport function roundDecimalRationalHalfAway(value: DecimalRational, decimalPlaces: number): CanonicalDecimal {\n    if (!Number.isSafeInteger(decimalPlaces) || decimalPlaces < 0 || decimalPlaces > 9) {\n        throw new RangeError(\"Cost display decimalPlaces must be an integer from 0 through 9\");\n    }\n    if (value.numerator < 0n || value.denominator <= 0n) {\n        throw new RangeError(\"Cost rational must be non-negative with a positive denominator\");\n    }\n    const scale = checkedScale(value.scale);\n    const scaledNumerator = value.numerator * tenTo(decimalPlaces);\n    const scaledDenominator = value.denominator * tenTo(scale);\n    const coefficient = (scaledNumerator * 2n + scaledDenominator) / (scaledDenominator * 2n);\n    return normalizeCanonicalDecimal({ coefficient, scale: decimalPlaces });\n}\nfunction tenTo(exponent: number): bigint {\n    if (!Number.isSafeInteger(exponent) || exponent < 0) {\n        throw new RangeError(\"Cost decimal exponent must be a non-negative safe integer\");\n    }\n    return 10n ** BigInt(exponent);\n}\nfunction checkedCoefficient(value: DecimalCoefficient): bigint {\n    if (value.coefficient < 0n)\n        throw new RangeError(\"Cost decimal coefficient must be non-negative\");\n    return value.coefficient;\n}\nfunction checkedScale(value: number): number {\n    if (!Number.isSafeInteger(value) || value < 0) {\n        throw new RangeError(\"Cost decimal scale must be a non-negative safe integer\");\n    }\n    return value;\n}\nfunction canonicalDecimal(value: string): CanonicalDecimal {\n    const canonical = makeCanonicalDecimal(value);\n    if (canonical === undefined) {\n        throw new RangeError(\"Cost decimal result exceeds canonical decimal limits\");\n    }\n    return canonical;\n}\n"]}

package/dist/analysis/cost-decimal.d.cts

@@ -0,0 +1,51 @@
+/**
+ * Private exact-decimal primitives for the future cost projection. Monetary
+ * inputs are always canonical strings; JavaScript numbers and decimal-library
+ * values never enter this boundary.
+ */
+import { type CanonicalDecimal, type NonNegativeSafeInteger } from "../o11y/record/model.cjs";
+/** Internal coefficient × 10^-scale representation. */
+export interface DecimalCoefficient {
+    readonly coefficient: bigint;
+    readonly scale: number;
+}
+/** Internal exact quotient used for a mean before its display rounding. */
+export interface DecimalRational {
+    readonly numerator: bigint;
+    readonly denominator: bigint;
+    readonly scale: number;
+}
+/**
+ * Reasoning is already included in the recorded output bucket and therefore
+ * must never become a second independently priced token bucket.
+ */
+export declare const INDEPENDENTLY_BILLABLE_TOKEN_BUCKETS: readonly ["input", "output", "cache-read", "cache-write"];
+export type IndependentlyBillableTokenBucket = (typeof INDEPENDENTLY_BILLABLE_TOKEN_BUCKETS)[number];
+export declare function isIndependentlyBillableTokenBucket(value: string): value is IndependentlyBillableTokenBucket;
+/** Parses one validated, non-negative canonical decimal without Number coercion. */
+export declare function parseCanonicalDecimal(value: CanonicalDecimal): DecimalCoefficient;
+/** Normalizes a non-negative coefficient × 10^-scale back to CanonicalDecimal. */
+export declare function normalizeCanonicalDecimal(value: DecimalCoefficient): CanonicalDecimal;
+/** Adds canonical amounts exactly. An empty sequence has the valid amount zero. */
+export declare function addCanonicalDecimals(values: readonly CanonicalDecimal[]): CanonicalDecimal;
+/** Adds non-negative decimal coefficients exactly, retaining the shared scale. */
+export declare function addDecimalCoefficients(values: readonly DecimalCoefficient[]): DecimalCoefficient;
+/** Multiplies two canonical amounts exactly, without accepting Number operands. */
+export declare function multiplyCanonicalDecimals(left: CanonicalDecimal, right: CanonicalDecimal): CanonicalDecimal;
+/** Multiplies one canonical amount by a recorded non-negative integer quantity. */
+export declare function multiplyCanonicalDecimalByInteger(value: CanonicalDecimal, multiplier: NonNegativeSafeInteger): CanonicalDecimal;
+/**
+ * Prices an exact recorded token count against a canonical per-million amount.
+ * The fixed 10^6 unit preserves a terminating decimal; arbitrary token units
+ * are intentionally unsupported until a public pricing contract exists.
+ */
+export declare function costForPerMillionTokens(amountPerMillion: CanonicalDecimal, tokens: NonNegativeSafeInteger): CanonicalDecimal;
+/** Turns an exact decimal into an exact rational without Number coercion. */
+export declare function rationalFromDecimal(value: DecimalCoefficient): DecimalRational;
+/** Divides an exact decimal by a positive integral denominator for a mean. */
+export declare function divideDecimalCoefficient(value: DecimalCoefficient, denominator: number): DecimalRational;
+/**
+ * Rounds a non-negative rational to a Profile display scale. All monetary
+ * inputs are non-negative, so half-away-from-zero is exact half-up here.
+ */
+export declare function roundDecimalRationalHalfAway(value: DecimalRational, decimalPlaces: number): CanonicalDecimal;

package/dist/analysis/cost-decimal.d.mts

@@ -0,0 +1,51 @@
+/**
+ * Private exact-decimal primitives for the future cost projection. Monetary
+ * inputs are always canonical strings; JavaScript numbers and decimal-library
+ * values never enter this boundary.
+ */
+import { type CanonicalDecimal, type NonNegativeSafeInteger } from "../o11y/record/model.mjs";
+/** Internal coefficient × 10^-scale representation. */
+export interface DecimalCoefficient {
+    readonly coefficient: bigint;
+    readonly scale: number;
+}
+/** Internal exact quotient used for a mean before its display rounding. */
+export interface DecimalRational {
+    readonly numerator: bigint;
+    readonly denominator: bigint;
+    readonly scale: number;
+}
+/**
+ * Reasoning is already included in the recorded output bucket and therefore
+ * must never become a second independently priced token bucket.
+ */
+export declare const INDEPENDENTLY_BILLABLE_TOKEN_BUCKETS: readonly ["input", "output", "cache-read", "cache-write"];
+export type IndependentlyBillableTokenBucket = (typeof INDEPENDENTLY_BILLABLE_TOKEN_BUCKETS)[number];
+export declare function isIndependentlyBillableTokenBucket(value: string): value is IndependentlyBillableTokenBucket;
+/** Parses one validated, non-negative canonical decimal without Number coercion. */
+export declare function parseCanonicalDecimal(value: CanonicalDecimal): DecimalCoefficient;
+/** Normalizes a non-negative coefficient × 10^-scale back to CanonicalDecimal. */
+export declare function normalizeCanonicalDecimal(value: DecimalCoefficient): CanonicalDecimal;
+/** Adds canonical amounts exactly. An empty sequence has the valid amount zero. */
+export declare function addCanonicalDecimals(values: readonly CanonicalDecimal[]): CanonicalDecimal;
+/** Adds non-negative decimal coefficients exactly, retaining the shared scale. */
+export declare function addDecimalCoefficients(values: readonly DecimalCoefficient[]): DecimalCoefficient;
+/** Multiplies two canonical amounts exactly, without accepting Number operands. */
+export declare function multiplyCanonicalDecimals(left: CanonicalDecimal, right: CanonicalDecimal): CanonicalDecimal;
+/** Multiplies one canonical amount by a recorded non-negative integer quantity. */
+export declare function multiplyCanonicalDecimalByInteger(value: CanonicalDecimal, multiplier: NonNegativeSafeInteger): CanonicalDecimal;
+/**
+ * Prices an exact recorded token count against a canonical per-million amount.
+ * The fixed 10^6 unit preserves a terminating decimal; arbitrary token units
+ * are intentionally unsupported until a public pricing contract exists.
+ */
+export declare function costForPerMillionTokens(amountPerMillion: CanonicalDecimal, tokens: NonNegativeSafeInteger): CanonicalDecimal;
+/** Turns an exact decimal into an exact rational without Number coercion. */
+export declare function rationalFromDecimal(value: DecimalCoefficient): DecimalRational;
+/** Divides an exact decimal by a positive integral denominator for a mean. */
+export declare function divideDecimalCoefficient(value: DecimalCoefficient, denominator: number): DecimalRational;
+/**
+ * Rounds a non-negative rational to a Profile display scale. All monetary
+ * inputs are non-negative, so half-away-from-zero is exact half-up here.
+ */
+export declare function roundDecimalRationalHalfAway(value: DecimalRational, decimalPlaces: number): CanonicalDecimal;

package/dist/analysis/cost-decimal.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Private exact-decimal primitives for the future cost projection. Monetary
+ * inputs are always canonical strings; JavaScript numbers and decimal-library
+ * values never enter this boundary.
+ */
+import { type CanonicalDecimal, type NonNegativeSafeInteger } from "../o11y/record/model.js";
+/** Internal coefficient × 10^-scale representation. */
+export interface DecimalCoefficient {
+    readonly coefficient: bigint;
+    readonly scale: number;
+}
+/** Internal exact quotient used for a mean before its display rounding. */
+export interface DecimalRational {
+    readonly numerator: bigint;
+    readonly denominator: bigint;
+    readonly scale: number;
+}
+/**
+ * Reasoning is already included in the recorded output bucket and therefore
+ * must never become a second independently priced token bucket.
+ */
+export declare const INDEPENDENTLY_BILLABLE_TOKEN_BUCKETS: readonly ["input", "output", "cache-read", "cache-write"];
+export type IndependentlyBillableTokenBucket = (typeof INDEPENDENTLY_BILLABLE_TOKEN_BUCKETS)[number];
+export declare function isIndependentlyBillableTokenBucket(value: string): value is IndependentlyBillableTokenBucket;
+/** Parses one validated, non-negative canonical decimal without Number coercion. */
+export declare function parseCanonicalDecimal(value: CanonicalDecimal): DecimalCoefficient;
+/** Normalizes a non-negative coefficient × 10^-scale back to CanonicalDecimal. */
+export declare function normalizeCanonicalDecimal(value: DecimalCoefficient): CanonicalDecimal;
+/** Adds canonical amounts exactly. An empty sequence has the valid amount zero. */
+export declare function addCanonicalDecimals(values: readonly CanonicalDecimal[]): CanonicalDecimal;
+/** Adds non-negative decimal coefficients exactly, retaining the shared scale. */
+export declare function addDecimalCoefficients(values: readonly DecimalCoefficient[]): DecimalCoefficient;
+/** Multiplies two canonical amounts exactly, without accepting Number operands. */
+export declare function multiplyCanonicalDecimals(left: CanonicalDecimal, right: CanonicalDecimal): CanonicalDecimal;
+/** Multiplies one canonical amount by a recorded non-negative integer quantity. */
+export declare function multiplyCanonicalDecimalByInteger(value: CanonicalDecimal, multiplier: NonNegativeSafeInteger): CanonicalDecimal;
+/**
+ * Prices an exact recorded token count against a canonical per-million amount.
+ * The fixed 10^6 unit preserves a terminating decimal; arbitrary token units
+ * are intentionally unsupported until a public pricing contract exists.
+ */
+export declare function costForPerMillionTokens(amountPerMillion: CanonicalDecimal, tokens: NonNegativeSafeInteger): CanonicalDecimal;
+/** Turns an exact decimal into an exact rational without Number coercion. */
+export declare function rationalFromDecimal(value: DecimalCoefficient): DecimalRational;
+/** Divides an exact decimal by a positive integral denominator for a mean. */
+export declare function divideDecimalCoefficient(value: DecimalCoefficient, denominator: number): DecimalRational;
+/**
+ * Rounds a non-negative rational to a Profile display scale. All monetary
+ * inputs are non-negative, so half-away-from-zero is exact half-up here.
+ */
+export declare function roundDecimalRationalHalfAway(value: DecimalRational, decimalPlaces: number): CanonicalDecimal;

package/dist/analysis/cost-decimal.js

@@ -0,0 +1,28 @@
+import { createRequire as __niceevalCreateRequire } from "node:module";
+const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
+const __niceevalCanonical = __niceevalRequire("./cost-decimal.cjs");
+const __niceevalExport0 = __niceevalCanonical["INDEPENDENTLY_BILLABLE_TOKEN_BUCKETS"];
+export { __niceevalExport0 as INDEPENDENTLY_BILLABLE_TOKEN_BUCKETS };
+const __niceevalExport1 = __niceevalCanonical["addCanonicalDecimals"];
+export { __niceevalExport1 as addCanonicalDecimals };
+const __niceevalExport2 = __niceevalCanonical["addDecimalCoefficients"];
+export { __niceevalExport2 as addDecimalCoefficients };
+const __niceevalExport3 = __niceevalCanonical["costForPerMillionTokens"];
+export { __niceevalExport3 as costForPerMillionTokens };
+const __niceevalExport4 = __niceevalCanonical["divideDecimalCoefficient"];
+export { __niceevalExport4 as divideDecimalCoefficient };
+const __niceevalExport5 = __niceevalCanonical["isIndependentlyBillableTokenBucket"];
+export { __niceevalExport5 as isIndependentlyBillableTokenBucket };
+const __niceevalExport6 = __niceevalCanonical["multiplyCanonicalDecimalByInteger"];
+export { __niceevalExport6 as multiplyCanonicalDecimalByInteger };
+const __niceevalExport7 = __niceevalCanonical["multiplyCanonicalDecimals"];
+export { __niceevalExport7 as multiplyCanonicalDecimals };
+const __niceevalExport8 = __niceevalCanonical["normalizeCanonicalDecimal"];
+export { __niceevalExport8 as normalizeCanonicalDecimal };
+const __niceevalExport9 = __niceevalCanonical["parseCanonicalDecimal"];
+export { __niceevalExport9 as parseCanonicalDecimal };
+const __niceevalExport10 = __niceevalCanonical["rationalFromDecimal"];
+export { __niceevalExport10 as rationalFromDecimal };
+const __niceevalExport11 = __niceevalCanonical["roundDecimalRationalHalfAway"];
+export { __niceevalExport11 as roundDecimalRationalHalfAway };
+//# sourceMappingURL=cost-decimal.js.map

package/dist/analysis/cost-decimal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-decimal.js","sources":[],"names":[],"mappings":""}