@bymax-one/nest-ai-tokens 1.0.3 → 1.0.4

package/CHANGELOG.md

@@ -8,6 +8,28 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and
 
 ## [Unreleased]
 
+## [1.0.4] - 2026-08-10
+
+Remediation of a local audit's settlement findings (merged in #65). No API changed.
+
+### Fixed
+
+- **Negative usage can no longer credit the wallet or budget.** `clampUsageCounts` floors every
+  token count — and the provider-reported cost (`providerReportedCostNanoUsd`) — at zero before the
+  signed settlement leg. A normalizer that computes a field by subtraction (OpenRouter's
+  `prompt - cached`), or a provider that reports a negative `usage.cost`, would otherwise credit
+  back more than was reserved and drive budget consumption negative.
+- **Streaming captures are clamped like non-stream captures.** `finalizeCaptureUsage` now routes
+  the `StreamUsageCollector` final through `normalizeCaptureUsage`, so a provider-final stream
+  carrying negative counts or cost no longer bypasses the floor and reaches settlement raw.
+
+### Documentation
+
+- `RecordInput.occurredAt` documents its trust model: it is a deliberate backfill feature, honoured
+  as given because `record()`'s input is trusted host input, and a host that forwards a value an
+  untrusted end user controls must validate it first — a back-dated timestamp selects a historical
+  price and an earlier budget window.
+
 ## [1.0.3] - 2026-08-06
 
 ### Fixed
@@ -193,5 +215,6 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.0.0]: https://github.com/bymaxone/nest-ai-tokens/releases/tag/v1.0.0
 [1.0.1]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.0.0...v1.0.1
 [1.0.2]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.0.1...v1.0.2
+[1.0.4]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.0.3...v1.0.4
 [1.0.3]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.0.2...v1.0.3
-[Unreleased]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.0.3...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.0.4...HEAD

package/dist/server/index.cjs

@@ -2126,6 +2126,19 @@ function tokenCountsOf(usage) {
 function sumTokenCounts(counts) {
   return TOKEN_FIELDS.reduce((total, field) => total + counts[field], 0);
 }
+function clampUsageCounts(usage) {
+  const counts = tokenCountsOf(usage);
+  const clamped = zeroTokenCounts();
+  for (const field of TOKEN_FIELDS) {
+    clamped[field] = counts[field] < 0 ? 0 : counts[field];
+  }
+  const result = { ...usage, ...clamped };
+  const cost = usage.providerReportedCostNanoUsd;
+  if (cost !== void 0 && cost < 0n) {
+    return { ...result, providerReportedCostNanoUsd: 0n };
+  }
+  return result;
+}
 function isNormalizedUsage(usage) {
   if (typeof usage !== "object" || usage === null) return false;
   const candidate = usage;
@@ -2202,10 +2215,10 @@ async function resolveTokenEstimate(pricing, context, tokens, serviceTier, at) {
   return { provider, model, operation: "chat", serviceTier, rawEstimateNanoUsd, estimatedTokens: tokens, tokenCounts };
 }
 function normalizeCaptureUsage(usage, normalizer) {
-  if (isNormalizedUsage(usage)) return usage;
+  if (isNormalizedUsage(usage)) return clampUsageCounts(usage);
   if (normalizer !== void 0) {
     try {
-      return normalizer(usage);
+      return clampUsageCounts(normalizer(usage));
     } catch (error) {
       if (error instanceof AiTokensException) throw error;
       throw new AiTokensException("AI_TOKENS_USAGE_MALFORMED", void 0, { reason: "the normalizer could not read the usage token fields" });
@@ -2659,9 +2672,9 @@ exports.MeteringService = class MeteringService {
     if (usage instanceof StreamUsageCollector) {
       const finalized = await usage.finalize();
       if (usage.usedFallback && finalized.inputTokens === 0 && hold.estimatedTokens > 0) {
-        return { ...finalized, inputTokens: hold.estimatedTokens };
+        return normalizeCaptureUsage({ ...finalized, inputTokens: hold.estimatedTokens });
       }
-      return finalized;
+      return normalizeCaptureUsage(finalized);
     }
     return normalizeCaptureUsage(usage, preset2?.normalizer);
   }

package/dist/server/index.d.cts

@@ -2553,7 +2553,14 @@ interface RecordInput {
     normalizer?: UsageNormalizer;
     /** The per-call metering context (trusted input from the host's auth layer). */
     context: MeteringContext;
-    /** When the call happened; defaults to now (backfills pass the original time). */
+    /**
+     * When the call happened; defaults to now. Backfills deliberately pass the original time so a
+     * usage record imported late still lands in the price version and budget window in effect when
+     * it actually occurred. Because that timestamp selects both, it is honoured as given — it is
+     * trusted host input, like the rest of {@link MeteringContext}. A host that forwards a value an
+     * untrusted end user controls must validate it first, since a back-dated `occurredAt` would pick
+     * a historical price and an earlier budget window.
+     */
     occurredAt?: Date;
     /**
      * The ONLY path prompt/completion text enters the library (spec §14.2): masked +

package/dist/server/index.d.ts

@@ -2553,7 +2553,14 @@ interface RecordInput {
     normalizer?: UsageNormalizer;
     /** The per-call metering context (trusted input from the host's auth layer). */
     context: MeteringContext;
-    /** When the call happened; defaults to now (backfills pass the original time). */
+    /**
+     * When the call happened; defaults to now. Backfills deliberately pass the original time so a
+     * usage record imported late still lands in the price version and budget window in effect when
+     * it actually occurred. Because that timestamp selects both, it is honoured as given — it is
+     * trusted host input, like the rest of {@link MeteringContext}. A host that forwards a value an
+     * untrusted end user controls must validate it first, since a back-dated `occurredAt` would pick
+     * a historical price and an earlier budget window.
+     */
     occurredAt?: Date;
     /**
      * The ONLY path prompt/completion text enters the library (spec §14.2): masked +

package/dist/server/index.mjs

@@ -2124,6 +2124,19 @@ function tokenCountsOf(usage) {
 function sumTokenCounts(counts) {
   return TOKEN_FIELDS.reduce((total, field) => total + counts[field], 0);
 }
+function clampUsageCounts(usage) {
+  const counts = tokenCountsOf(usage);
+  const clamped = zeroTokenCounts();
+  for (const field of TOKEN_FIELDS) {
+    clamped[field] = counts[field] < 0 ? 0 : counts[field];
+  }
+  const result = { ...usage, ...clamped };
+  const cost = usage.providerReportedCostNanoUsd;
+  if (cost !== void 0 && cost < 0n) {
+    return { ...result, providerReportedCostNanoUsd: 0n };
+  }
+  return result;
+}
 function isNormalizedUsage(usage) {
   if (typeof usage !== "object" || usage === null) return false;
   const candidate = usage;
@@ -2200,10 +2213,10 @@ async function resolveTokenEstimate(pricing, context, tokens, serviceTier, at) {
   return { provider, model, operation: "chat", serviceTier, rawEstimateNanoUsd, estimatedTokens: tokens, tokenCounts };
 }
 function normalizeCaptureUsage(usage, normalizer) {
-  if (isNormalizedUsage(usage)) return usage;
+  if (isNormalizedUsage(usage)) return clampUsageCounts(usage);
   if (normalizer !== void 0) {
     try {
-      return normalizer(usage);
+      return clampUsageCounts(normalizer(usage));
     } catch (error) {
       if (error instanceof AiTokensException) throw error;
       throw new AiTokensException("AI_TOKENS_USAGE_MALFORMED", void 0, { reason: "the normalizer could not read the usage token fields" });
@@ -2657,9 +2670,9 @@ var MeteringService = class {
     if (usage instanceof StreamUsageCollector) {
       const finalized = await usage.finalize();
       if (usage.usedFallback && finalized.inputTokens === 0 && hold.estimatedTokens > 0) {
-        return { ...finalized, inputTokens: hold.estimatedTokens };
+        return normalizeCaptureUsage({ ...finalized, inputTokens: hold.estimatedTokens });
       }
-      return finalized;
+      return normalizeCaptureUsage(finalized);
     }
     return normalizeCaptureUsage(usage, preset2?.normalizer);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-ai-tokens",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "AI token metering & usage-based billing for NestJS 11: provider usage normalizer (×9), versioned effective-dated pricing, immutable append-only ledger, prepaid wallets, multi-dimension budgets, and markup/margin. Zero runtime dependencies.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -85,8 +85,8 @@
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
     "mutation": "stryker run",
+    "mutation:full": "node -e \"require('node:fs').rmSync('reports/stryker-incremental.json',{force:true,recursive:true})\" && stryker run",
     "mutation:dry-run": "stryker run --dryRunOnly",
-    "mutation:incremental": "stryker run --incremental",
     "prepare": "prisma generate",
     "prepublishOnly": "pnpm clean && pnpm typecheck && pnpm lint && pnpm check:mutants && pnpm test:cov:all && pnpm build && pnpm size && pnpm check:published",
     "release": "npm publish --provenance --access public",