@wildo-ai/saas-models 1.1.5 → 1.1.6

package/dist/esm/external-providers/provider-usage-cost.shared.js

@@ -0,0 +1,171 @@
+/**
+ * # Provider-usage cost: pricing one call exactly, and rounding a total once
+ *
+ * The arithmetic half of #1598's cost calculator. Pure and adapter-free, so the backend recorder, the
+ * `summarize` read and the period close use ONE implementation and cannot disagree about a cost.
+ *
+ * ## Exact per call, rounded once per total (review F11)
+ *
+ * A call's cost is stored as an exact fraction of a minor currency unit
+ * (`callCostMinorNumerator / callCostUnitsDenominator`). A total is the exact sum of those fractions (each
+ * multiplied by its row's share), rounded UP to a whole minor unit once, at the moment a total is reported.
+ * Rounding each call would overstate a case made of many small embedding calls by up to one minor unit
+ * per call. Currencies are never converted and never mixed: an accumulator holds one currency.
+ *
+ * ## Quantities (#1598 §7)
+ *
+ * - Input: with a reported split, `noCacheTokens` → `INPUT_TOKEN`, `cacheReadTokens` →
+ *   `CACHED_INPUT_TOKEN`, `cacheWriteTokens` → `CACHE_WRITE_INPUT_TOKEN`; without one, every prompt token is
+ *   `INPUT_TOKEN`. A cache category the authority prices no rate for is priced at the input rate: a missing
+ *   rate never makes tokens free.
+ * - Output: `completionTokens` → `OUTPUT_TOKEN`. When the authority declares a `REASONING_TOKEN` rate and the
+ *   provider reported the reasoning split, the reasoning quantity is priced at that rate and SUBTRACTED from
+ *   the output quantity, so it is never billed twice (Paul, Q3).
+ * - Tiers are per request: the highest threshold the call's whole input quantity exceeds applies its
+ *   multipliers to the input categories and to output/reasoning respectively.
+ */
+import { PROVIDER_USAGE_RATE_MULTIPLIER_BASIS_POINTS, ProviderUsagePricingCategory, } from './provider-usage-pricing.shared.schemas.js';
+import { ReasoningUsageReporting } from '../flows-actors/work-attribution.shared.schemas.js';
+const ZERO = BigInt(0);
+const ONE = BigInt(1);
+function gcd(a, b) {
+    let x = a < ZERO ? -a : a;
+    let y = b < ZERO ? -b : b;
+    while (y !== ZERO) {
+        const t = x % y;
+        x = y;
+        y = t;
+    }
+    return x === ZERO ? ONE : x;
+}
+function count(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+/**
+ * Pick the authority that prices a call: same provider and model, `effectiveFrom` not after the call, the
+ * highest version among those. `undefined` means the call is UNPRICED.
+ */
+export function selectProviderUsagePricingAuthority(authorities, call) {
+    if (!call.provider || !call.model)
+        return undefined;
+    let chosen;
+    for (const authority of authorities) {
+        if (authority.providerRef !== call.provider || authority.model !== call.model)
+            continue;
+        if (Date.parse(authority.effectiveFrom) > call.calledAt.getTime())
+            continue;
+        if (!chosen || authority.pricingAuthorityVersion > chosen.pricingAuthorityVersion)
+            chosen = authority;
+    }
+    return chosen;
+}
+/**
+ * Refuse a registered list that names one `ref@version` twice (#1598 §7). Two entries under one identity
+ * would make "the price used" ambiguous in every row and aggregate that names it. Throws with every
+ * duplicated identity named.
+ */
+export function assertUniqueProviderUsagePricingAuthorities(authorities) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const authority of authorities) {
+        const identity = `${authority.pricingAuthorityRef}@${authority.pricingAuthorityVersion}`;
+        if (seen.has(identity))
+            duplicates.add(identity);
+        seen.add(identity);
+    }
+    if (duplicates.size > 0) {
+        throw new Error(`modelCostAccounting.providerUsagePricingAuthorities registers the same pricing authority more than once: ${[...duplicates].join(', ')}. `
+            + 'A price is identified by pricingAuthorityRef@pricingAuthorityVersion; publish a changed rate as a new version.');
+    }
+}
+/** Whether a call's usage reports the reasoning split. */
+export function reasoningUsageReportingOf(usage) {
+    return typeof usage.reasoningTokens === 'number' && Number.isFinite(usage.reasoningTokens) && usage.reasoningTokens >= 0
+        ? ReasoningUsageReporting.REPORTED
+        : ReasoningUsageReporting.UNREPORTED;
+}
+/**
+ * The exact cost of one call under `authority`, unrounded. See the file header for the quantity rules.
+ */
+export function computeProviderUsageCallCost(authority, usage) {
+    const rateOf = new Map(authority.rates.map((rate) => [rate.category, rate.amountMinorNumerator]));
+    const inputRate = rateOf.get(ProviderUsagePricingCategory.INPUT_TOKEN);
+    const promptTokens = count(usage.promptTokens);
+    const completionTokens = count(usage.completionTokens);
+    const hasInputSplit = usage.noCacheTokens !== undefined || usage.cacheReadTokens !== undefined || usage.cacheWriteTokens !== undefined;
+    const cacheRead = hasInputSplit ? count(usage.cacheReadTokens) : 0;
+    const cacheWrite = hasInputSplit ? count(usage.cacheWriteTokens) : 0;
+    const noCache = hasInputSplit
+        ? (usage.noCacheTokens !== undefined ? count(usage.noCacheTokens) : Math.max(0, promptTokens - cacheRead - cacheWrite))
+        : promptTokens;
+    const pricesReasoningApart = rateOf.has(ProviderUsagePricingCategory.REASONING_TOKEN)
+        && reasoningUsageReportingOf(usage) === ReasoningUsageReporting.REPORTED;
+    const reasoning = pricesReasoningApart ? Math.min(count(usage.reasoningTokens), completionTokens) : 0;
+    const output = completionTokens - reasoning;
+    // The tier is decided by the request's WHOLE input quantity, whatever its cache split.
+    const inputQuantity = hasInputSplit ? noCache + cacheRead + cacheWrite : promptTokens;
+    let inputMultiplier = PROVIDER_USAGE_RATE_MULTIPLIER_BASIS_POINTS;
+    let outputMultiplier = PROVIDER_USAGE_RATE_MULTIPLIER_BASIS_POINTS;
+    for (const rule of authority.usageTierRules) {
+        if (inputQuantity > rule.inputTokenThresholdExclusive) {
+            inputMultiplier = rule.inputRateMultiplierBasisPoints;
+            outputMultiplier = rule.outputRateMultiplierBasisPoints;
+        }
+    }
+    const amounts = [];
+    let numerator = ZERO;
+    const add = (category, quantity, rate, multiplier) => {
+        if (quantity === 0)
+            return;
+        amounts.push({ category, quantity });
+        numerator += BigInt(quantity) * BigInt(rate) * BigInt(multiplier);
+    };
+    add(ProviderUsagePricingCategory.INPUT_TOKEN, noCache, inputRate, inputMultiplier);
+    add(ProviderUsagePricingCategory.CACHED_INPUT_TOKEN, cacheRead, rateOf.get(ProviderUsagePricingCategory.CACHED_INPUT_TOKEN) ?? inputRate, inputMultiplier);
+    add(ProviderUsagePricingCategory.CACHE_WRITE_INPUT_TOKEN, cacheWrite, rateOf.get(ProviderUsagePricingCategory.CACHE_WRITE_INPUT_TOKEN) ?? inputRate, inputMultiplier);
+    add(ProviderUsagePricingCategory.OUTPUT_TOKEN, output, rateOf.get(ProviderUsagePricingCategory.OUTPUT_TOKEN), outputMultiplier);
+    if (pricesReasoningApart) {
+        add(ProviderUsagePricingCategory.REASONING_TOKEN, reasoning, rateOf.get(ProviderUsagePricingCategory.REASONING_TOKEN), outputMultiplier);
+    }
+    let denominator = BigInt(authority.unitsDenominator) * BigInt(PROVIDER_USAGE_RATE_MULTIPLIER_BASIS_POINTS);
+    const divisor = gcd(numerator, denominator);
+    numerator /= divisor;
+    denominator /= divisor;
+    return {
+        pricingAuthorityRef: authority.pricingAuthorityRef,
+        pricingAuthorityVersion: authority.pricingAuthorityVersion,
+        currency: authority.currency,
+        callCostMinorNumerator: numerator.toString(),
+        callCostUnitsDenominator: Number(denominator),
+        amounts,
+    };
+}
+/**
+ * An exact running total of minor-unit fractions in ONE currency, rounded up once when read.
+ *
+ * `add` takes a call's exact cost and the attribution row's share of it (`shareNumerator / shareDenominator`,
+ * 1/1 for a whole call). The sum stays a reduced fraction of bigints, so no precision is lost however many
+ * rows are added.
+ */
+export class ExactMinorCostTotal {
+    numerator = ZERO;
+    denominator = ONE;
+    add(callCostMinorNumerator, callCostUnitsDenominator, shareNumerator = 1, shareDenominator = 1) {
+        if (shareDenominator <= 0 || callCostUnitsDenominator <= 0)
+            return;
+        const partNumerator = BigInt(callCostMinorNumerator) * BigInt(Math.max(0, Math.floor(shareNumerator)));
+        const partDenominator = BigInt(callCostUnitsDenominator) * BigInt(Math.floor(shareDenominator));
+        const nextNumerator = this.numerator * partDenominator + partNumerator * this.denominator;
+        const nextDenominator = this.denominator * partDenominator;
+        const divisor = gcd(nextNumerator, nextDenominator);
+        this.numerator = nextNumerator / divisor;
+        this.denominator = nextDenominator / divisor;
+    }
+    /** The total, rounded UP to a whole minor unit: `CEILING_AGGREGATE_TO_MINOR_UNIT`, applied once. */
+    ceilMinor() {
+        if (this.numerator === ZERO)
+            return ZERO;
+        return (this.numerator + this.denominator - ONE) / this.denominator;
+    }
+}
+//# sourceMappingURL=provider-usage-cost.shared.js.map

package/dist/esm/external-providers/provider-usage-cost.shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-usage-cost.shared.js","sourceRoot":"","sources":["../../../../src/external-providers/provider-usage-cost.shared.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * # Provider-usage cost: pricing one call exactly, and rounding a total once\n *\n * The arithmetic half of #1598's cost calculator. Pure and adapter-free, so the backend recorder, the\n * `summarize` read and the period close use ONE implementation and cannot disagree about a cost.\n *\n * ## Exact per call, rounded once per total (review F11)\n *\n * A call's cost is stored as an exact fraction of a minor currency unit\n * (`callCostMinorNumerator / callCostUnitsDenominator`). A total is the exact sum of those fractions (each\n * multiplied by its row's share), rounded UP to a whole minor unit once, at the moment a total is reported.\n * Rounding each call would overstate a case made of many small embedding calls by up to one minor unit\n * per call. Currencies are never converted and never mixed: an accumulator holds one currency.\n *\n * ## Quantities (#1598 §7)\n *\n * - Input: with a reported split, `noCacheTokens` → `INPUT_TOKEN`, `cacheReadTokens` →\n *   `CACHED_INPUT_TOKEN`, `cacheWriteTokens` → `CACHE_WRITE_INPUT_TOKEN`; without one, every prompt token is\n *   `INPUT_TOKEN`. A cache category the authority prices no rate for is priced at the input rate: a missing\n *   rate never makes tokens free.\n * - Output: `completionTokens` → `OUTPUT_TOKEN`. When the authority declares a `REASONING_TOKEN` rate and the\n *   provider reported the reasoning split, the reasoning quantity is priced at that rate and SUBTRACTED from\n *   the output quantity, so it is never billed twice (Paul, Q3).\n * - Tiers are per request: the highest threshold the call's whole input quantity exceeds applies its\n *   multipliers to the input categories and to output/reasoning respectively.\n */\nimport {\n  PROVIDER_USAGE_RATE_MULTIPLIER_BASIS_POINTS,\n  ProviderUsagePricingCategory,\n  type ProviderUsageAmount,\n  type ProviderUsageCostResult,\n  type ProviderUsagePricingAuthority,\n} from './provider-usage-pricing.shared.schemas';\nimport { ReasoningUsageReporting } from '../flows-actors/work-attribution.shared.schemas';\n\n/** The token counts one call reported, as the provider-call record stores them. Absent means not reported. */\nexport interface ProviderUsageQuantities {\n  readonly promptTokens?: number;\n  readonly completionTokens?: number;\n  readonly noCacheTokens?: number;\n  readonly cacheReadTokens?: number;\n  readonly cacheWriteTokens?: number;\n  readonly reasoningTokens?: number;\n}\n\nconst ZERO = BigInt(0);\nconst ONE = BigInt(1);\n\nfunction gcd(a: bigint, b: bigint): bigint {\n  let x = a < ZERO ? -a : a;\n  let y = b < ZERO ? -b : b;\n  while (y !== ZERO) {\n    const t = x % y;\n    x = y;\n    y = t;\n  }\n  return x === ZERO ? ONE : x;\n}\n\nfunction count(value: number | undefined): number {\n  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;\n}\n\n/**\n * Pick the authority that prices a call: same provider and model, `effectiveFrom` not after the call, the\n * highest version among those. `undefined` means the call is UNPRICED.\n */\nexport function selectProviderUsagePricingAuthority(\n  authorities: readonly ProviderUsagePricingAuthority[],\n  call: { provider?: string | null; model?: string | null; calledAt: Date },\n): ProviderUsagePricingAuthority | undefined {\n  if (!call.provider || !call.model) return undefined;\n  let chosen: ProviderUsagePricingAuthority | undefined;\n  for (const authority of authorities) {\n    if (authority.providerRef !== call.provider || authority.model !== call.model) continue;\n    if (Date.parse(authority.effectiveFrom) > call.calledAt.getTime()) continue;\n    if (!chosen || authority.pricingAuthorityVersion > chosen.pricingAuthorityVersion) chosen = authority;\n  }\n  return chosen;\n}\n\n/**\n * Refuse a registered list that names one `ref@version` twice (#1598 §7). Two entries under one identity\n * would make \"the price used\" ambiguous in every row and aggregate that names it. Throws with every\n * duplicated identity named.\n */\nexport function assertUniqueProviderUsagePricingAuthorities(authorities: readonly ProviderUsagePricingAuthority[]): void {\n  const seen = new Set<string>();\n  const duplicates = new Set<string>();\n  for (const authority of authorities) {\n    const identity = `${authority.pricingAuthorityRef}@${authority.pricingAuthorityVersion}`;\n    if (seen.has(identity)) duplicates.add(identity);\n    seen.add(identity);\n  }\n  if (duplicates.size > 0) {\n    throw new Error(\n      `modelCostAccounting.providerUsagePricingAuthorities registers the same pricing authority more than once: ${[...duplicates].join(', ')}. `\n      + 'A price is identified by pricingAuthorityRef@pricingAuthorityVersion; publish a changed rate as a new version.',\n    );\n  }\n}\n\n/** Whether a call's usage reports the reasoning split. */\nexport function reasoningUsageReportingOf(usage: ProviderUsageQuantities): ReasoningUsageReporting {\n  return typeof usage.reasoningTokens === 'number' && Number.isFinite(usage.reasoningTokens) && usage.reasoningTokens >= 0\n    ? ReasoningUsageReporting.REPORTED\n    : ReasoningUsageReporting.UNREPORTED;\n}\n\n/**\n * The exact cost of one call under `authority`, unrounded. See the file header for the quantity rules.\n */\nexport function computeProviderUsageCallCost(authority: ProviderUsagePricingAuthority, usage: ProviderUsageQuantities): ProviderUsageCostResult {\n  const rateOf = new Map(authority.rates.map((rate) => [rate.category, rate.amountMinorNumerator]));\n  const inputRate = rateOf.get(ProviderUsagePricingCategory.INPUT_TOKEN)!;\n\n  const promptTokens = count(usage.promptTokens);\n  const completionTokens = count(usage.completionTokens);\n  const hasInputSplit = usage.noCacheTokens !== undefined || usage.cacheReadTokens !== undefined || usage.cacheWriteTokens !== undefined;\n  const cacheRead = hasInputSplit ? count(usage.cacheReadTokens) : 0;\n  const cacheWrite = hasInputSplit ? count(usage.cacheWriteTokens) : 0;\n  const noCache = hasInputSplit\n    ? (usage.noCacheTokens !== undefined ? count(usage.noCacheTokens) : Math.max(0, promptTokens - cacheRead - cacheWrite))\n    : promptTokens;\n\n  const pricesReasoningApart = rateOf.has(ProviderUsagePricingCategory.REASONING_TOKEN)\n    && reasoningUsageReportingOf(usage) === ReasoningUsageReporting.REPORTED;\n  const reasoning = pricesReasoningApart ? Math.min(count(usage.reasoningTokens), completionTokens) : 0;\n  const output = completionTokens - reasoning;\n\n  // The tier is decided by the request's WHOLE input quantity, whatever its cache split.\n  const inputQuantity = hasInputSplit ? noCache + cacheRead + cacheWrite : promptTokens;\n  let inputMultiplier = PROVIDER_USAGE_RATE_MULTIPLIER_BASIS_POINTS;\n  let outputMultiplier = PROVIDER_USAGE_RATE_MULTIPLIER_BASIS_POINTS;\n  for (const rule of authority.usageTierRules) {\n    if (inputQuantity > rule.inputTokenThresholdExclusive) {\n      inputMultiplier = rule.inputRateMultiplierBasisPoints;\n      outputMultiplier = rule.outputRateMultiplierBasisPoints;\n    }\n  }\n\n  const amounts: ProviderUsageAmount[] = [];\n  let numerator = ZERO;\n  const add = (category: ProviderUsagePricingCategory, quantity: number, rate: number, multiplier: number): void => {\n    if (quantity === 0) return;\n    amounts.push({ category, quantity });\n    numerator += BigInt(quantity) * BigInt(rate) * BigInt(multiplier);\n  };\n  add(ProviderUsagePricingCategory.INPUT_TOKEN, noCache, inputRate, inputMultiplier);\n  add(ProviderUsagePricingCategory.CACHED_INPUT_TOKEN, cacheRead, rateOf.get(ProviderUsagePricingCategory.CACHED_INPUT_TOKEN) ?? inputRate, inputMultiplier);\n  add(ProviderUsagePricingCategory.CACHE_WRITE_INPUT_TOKEN, cacheWrite, rateOf.get(ProviderUsagePricingCategory.CACHE_WRITE_INPUT_TOKEN) ?? inputRate, inputMultiplier);\n  add(ProviderUsagePricingCategory.OUTPUT_TOKEN, output, rateOf.get(ProviderUsagePricingCategory.OUTPUT_TOKEN)!, outputMultiplier);\n  if (pricesReasoningApart) {\n    add(ProviderUsagePricingCategory.REASONING_TOKEN, reasoning, rateOf.get(ProviderUsagePricingCategory.REASONING_TOKEN)!, outputMultiplier);\n  }\n\n  let denominator = BigInt(authority.unitsDenominator) * BigInt(PROVIDER_USAGE_RATE_MULTIPLIER_BASIS_POINTS);\n  const divisor = gcd(numerator, denominator);\n  numerator /= divisor;\n  denominator /= divisor;\n\n  return {\n    pricingAuthorityRef: authority.pricingAuthorityRef,\n    pricingAuthorityVersion: authority.pricingAuthorityVersion,\n    currency: authority.currency,\n    callCostMinorNumerator: numerator.toString(),\n    callCostUnitsDenominator: Number(denominator),\n    amounts,\n  };\n}\n\n/**\n * An exact running total of minor-unit fractions in ONE currency, rounded up once when read.\n *\n * `add` takes a call's exact cost and the attribution row's share of it (`shareNumerator / shareDenominator`,\n * 1/1 for a whole call). The sum stays a reduced fraction of bigints, so no precision is lost however many\n * rows are added.\n */\nexport class ExactMinorCostTotal {\n  private numerator = ZERO;\n  private denominator = ONE;\n\n  public add(callCostMinorNumerator: string, callCostUnitsDenominator: number, shareNumerator = 1, shareDenominator = 1): void {\n    if (shareDenominator <= 0 || callCostUnitsDenominator <= 0) return;\n    const partNumerator = BigInt(callCostMinorNumerator) * BigInt(Math.max(0, Math.floor(shareNumerator)));\n    const partDenominator = BigInt(callCostUnitsDenominator) * BigInt(Math.floor(shareDenominator));\n    const nextNumerator = this.numerator * partDenominator + partNumerator * this.denominator;\n    const nextDenominator = this.denominator * partDenominator;\n    const divisor = gcd(nextNumerator, nextDenominator);\n    this.numerator = nextNumerator / divisor;\n    this.denominator = nextDenominator / divisor;\n  }\n\n  /** The total, rounded UP to a whole minor unit: `CEILING_AGGREGATE_TO_MINOR_UNIT`, applied once. */\n  public ceilMinor(): bigint {\n    if (this.numerator === ZERO) return ZERO;\n    return (this.numerator + this.denominator - ONE) / this.denominator;\n  }\n}\n"]}

package/dist/esm/external-providers/provider-usage-pricing.example.d.ts

@@ -0,0 +1,12 @@
+import { type ProviderUsagePricingAuthorityInput } from './provider-usage-pricing.shared.schemas';
+/**
+ * Tier-B example (#1598): one provider price, as an application registers it in
+ * `modelCostAccounting.providerUsagePricingAuthorities`.
+ *
+ * The rates are OpenAI's public list price for `gpt-5.6-terra`, observed on 2026-08-13. A firm with a
+ * negotiated contract registers its own numbers instead; that is why the list is the application's.
+ */
+/** @wildo_source:part:start example.config.provider-usage-pricing facet:kind:usage-example facet:audience:app-developer */
+export declare const exampleProviderUsagePricingAuthority: ProviderUsagePricingAuthorityInput;
+/** @wildo_source:part:end example.config.provider-usage-pricing */
+//# sourceMappingURL=provider-usage-pricing.example.d.ts.map

package/dist/esm/external-providers/provider-usage-pricing.example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-usage-pricing.example.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/provider-usage-pricing.example.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,kCAAkC,EACxC,MAAM,yCAAyC,CAAC;AAEjD;;;;;;GAMG;AACH,2HAA2H;AAC3H,eAAO,MAAM,oCAAoC,EAAE,kCA4BlD,CAAC;AACF,mEAAmE"}

package/dist/esm/external-providers/provider-usage-pricing.example.js

@@ -0,0 +1,40 @@
+import { ProviderUsagePricingCategory, ProviderUsagePricingRoundingMode, ProviderUsagePricingTierRuleKind, } from './provider-usage-pricing.shared.schemas.js';
+/**
+ * Tier-B example (#1598): one provider price, as an application registers it in
+ * `modelCostAccounting.providerUsagePricingAuthorities`.
+ *
+ * The rates are OpenAI's public list price for `gpt-5.6-terra`, observed on 2026-08-13. A firm with a
+ * negotiated contract registers its own numbers instead; that is why the list is the application's.
+ */
+/** @wildo_source:part:start example.config.provider-usage-pricing facet:kind:usage-example facet:audience:app-developer */
+export const exampleProviderUsagePricingAuthority = {
+    schemaVersion: 1,
+    pricingAuthorityRef: 'pricing:openai/gpt-5.6-terra',
+    pricingAuthorityVersion: 1,
+    providerRef: 'openai',
+    // The resolved model id exactly as the call records it (the agent's configured model).
+    model: 'gpt-5.6-terra',
+    currency: 'USD',
+    // Rates below are minor units (cents) per million tokens.
+    unitsDenominator: 1_000_000,
+    roundingMode: ProviderUsagePricingRoundingMode.CEILING_AGGREGATE_TO_MINOR_UNIT,
+    rates: [
+        { category: ProviderUsagePricingCategory.INPUT_TOKEN, amountMinorNumerator: 200 },
+        { category: ProviderUsagePricingCategory.CACHED_INPUT_TOKEN, amountMinorNumerator: 20 },
+        { category: ProviderUsagePricingCategory.CACHE_WRITE_INPUT_TOKEN, amountMinorNumerator: 250 },
+        // No REASONING_TOKEN rate: reasoning is priced as output, which is how this provider bills it.
+        { category: ProviderUsagePricingCategory.OUTPUT_TOKEN, amountMinorNumerator: 1_200 },
+    ],
+    // Requests over 272k input tokens are priced at 2x input and 1.5x output.
+    usageTierRules: [{
+            kind: ProviderUsagePricingTierRuleKind.INPUT_TOKEN_QUANTITY_ABOVE,
+            inputTokenThresholdExclusive: 272_000,
+            inputRateMultiplierBasisPoints: 20_000,
+            outputRateMultiplierBasisPoints: 15_000,
+        }],
+    effectiveFrom: '2026-08-13T00:00:00.000Z',
+    sourceRef: 'https://developers.openai.com/api/docs/models/gpt-5.6-terra',
+    sourceVersion: 'observed:2026-08-13',
+};
+/** @wildo_source:part:end example.config.provider-usage-pricing */
+//# sourceMappingURL=provider-usage-pricing.example.js.map

package/dist/esm/external-providers/provider-usage-pricing.example.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-usage-pricing.example.js","sourceRoot":"","sources":["../../../../src/external-providers/provider-usage-pricing.example.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,4BAA4B,EAC5B,gCAAgC,EAChC,gCAAgC,GAEjC,MAAM,yCAAyC,CAAC;AAEjD;;;;;;GAMG;AACH,2HAA2H;AAC3H,MAAM,CAAC,MAAM,oCAAoC,GAAuC;IACtF,aAAa,EAAE,CAAC;IAChB,mBAAmB,EAAE,8BAA8B;IACnD,uBAAuB,EAAE,CAAC;IAC1B,WAAW,EAAE,QAAQ;IACrB,uFAAuF;IACvF,KAAK,EAAE,eAAe;IACtB,QAAQ,EAAE,KAAK;IACf,0DAA0D;IAC1D,gBAAgB,EAAE,SAAS;IAC3B,YAAY,EAAE,gCAAgC,CAAC,+BAA+B;IAC9E,KAAK,EAAE;QACL,EAAE,QAAQ,EAAE,4BAA4B,CAAC,WAAW,EAAE,oBAAoB,EAAE,GAAG,EAAE;QACjF,EAAE,QAAQ,EAAE,4BAA4B,CAAC,kBAAkB,EAAE,oBAAoB,EAAE,EAAE,EAAE;QACvF,EAAE,QAAQ,EAAE,4BAA4B,CAAC,uBAAuB,EAAE,oBAAoB,EAAE,GAAG,EAAE;QAC7F,+FAA+F;QAC/F,EAAE,QAAQ,EAAE,4BAA4B,CAAC,YAAY,EAAE,oBAAoB,EAAE,KAAK,EAAE;KACrF;IACD,0EAA0E;IAC1E,cAAc,EAAE,CAAC;YACf,IAAI,EAAE,gCAAgC,CAAC,0BAA0B;YACjE,4BAA4B,EAAE,OAAO;YACrC,8BAA8B,EAAE,MAAM;YACtC,+BAA+B,EAAE,MAAM;SACxC,CAAC;IACF,aAAa,EAAE,0BAA0B;IACzC,SAAS,EAAE,6DAA6D;IACxE,aAAa,EAAE,qBAAqB;CACrC,CAAC;AACF,mEAAmE","sourcesContent":["import {\n  ProviderUsagePricingCategory,\n  ProviderUsagePricingRoundingMode,\n  ProviderUsagePricingTierRuleKind,\n  type ProviderUsagePricingAuthorityInput,\n} from './provider-usage-pricing.shared.schemas';\n\n/**\n * Tier-B example (#1598): one provider price, as an application registers it in\n * `modelCostAccounting.providerUsagePricingAuthorities`.\n *\n * The rates are OpenAI's public list price for `gpt-5.6-terra`, observed on 2026-08-13. A firm with a\n * negotiated contract registers its own numbers instead; that is why the list is the application's.\n */\n/** @wildo_source:part:start example.config.provider-usage-pricing facet:kind:usage-example facet:audience:app-developer */\nexport const exampleProviderUsagePricingAuthority: ProviderUsagePricingAuthorityInput = {\n  schemaVersion: 1,\n  pricingAuthorityRef: 'pricing:openai/gpt-5.6-terra',\n  pricingAuthorityVersion: 1,\n  providerRef: 'openai',\n  // The resolved model id exactly as the call records it (the agent's configured model).\n  model: 'gpt-5.6-terra',\n  currency: 'USD',\n  // Rates below are minor units (cents) per million tokens.\n  unitsDenominator: 1_000_000,\n  roundingMode: ProviderUsagePricingRoundingMode.CEILING_AGGREGATE_TO_MINOR_UNIT,\n  rates: [\n    { category: ProviderUsagePricingCategory.INPUT_TOKEN, amountMinorNumerator: 200 },\n    { category: ProviderUsagePricingCategory.CACHED_INPUT_TOKEN, amountMinorNumerator: 20 },\n    { category: ProviderUsagePricingCategory.CACHE_WRITE_INPUT_TOKEN, amountMinorNumerator: 250 },\n    // No REASONING_TOKEN rate: reasoning is priced as output, which is how this provider bills it.\n    { category: ProviderUsagePricingCategory.OUTPUT_TOKEN, amountMinorNumerator: 1_200 },\n  ],\n  // Requests over 272k input tokens are priced at 2x input and 1.5x output.\n  usageTierRules: [{\n    kind: ProviderUsagePricingTierRuleKind.INPUT_TOKEN_QUANTITY_ABOVE,\n    inputTokenThresholdExclusive: 272_000,\n    inputRateMultiplierBasisPoints: 20_000,\n    outputRateMultiplierBasisPoints: 15_000,\n  }],\n  effectiveFrom: '2026-08-13T00:00:00.000Z',\n  sourceRef: 'https://developers.openai.com/api/docs/models/gpt-5.6-terra',\n  sourceVersion: 'observed:2026-08-13',\n};\n/** @wildo_source:part:end example.config.provider-usage-pricing */\n"]}

package/dist/esm/external-providers/provider-usage-pricing.shared.schemas.d.ts

@@ -1,25 +1,48 @@
 import { z } from 'zod';
-/** Billable provider-usage dimensions. These are acquisition-cost categories, not customer billing units. */
+/**
+ * @wildo_source:part:start saas.models.provider-usage-pricing-authority facet:layer:shared facet:family:config facet:audience:app-developer
+ *
+ * Billable provider-usage dimensions. These are ACQUISITION-cost categories (what the application pays a
+ * model provider), not customer billing units.
+ */
 export declare enum ProviderUsagePricingCategory {
+    /** Input tokens read without a prompt cache (or every input token, when the provider reported no split). */
     INPUT_TOKEN = "INPUT_TOKEN",
+    /** Input tokens served from a prompt cache. Priced at `INPUT_TOKEN` when the authority declares no rate. */
     CACHED_INPUT_TOKEN = "CACHED_INPUT_TOKEN",
+    /** Input tokens written into a prompt cache. Priced at `INPUT_TOKEN` when the authority declares no rate. */
     CACHE_WRITE_INPUT_TOKEN = "CACHE_WRITE_INPUT_TOKEN",
+    /** Output tokens. Includes reasoning unless the authority declares a `REASONING_TOKEN` rate. */
     OUTPUT_TOKEN = "OUTPUT_TOKEN",
+    /**
+     * Reasoning tokens, when the authority prices them apart. They are then SUBTRACTED from the output
+     * quantity: every provider already counts reasoning inside its output total, so reasoning is never
+     * billed twice.
+     */
     REASONING_TOKEN = "REASONING_TOKEN"
 }
 export declare const PROVIDER_USAGE_PRICING_CATEGORY_ORDER: readonly ProviderUsagePricingCategory[];
-/** V1 rounds once after aggregating every supported category into the authority's common denominator. */
+/**
+ * How a TOTAL is rounded to a whole minor currency unit. There is one mode: exact per-call costs are summed
+ * first and the sum is rounded up once, per reported total (#1598 review F11). Rounding each call up would
+ * overstate an embedding-heavy case by up to one minor unit per call.
+ */
 export declare enum ProviderUsagePricingRoundingMode {
     CEILING_AGGREGATE_TO_MINOR_UNIT = "CEILING_AGGREGATE_TO_MINOR_UNIT"
 }
 /** Closed trigger vocabulary for provider pricing tiers. */
 export declare enum ProviderUsagePricingTierRuleKind {
+    /** The whole request is priced at the tier when its INPUT quantity (all prompt tokens) exceeds the threshold. */
     INPUT_TOKEN_QUANTITY_ABOVE = "INPUT_TOKEN_QUANTITY_ABOVE"
 }
+/** A rate multiplier is written in basis points: 10 000 = ×1. */
+export declare const PROVIDER_USAGE_RATE_MULTIPLIER_BASIS_POINTS = 10000;
 export declare const ProviderUsagePricingTierRuleSchema: z.ZodObject<{
     kind: z.ZodLiteral<ProviderUsagePricingTierRuleKind>;
     inputTokenThresholdExclusive: z.ZodNumber;
+    /** Multiplier on the three input categories, in basis points (≥ 10 000: a tier never discounts). */
     inputRateMultiplierBasisPoints: z.ZodNumber;
+    /** Multiplier on output and reasoning, in basis points (≥ 10 000). */
     outputRateMultiplierBasisPoints: z.ZodNumber;
 }, z.core.$strict>;
 export type ProviderUsagePricingTierRule = z.infer<typeof ProviderUsagePricingTierRuleSchema>;
@@ -30,20 +53,35 @@ export declare const ProviderUsagePricingRateSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type ProviderUsagePricingRate = z.infer<typeof ProviderUsagePricingRateSchema>;
 /**
- * Canonical registered provider/model acquisition-cost authority.
+ * One provider/model acquisition-cost price, REGISTERED BY THE APPLICATION in
+ * `modelCostAccounting.providerUsagePricingAuthorities` (#1598), because rates are negotiated: a list price
+ * shipped by the engine would be wrong for every firm with a contract, and would go stale.
  *
- * This is deliberately separate from billing `PriceSchema`, which represents what an application
- * charges its customers. Runtime budget consumers retain this record's identity/digest and never
- * copy its rates into a workflow-local table.
+ * A price is identified by `pricingAuthorityRef@pricingAuthorityVersion`; the registry refuses a duplicate
+ * pair at startup. A call is priced by the authority whose `providerRef` and `model` equal the call's
+ * recorded provider and model, choosing the highest version whose `effectiveFrom` is not after the call.
+ * No match leaves the call `UNPRICED`, never priced at zero.
+ *
+ * Deliberately separate from billing's `PriceSchema`, which is what the application CHARGES its customers.
+ *
+ * History: an earlier revision carried `implementationDigest` and `pricingDigest` and a "sealed basis" type
+ * saying an application could "neither choose rates" nor mint the digest. Both were remnants of the retired
+ * digest era (one-source-of-truth Rule 0) and contradicted the decision that the application registers its
+ * rates. `modelRef` / `modelVersion` were replaced by `model`, the one id a call actually records.
  */
-export declare const ProviderUsagePricingAuthorityV1Schema: z.ZodObject<{
+export declare const ProviderUsagePricingAuthoritySchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
+    /** Stable name of this price list entry, for example `pricing:openai/gpt-5.6-terra`. */
     pricingAuthorityRef: z.ZodString;
+    /** Version of that entry. A rate change is a new version with a later `effectiveFrom`, never an edit. */
     pricingAuthorityVersion: z.ZodNumber;
+    /** The provider the call went to, exactly as the call records it (`openai`, `anthropic`, ...). */
     providerRef: z.ZodString;
-    modelRef: z.ZodString;
-    modelVersion: z.ZodString;
+    /** The resolved model id, exactly as the call records it (`gpt-5.6-terra`, `claude-opus-4-8`, ...). */
+    model: z.ZodString;
+    /** ISO 4217 code. Currencies are never converted: every total is per currency. */
     currency: z.ZodString;
+    /** The number of billable units each rate's `amountMinorNumerator` is charged per (1 000 000 for "per million tokens"). */
     unitsDenominator: z.ZodNumber;
     roundingMode: z.ZodLiteral<ProviderUsagePricingRoundingMode>;
     rates: z.ZodArray<z.ZodObject<{
@@ -55,45 +93,43 @@ export declare const ProviderUsagePricingAuthorityV1Schema: z.ZodObject<{
     usageTierRules: z.ZodArray<z.ZodObject<{
         kind: z.ZodLiteral<ProviderUsagePricingTierRuleKind>;
         inputTokenThresholdExclusive: z.ZodNumber;
+        /** Multiplier on the three input categories, in basis points (≥ 10 000: a tier never discounts). */
         inputRateMultiplierBasisPoints: z.ZodNumber;
+        /** Multiplier on output and reasoning, in basis points (≥ 10 000). */
         outputRateMultiplierBasisPoints: z.ZodNumber;
     }, z.core.$strict>>;
+    /** From when this version applies to a call (inclusive). */
     effectiveFrom: z.ZodISODateTime;
+    /** Where the rates come from: a public price page, a contract reference. Provenance only. */
     sourceRef: z.ZodString;
     sourceVersion: z.ZodString;
-    implementationDigest: z.ZodString;
-    pricingDigest: z.ZodString;
 }, z.core.$strict>;
-export type ProviderUsagePricingAuthorityV1 = z.infer<typeof ProviderUsagePricingAuthorityV1Schema>;
-/**
- * Registry input owned by provider/model configuration. The backend calculator
- * supplies its own implementation identity and seals the final authority, so
- * an application or workflow can neither choose rates nor mint the algorithm
- * digest it later asks the registry to trust.
- */
-export type ProviderUsagePricingAuthorityBasisV1 = Omit<ProviderUsagePricingAuthorityV1, 'implementationDigest' | 'pricingDigest' | 'rates' | 'usageTierRules'> & {
-    readonly rates: readonly ProviderUsagePricingRate[];
-    readonly usageTierRules: readonly ProviderUsagePricingTierRule[];
-};
-/**
- * Canonical acquisition-cost basis for the selected app-creation model.
- *
- * The source is the provider's public model page observed on 2026-08-13. This
- * is not customer billing data and is never copied into a Work Cycle or Driver
- * request; those consumers retain only the sealed registry identity.
- */
-export declare const OPENAI_GPT_5_6_TERRA_PROVIDER_USAGE_PRICING_BASIS_V1: ProviderUsagePricingAuthorityBasisV1;
+export type ProviderUsagePricingAuthority = z.infer<typeof ProviderUsagePricingAuthoritySchema>;
+export type ProviderUsagePricingAuthorityInput = z.input<typeof ProviderUsagePricingAuthoritySchema>;
+/** @wildo_source:part:end saas.models.provider-usage-pricing-authority */
+/** One priced quantity of one category, as the calculator derived it from a call's usage. */
 export declare const ProviderUsageAmountSchema: z.ZodObject<{
     category: z.ZodEnum<typeof ProviderUsagePricingCategory>;
     quantity: z.ZodNumber;
 }, z.core.$strict>;
 export type ProviderUsageAmount = z.infer<typeof ProviderUsageAmountSchema>;
+/**
+ * The EXACT cost of one call under one authority, unrounded (#1598 F11):
+ * `callCostMinorNumerator / callCostUnitsDenominator` minor currency units.
+ *
+ * The numerator is a decimal INTEGER STRING because it is an exact rational part and must survive both
+ * adapters without floating-point loss; the denominator is small enough to stay a number.
+ */
 export declare const ProviderUsageCostResultSchema: z.ZodObject<{
     pricingAuthorityRef: z.ZodString;
     pricingAuthorityVersion: z.ZodNumber;
-    pricingDigest: z.ZodString;
     currency: z.ZodString;
-    amountMinor: z.ZodNumber;
+    callCostMinorNumerator: z.ZodString;
+    callCostUnitsDenominator: z.ZodNumber;
+    amounts: z.ZodArray<z.ZodObject<{
+        category: z.ZodEnum<typeof ProviderUsagePricingCategory>;
+        quantity: z.ZodNumber;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type ProviderUsageCostResult = z.infer<typeof ProviderUsageCostResultSchema>;
 //# sourceMappingURL=provider-usage-pricing.shared.schemas.d.ts.map

package/dist/esm/external-providers/provider-usage-pricing.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-usage-pricing.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/provider-usage-pricing.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB,6GAA6G;AAC7G,oBAAY,4BAA4B;IACtC,WAAW,gBAAgB;IAC3B,kBAAkB,uBAAuB;IACzC,uBAAuB,4BAA4B;IACnD,YAAY,iBAAiB;IAC7B,eAAe,oBAAoB;CACpC;AAED,eAAO,MAAM,qCAAqC,EAAE,SAAS,4BAA4B,EAMvF,CAAC;AAEH,yGAAyG;AACzG,oBAAY,gCAAgC;IAC1C,+BAA+B,oCAAoC;CACpE;AAED,4DAA4D;AAC5D,oBAAY,gCAAgC;IAC1C,0BAA0B,+BAA+B;CAC1D;AAID,eAAO,MAAM,kCAAkC;;;;;kBAK7C,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F,eAAO,MAAM,8BAA8B;;IAEzC,0EAA0E;;kBAE1E,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF;;;;;;GAMG;AACH,eAAO,MAAM,qCAAqC;;;;;;;;;;;;QAZhD,0EAA0E;;;IAuB1E,mFAAmF;;;;;;;;;;;;kBA2BnF,CAAC;AACH,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qCAAqC,CAAC,CAAC;AAEpG;;;;;GAKG;AACH,MAAM,MAAM,oCAAoC,GAAG,IAAI,CACrD,+BAA+B,EAC/B,sBAAsB,GAAG,eAAe,GAAG,OAAO,GAAG,gBAAgB,CACtE,GAAG;IACF,QAAQ,CAAC,KAAK,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACpD,QAAQ,CAAC,cAAc,EAAE,SAAS,4BAA4B,EAAE,CAAC;CAClE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oDAAoD,EAAE,oCA2BjE,CAAC;AAEH,eAAO,MAAM,yBAAyB;;;kBAGpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,6BAA6B;;;;;;kBAMxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC"}
+{"version":3,"file":"provider-usage-pricing.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/external-providers/provider-usage-pricing.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;;;;GAKG;AACH,oBAAY,4BAA4B;IACtC,4GAA4G;IAC5G,WAAW,gBAAgB;IAC3B,4GAA4G;IAC5G,kBAAkB,uBAAuB;IACzC,6GAA6G;IAC7G,uBAAuB,4BAA4B;IACnD,gGAAgG;IAChG,YAAY,iBAAiB;IAC7B;;;;OAIG;IACH,eAAe,oBAAoB;CACpC;AAED,eAAO,MAAM,qCAAqC,EAAE,SAAS,4BAA4B,EAMvF,CAAC;AAEH;;;;GAIG;AACH,oBAAY,gCAAgC;IAC1C,+BAA+B,oCAAoC;CACpE;AAED,4DAA4D;AAC5D,oBAAY,gCAAgC;IAC1C,iHAAiH;IACjH,0BAA0B,+BAA+B;CAC1D;AAED,iEAAiE;AACjE,eAAO,MAAM,2CAA2C,QAAS,CAAC;AAElE,eAAO,MAAM,kCAAkC;;;IAG7C,oGAAoG;;IAEpG,sEAAsE;;kBAEtE,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F,eAAO,MAAM,8BAA8B;;IAEzC,0EAA0E;;kBAE1E,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mCAAmC;;IAE9C,wFAAwF;;IAExF,yGAAyG;;IAEzG,kGAAkG;;IAElG,uGAAuG;;IAEvG,kFAAkF;;IAElF,2HAA2H;;;;;QAlC3H,0EAA0E;;;IAsC1E,mFAAmF;;;;QA/CnF,oGAAoG;;QAEpG,sEAAsE;;;IA+CtE,4DAA4D;;IAE5D,6FAA6F;;;kBAuB7F,CAAC;AACH,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mCAAmC,CAAC,CAAC;AAChG,MAAM,MAAM,kCAAkC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mCAAmC,CAAC,CAAC;AACrG,0EAA0E;AAE1E,6FAA6F;AAC7F,eAAO,MAAM,yBAAyB;;;kBAGpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;kBAOxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC"}