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

package/CHANGELOG.md

@@ -6,16 +6,49 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and
 
 ---
 
-## [Unreleased]
+## [1.1.0] - 2026-08-11
+
+### Changed
+
+- **BREAKING: `ioredis` peer moved to `^6.0.0`** (was `^5.0.0`; the ranges are disjoint, so an
+  ioredis 5 consumer no longer satisfies the contract). It aligns the `./redis` budget counter
+  with `@bymax-one/nest-queue@1.2.0`, so a backend that consumes both resolves one shared `ioredis`.
+  ioredis 6 defaults to RESP3 but keeps `replyMapping: "legacy"`, leaving reply shapes unchanged at
+  runtime; the store's URL-only `new Redis(url)` construction is untouched by the RESP3 options
+  typing break, so no source changed.
+- **Mutation gate raised to a perfect score.** `stryker.config.json` now breaks below 100 (`break`,
+  `high` and `low` are all 100), so no surviving mutant can pass the gate.
+
+## [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
 
 - **Every suppression reason was dropped from the mutation report.** All 249 `// Stryker
-  disable` directives in the source wrote their justification after `--`. Stryker reads a
+disable` directives in the source wrote their justification after `--`. Stryker reads a
   directive with one regular expression, `/^\s?Stryker (disable|restore)(?: (next-line))?
-  ([a-zA-Z, ]+)(?::(.+)?)?/`, whose mutator list accepts letters, commas and spaces only
+([a-zA-Z, ]+)(?::(.+)?)?/`, whose mutator list accepts letters, commas and spaces only
   and which captures the reason exclusively after a colon. A `-` therefore closed the
   mutator list and left the reason unmatched, so each directive still silenced its mutant
   but the report recorded Stryker's fallback text, `Ignored using a comment`. The README
@@ -49,14 +82,14 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and
   implement `emitDecoratorMetadata` because it does not replicate TypeScript's type
   system — so the second key was never there. The first two parameters had neither, and
   the container threw `Nest can't resolve dependencies of the MeteringInterceptor
-  (?, +, Symbol(BYMAX_AI_TOKENS_OPTIONS))` before any provider was created. Both now
+(?, +, Symbol(BYMAX_AI_TOKENS_OPTIONS))` before any provider was created. Both now
   carry `@Inject`.
 
 ### Changed
 
 - `emitDecoratorMetadata` is `false` in `tsconfig.json`. It was `true`, which was never
   true of the artifact: tsup prints `You have emitDecoratorMetadata enabled but
-  @swc/core was not installed, skipping swc plugin` on every build, and that warning had
+@swc/core was not installed, skipping swc plugin` on every build, and that warning had
   been printed on every build of this package. Turning it off makes the source compile
   the way the bundle is built, so a parameter that depends on reflected types now fails
   where it is cheap to see.
@@ -117,7 +150,6 @@ have regressed from. They are kept because the reasoning is worth having.
 - **Zero runtime dependencies** — `"dependencies": {}`. All runtime functionality via peer dependencies.
 - **100% unit test coverage** — 804 tests; 10-scenario Testcontainers e2e suite; Stryker mutation gate at 100.00% (0 surviving mutants, break 95).
 
-
 - **Prisma 7 support, alongside Prisma 6.** The declared peer range has always
   been `>=6.0.0`, but nothing verified the claim; the end-to-end suite now runs
   against Prisma 7 and a real PostgreSQL, and it is what surfaced the conflict
@@ -133,7 +165,7 @@ have regressed from. They are kept because the reasoning is worth having.
 - **`pnpm check:exports`** runs `attw --pack . --profile strict` against the packed
   tarball, which is what surfaced both resolution defects above.
 - **`pnpm check:runtime`** packs the tarball, lays it out the way npm would, and
-  asserts in ESM *and* CommonJS that an error thrown by `PrismaAiTokensStore`
+  asserts in ESM _and_ CommonJS that an error thrown by `PrismaAiTokensStore`
   satisfies `instanceof AiTokensException` against the class the root exports. No
   source-based suite can observe this: the unit tests map the subpath specifiers to
   `src` and therefore see a single copy. Both gates run in CI.
@@ -193,5 +225,7 @@ 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.1.0]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.0.4...v1.1.0
+[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/README.md

@@ -715,7 +715,7 @@ that reads a tenant id from request input lets a caller bill someone else.
 - **Runtime:** Node.js 24+
 - **Framework:** NestJS 11 (guard + interceptor, `ConfigurableModuleBuilder`, `Symbol()` tokens)
 - **Persistence:** `@prisma/client ^6 || ^7` (peer) over PostgreSQL — both majors supported
-- **Budget acceleration:** `ioredis ^5` (peer), optional
+- **Budget acceleration:** `ioredis ^6` (peer), optional
 - **Events:** `@nestjs/event-emitter >=2` (peer), optional
 - **Telemetry:** `@opentelemetry/api ^1.9` (peer), optional
 - **Build:** tsup — ESM + CJS per subpath, with `.d.ts` _and_ `.d.cts` declarations
@@ -730,7 +730,7 @@ This library decides what a customer is charged, so the suite is held to a bar b
 tests pass".
 
 - ✅ **100% line coverage** — statements, branches, functions and lines, enforced as a gate
-- ✅ **100% mutation score against a `break: 95` gate** — the gate is the floor a run must
+- ✅ **100% mutation score against a `break: 100` gate** — the gate is the floor a run must
   clear; the score the suite actually reaches is 100%, verified with
   [Stryker](https://stryker-mutator.io/) ([report](./docs/mutation_testing_results.md))
 - ✅ **Real PostgreSQL in e2e** — Testcontainers, so the unique constraint that prevents a
@@ -752,7 +752,7 @@ tests pass".
 pnpm test          # unit tests
 pnpm test:cov      # unit tests with the 100% coverage gate
 pnpm test:e2e      # end-to-end against PostgreSQL (requires Docker)
-pnpm mutation      # Stryker mutation testing (break: 95)
+pnpm mutation      # Stryker mutation testing (break: 100)
 pnpm typecheck     # tsc strict check
 pnpm lint          # ESLint
 pnpm build && pnpm size   # bundle-size budgets

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.1.0",
   "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",
@@ -106,7 +106,7 @@
     "reflect-metadata": "^0.2.0",
     "rxjs": "^7.8.0",
     "@prisma/client": "^6.0.0 || ^7.0.0",
-    "ioredis": "^5.0.0",
+    "ioredis": "^6.0.0",
     "@nestjs/event-emitter": ">=2.0.0",
     "@opentelemetry/api": "^1.9.0"
   },
@@ -158,7 +158,7 @@
     "eslint": "^9.39.5",
     "eslint-config-prettier": "^10.1.8",
     "fast-check": "^4.9.0",
-    "ioredis": "^5.4.2",
+    "ioredis": "^6.0.0",
     "jest": "^30.4.2",
     "prettier": "^3.9.6",
     "prisma": "^7.9.1",