@bymax-one/nest-ai-tokens 1.1.1 → 1.1.3

package/CHANGELOG.md

@@ -6,6 +6,134 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and
 
 ---
 
+## [Unreleased]
+
+## [1.1.3] - 2026-10-31
+
+**Billing:** if you set prices with `upsertPrice` for a model the snapshot also prices while
+`pricing.seedFromSnapshot` was on, a restart of an earlier version could replace them with the
+snapshot. Run the two queries under the seed entry below to look for affected rows.
+
+### Fixed
+
+- **`forRootAsync({ useFactory })` accepts a factory with typed parameters.** The declared
+  signature `(...args: unknown[]) => ...` rejected the form Nest code normally writes,
+  `useFactory: (config: ConfigService) => ...`, so every consumer had to take `unknown` and cast.
+  The member is now declared with method syntax, which makes its parameters bivariant, and the
+  variadic form still compiles. No runtime change.
+
+  **Apply:** no action required. A cast such as `(prisma: unknown) => ... prisma as PrismaService`
+  can be replaced by a typed parameter.
+
+- **A disabled wallet, budget or guard service no longer injects as `null` with `forRootAsync`.**
+  `forRootAsync` resolves its options after the providers are declared, so it registers
+  `WalletService`, `BudgetService` and `BudgetGuard` even when the options leave them out, and it
+  used to inject `null`: a consumer got `TypeError: Cannot read properties of null` at its first
+  call, with a type that said `WalletService`. It now injects a stand-in whose methods throw
+  `AI_TOKENS_INVALID_CONFIG`; the reason names the missing options block, `wallets` or
+  `budgets`. The stand-in is an instance of the service's class. `forRoot` is unchanged: it does not register a disabled service.
+
+  **Apply:** code that tested the injected service for `null` to detect a disabled feature must
+  check its own options instead.
+
+- **`AI_TOKENS_NOT_CONFIGURED` is documented as reserved.** Nest finishes resolving the async
+  options before it builds any service, so nothing raises it.
+
+- **A restart no longer reverts prices the host set, and the snapshot seed no longer adds rows.**
+  With `pricing.seedFromSnapshot` on (the default), every boot re-ran each seed row through
+  `upsertPrice`, which closes the open row of that model and inserts a new one. A second boot
+  against a seeded database added one closed zero-length row and one new open row per seed row
+  (34 rows after two boots, 17 closed), and a rate the host had set with `upsertPrice` was
+  closed before its own start date while the snapshot row became the open row again, so the
+  snapshot price silently replaced the host's price on every restart. The seed now inserts
+  only the model, operation and tier combinations that have no row at all, in one transaction
+  under a per-combination `pg_advisory_xact_lock`, and never touches existing history. The
+  session-scoped `pg_try_advisory_lock` the seed used is no longer taken: a session lock stays
+  held until its connection closes, so whether a boot seeded depended on which old connections
+  were still alive. `PrismaAiTokensStore.acquireSeedLock` stays for compatibility and is
+  deprecated. `IPricingStore` gains the optional method `seedPrice`; a custom store without it
+  is seeded from `getPriceHistory` and `upsertPrice`, which is not atomic across replicas.
+
+  **Apply:** a 1.1.x database may hold duplicated zero-length rows and reverted overrides. Find
+  them with the queries below; deleting or re-entering rows is your call, nothing here changes
+  data.
+
+  ```sql
+  -- Rows the old seed closed at the instant they began (one per extra boot).
+  SELECT "provider", "model", "operation", "serviceTier", COUNT(*) AS "rows"
+  FROM "ai_model_prices"
+  WHERE "effectiveTo" = "effectiveFrom"
+  GROUP BY 1, 2, 3, 4;
+
+  -- Rows closed before their own start: a price set with upsertPrice that a later boot reverted.
+  SELECT "provider", "model", "operation", "serviceTier", "inputNanoUsdPerMillion",
+         "effectiveFrom", "effectiveTo"
+  FROM "ai_model_prices"
+  WHERE "effectiveTo" < "effectiveFrom";
+  ```
+
+  A row from the second query is a rate you set; re-enter it with `upsertPrice` at its original
+  `effectiveFrom`.
+
+### Added
+
+- `ChainVerification`, the result of `LedgerService.verifyChain`, is exported by name from the
+  package root (a type only).
+
+### Documentation
+
+- **The README says how to create the tables and what the public API is.** The SQL migration and
+  the Prisma schema fragment ship in the package under `dist/prisma/` but were not mentioned; the
+  setup section now names both. The API reference lists the decorators (including `@AiFeature`),
+  the money and ledger helpers, the catalogs, the injection tokens and `CounterValueOutOfRangeError`.
+  The `budgets.defaultPolicy` Type column read `'block' | 'alert'`; the type is
+  `'block' | 'throttle' | 'allow'`. The content sidecar section states that the library ships no
+  `IContentStore` implementation or table, and the configuration section describes the
+  `forRootAsync` and `forRoot` behaviour for a disabled wallet or budget block. The 1.0.0 entries
+  that named an `OtelTelemetrySink` and a six-step resolution chain were corrected to the code.
+
+- **The README now matches the code.** The configuration table gave the wrong default for
+  `pricing.seedFromSnapshot` (`true`, not `false`), `budgets.defaultPolicy` (`'block'`, not
+  `'alert'`) and `holds.ttlSeconds` (`3600`, not `300`), and gave no default for
+  `wallets.creditRateNanoUsd` (`1_000_000_000n`). It told readers to pass an
+  `OtelTelemetrySink` that the library does not ship; the option is `telemetry.sink`, which
+  takes your own `ITelemetrySink`, next to `telemetry.metrics`. The Bedrock preset is
+  `providerPresets.bedrock`, not `providerPresets.bedrockConverse`. The artifact-size table,
+  the stack list (it named a `ConfigurableModuleBuilder` the module does not use) and the
+  `AI_TOKENS_PRICE_NOT_FOUND` description (it counted resolution steps) were corrected too.
+- **The README examples compile.** Some examples called methods or read fields that do not
+  exist: `wallets.getOrCreate` (the method is `getBalance`, and it returns `nanoUsd` and
+  `credits`), `metering.summarize` (it is `UsageReportService.summarize`), `reports.export`
+  with a `format` property (the format is the second argument), and a markup policy typed on
+  `MeteringContext` (its `resolve` takes the narrower call context).
+
+## [1.1.2] - 2026-10-30
+
+### Fixed
+
+- **`PricingService.resolveRate` no longer serves one request's price to another.** The
+  resolution cache key joined provider, model, baseModel, operation, tier and time bucket
+  with `|`, which can also appear inside a model id. Two different requests could spell the
+  same key — `model: 'b|c'` with no `baseModel` against `model: 'b'` with `baseModel: 'c|'` —
+  and the second received the first's rate from the cache. The key is now a JSON array of
+  the fields, so no value can move the boundary between them. (#117)
+
+  **Apply:** no action required. Requests whose model names contain `|` now resolve their
+  own price instead of a colliding entry's.
+
+### Security
+
+- Advisories on transitive **dev** packages are cleared through `pnpm-workspace.yaml`
+  overrides: body-parser, multer, qs and zod (#115). deepmerge GHSA-gcqx-w48m-w2h4 has no
+  patched release and is reached only through `jest-config`, so it is ignored in
+  `osv-scanner.toml` until 2027-01-27. None of these reach a consumer install: the package
+  has no runtime dependencies.
+
+### Documentation
+
+- `SECURITY.md`: only the latest minor line (1.1.x) receives security fixes; 1.0.x is
+  unsupported and consumers should upgrade.
+
 ## [1.1.1] - 2026-10-23
 
 ### Fixed
@@ -62,7 +190,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and
 
 ## [1.0.4] - 2026-08-10
 
-Remediation of a local audit's settlement findings (merged in #65). No API changed.
+Remediation of a local audit's settlement findings (merged in #65). No API changes.
 
 ### Fixed
 
@@ -174,7 +302,7 @@ have regressed from. They are kept because the reasoning is worth having.
 ### Added
 
 - **Nine provider normalizers** — OpenAI Chat Completions, OpenAI Responses API, OpenAI-compatible (DeepSeek, xAI, Groq, Azure OpenAI), Anthropic Messages, Google Gemini / Vertex AI, AWS Bedrock Converse, Mistral, OpenRouter, Vercel AI SDK v5/v6. All are pure functions over plain objects; no provider SDK peer dependency.
-- **Versioned effective-dated pricing** — `PricingService` with a six-step model-resolution chain, in-memory TTL cache, `upsertPrice()`, and idempotent `MODEL_PRICES_SEED` snapshot seed. Rates are bigint nano-USD per million tokens; past records are never re-rated.
+- **Versioned effective-dated pricing** — `PricingService` with a model-resolution chain (exact, `baseModel`, alias map, normalized id, longest prefix), in-memory TTL cache, `upsertPrice()`, and idempotent `MODEL_PRICES_SEED` snapshot seed. Rates are bigint nano-USD per million tokens; past records are never re-rated.
 - **Immutable append-only ledger** — `LedgerService` with content-derived idempotency (`deriveIdempotencyKey`), exactly-once semantics (payload-hash replay detection), lifecycle transitions (pending → posted → reversed/released), filtered queries, and optional per-tenant tamper-evident hash chain (`verifyChain()`).
 - **First-class markup / margin** — `MarkupResolver` with a fixed multiplier or a per-call `IMarkupPolicy`. Every record stores both `rawCostNanoUsd` (provider cost) and `billedCostNanoUsd` (after markup). The resale lever is a first-class configuration option, not application code.
 - **Prepaid wallets** — `WalletService` with grant/debit/refund/adjust entries, configurable burn order (expiry/priority/FIFO), overdraft support, and debit-allocation tracking.
@@ -185,7 +313,7 @@ have regressed from. They are kept because the reasoning is worth having.
 - **NestJS enforcement** — `BudgetGuard` (CanActivate), `MeteringInterceptor` (NestInterceptor), and the `@Meter`, `@RequireBudget`, `@AiFeature` decorators for declarative controller-level metering.
 - **Usage reporting** — `UsageReportService` with SQL-aggregated `summarize()`, CSV/JSON `export()`, paginated history, per-model analytics, and currency conversion.
 - **Events** — Typed domain events (`ai_tokens.*`) delivered to `@nestjs/event-emitter` (optional peer) and/or an `IEventSink` port.
-- **OpenTelemetry** — Optional `ITelemetrySink` / `OtelTelemetrySink` via `@opentelemetry/api` (optional peer).
+- **OpenTelemetry** — The `ITelemetrySink` port, which you implement over `@opentelemetry/api` (optional peer); the library ships no sink and imports nothing from `@opentelemetry/api`.
 - **PostgreSQL adapter** — `PrismaAiTokensStore` (`./prisma` subpath) implementing all four storage ports via parameterized raw SQL. Seven-table schema with migrations.
 - **Five subpaths** — `.` (server), `./shared` (zero-dep), `./prices` (data-only), `./prisma` (adapter), `./redis` (counter).
 - **Zero runtime dependencies** — `"dependencies": {}`. All runtime functionality via peer dependencies.
@@ -267,7 +395,9 @@ have regressed from. They are kept because the reasoning is worth having.
 [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.1.2]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.1.1...v1.1.2
+[1.1.3]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.1.2...v1.1.3
 [1.1.1]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.1.0...v1.1.1
 [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.1.1...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.1.3...HEAD

package/README.md

@@ -134,10 +134,10 @@ the feature that needs them is enabled.
 
 | Artifact                                    | Brotli size | Budget  |
 | ------------------------------------------- | ----------- | ------- |
-| server (`@bymax-one/nest-ai-tokens`)        | 37 KB       | < 40 KB |
+| server (`@bymax-one/nest-ai-tokens`)        | 38 KB       | < 40 KB |
 | shared (`@bymax-one/nest-ai-tokens/shared`) | 5 KB        | < 10 KB |
 | prisma (`@bymax-one/nest-ai-tokens/prisma`) | 10 KB       | < 15 KB |
-| redis (`@bymax-one/nest-ai-tokens/redis`)   | 1.1 KB      | < 5 KB  |
+| redis (`@bymax-one/nest-ai-tokens/redis`)   | 1.3 KB      | < 5 KB  |
 | prices (data-only, exempt from budget)      | 1.3 KB      | exempt  |
 
 ---
@@ -180,6 +180,20 @@ npm i @prisma/adapter-pg
 > moves to a `prisma.config.ts` at your project root. Neither change reaches this
 > library's API — `PrismaAiTokensStore` receives whatever client you built.
 
+#### Create the tables
+
+`PrismaAiTokensStore` needs seven tables, and the package ships what creates them, inside the
+installed package:
+
+- `node_modules/@bymax-one/nest-ai-tokens/dist/prisma/migrations/0001_init.sql` — the SQL for all
+  seven tables. Apply it with `psql -f` or `prisma db execute --file` before the first boot.
+- `node_modules/@bymax-one/nest-ai-tokens/dist/prisma/schema.prisma.fragment` — the same models
+  for merging into your own Prisma schema if you manage migrations with `prisma migrate`.
+
+The SQL also creates two partial indexes (exactly one open price row per model, and a fast scan
+of pending holds) that a Prisma schema cannot express. If you migrate from the fragment, add them
+yourself.
+
 ### 2 — Register the module
 
 ```typescript
@@ -284,19 +298,26 @@ export class AiController {
 
 `BymaxAiTokensModule.forRoot(options)` / `.forRootAsync({ useFactory })` accept `BymaxAiTokensModuleOptions`:
 
-| Option                      | Type                                  | Default        | Purpose                                                                       |
-| --------------------------- | ------------------------------------- | -------------- | ----------------------------------------------------------------------------- |
-| `store`                     | `IAiTokensStore`                      | — (required)   | Persistence adapter (use `PrismaAiTokensStore`)                               |
-| `scopeResolver`             | `(ctx) => MeteringContext`            | —              | Resolves the caller's scope from the request (required for guard/interceptor) |
-| `ratingMode`                | `'rate-table' \| 'provider-reported'` | `'rate-table'` | Default cost rating mode                                                      |
-| `markup`                    | `number \| IMarkupPolicy`             | `1.0`          | The resale multiplier (e.g. `4.0` = 4× provider cost)                         |
-| `pricing.seedFromSnapshot`  | `boolean`                             | `false`        | Seed `MODEL_PRICES_SEED` into the registry on first boot                      |
-| `wallets.creditRateNanoUsd` | `bigint`                              | —              | Exchange rate: 1 credit = this many nano-USD                                  |
-| `wallets.burnOrder`         | `'expiry' \| 'priority' \| 'fifo'`    | `'expiry'`     | Order in which grants are consumed                                            |
-| `budgets.defaultPolicy`     | `'block' \| 'alert'`                  | `'alert'`      | Default enforcement when a budget is exhausted                                |
-| `budgets.alertThresholds`   | `number[]`                            | `[0.8, 1.0]`   | Soft-threshold events at these fractions                                      |
-| `holds.ttlSeconds`          | `number`                              | `300`          | Spend-hold TTL; the reaper voids expired holds                                |
-| `telemetry`                 | `ITelemetrySink`                      | no-op          | OpenTelemetry sink (pass `OtelTelemetrySink`)                                 |
+| Option                      | Type                                  | Default          | Purpose                                                                         |
+| --------------------------- | ------------------------------------- | ---------------- | ------------------------------------------------------------------------------- |
+| `store`                     | `IAiTokensStore`                      | — (required)     | Persistence adapter (use `PrismaAiTokensStore`)                                 |
+| `scopeResolver`             | `(ctx) => MeteringContext`            | —                | Resolves the caller's scope from the request (required for guard/interceptor)   |
+| `ratingMode`                | `'rate-table' \| 'provider-reported'` | `'rate-table'`   | Default cost rating mode                                                        |
+| `markup`                    | `number \| IMarkupPolicy`             | `1.0`            | The resale multiplier (e.g. `4.0` = 4× provider cost)                           |
+| `pricing.seedFromSnapshot`  | `boolean`                             | `true`           | Add seed rows only for combinations with no price row; never changes a price    |
+| `wallets.creditRateNanoUsd` | `bigint`                              | `1_000_000_000n` | Exchange rate: 1 credit = this many nano-USD                                    |
+| `wallets.burnOrder`         | `'expiry' \| 'priority' \| 'fifo'`    | `'expiry'`       | Order in which grants are consumed                                              |
+| `budgets.defaultPolicy`     | `'block' \| 'throttle' \| 'allow'`    | `'block'`        | Default enforcement when a budget is exhausted                                  |
+| `budgets.alertThresholds`   | `number[]`                            | `[0.8, 1.0]`     | Soft-threshold events at these fractions                                        |
+| `holds.ttlSeconds`          | `number`                              | `3600`           | Spend-hold TTL; the reaper voids expired holds                                  |
+| `telemetry.sink`            | `ITelemetrySink`                      | — (off)          | Your OpenTelemetry sink; the library ships none and telemetry is off without it |
+| `telemetry.metrics`         | `boolean`                             | `true`           | Emit token-usage and duration metrics when a sink is present                    |
+
+With `forRootAsync`, the options arrive after the providers are declared, so `WalletService`,
+`BudgetService` and `BudgetGuard` are always registered. When the options leave `wallets` or
+`budgets` out, the injected object throws `AI_TOKENS_INVALID_CONFIG` on any method call, with a
+reason naming the missing block. With `forRoot` they are not registered, so injecting one fails
+when the application boots.
 
 ---
 
@@ -309,7 +330,7 @@ export class AiController {
 | OpenAI-compatible | DeepSeek, xAI, Groq, Azure OpenAI | `normalizeOpenAiCompatibleUsage` / `providerPresets.openaiCompatible`              |
 | Anthropic         | Messages API                      | `normalizeAnthropicUsage` / `providerPresets.anthropic`                            |
 | Google            | Gemini / Vertex AI                | `normalizeGeminiUsage` / `providerPresets.gemini`                                  |
-| AWS               | Bedrock Converse                  | `normalizeBedrockConverseUsage` / `providerPresets.bedrockConverse`                |
+| AWS               | Bedrock Converse                  | `normalizeBedrockConverseUsage` / `providerPresets.bedrock`                        |
 | Mistral           | Chat API                          | `normalizeMistralUsage` / `providerPresets.mistral`                                |
 | OpenRouter        | Chat                              | `normalizeOpenRouterUsage` / `providerPresets.openrouter` (provider-reported cost) |
 | Vercel            | AI SDK v5/v6                      | `normalizeVercelAiSdkUsage` / `providerPresets.vercelAiSdk`                        |
@@ -325,7 +346,7 @@ The fundamental difference between "what the provider charged you" and "what you
 ```typescript
 // Configure at module level:
 BymaxAiTokensModule.forRootAsync({
-  useFactory: (prisma) => ({
+  useFactory: (prisma: PrismaService) => ({
     store: new PrismaAiTokensStore(prisma),
     markup: 4.0, // 4× resale margin
     wallets: { creditRateNanoUsd: 5_000_000_000n }, // sell credits at $5 each
@@ -342,7 +363,7 @@ For per-tenant or per-feature pricing, implement `IMarkupPolicy`:
 
 ```typescript
 class MyMarkupPolicy implements IMarkupPolicy {
-  resolve(ctx: MeteringContext): number | Promise<number> {
+  resolve(ctx: { feature?: string }): number | Promise<number> {
     return ctx.feature === 'premium.summarize' ? 5.0 : 3.0
   }
 }
@@ -370,8 +391,8 @@ await wallets.grant(
 
 // Credits are debited automatically when the ledger posts a billed cost.
 // Check balance:
-const wallet = await wallets.getOrCreate({ tenantId, ownerType: 'user', ownerId: userId })
-console.log(wallet.balanceNanoUsd) // current balance
+const balance = await wallets.getBalance({ tenantId, ownerType: 'user', ownerId: userId })
+console.log(balance.nanoUsd) // current balance
 ```
 
 ### Multi-Dimension Budgets
@@ -443,7 +464,7 @@ On abort, the collector falls back to a tokenizer estimate of the output tokens
 
 ```typescript
 // Usage summary — by feature, for the last 30 days:
-const summary = await metering.summarize({
+const summary = await reports.summarize({
   tenantId,
   scope: { type: 'user', id: userId },
   from: thirtyDaysAgo,
@@ -452,12 +473,7 @@ const summary = await metering.summarize({
 })
 
 // Export as CSV (streaming):
-const csv = await reports.export({
-  tenantId,
-  from,
-  to,
-  format: 'csv',
-})
+const csv = await reports.export({ tenantId, from, to }, 'csv')
 csv.pipe(res)
 
 // Access status / remaining budget:
@@ -495,11 +511,11 @@ All errors are `AiTokensException extends HttpException`. Use the exported `AI_T
 
 | Code                             | HTTP | When                                                                                  |
 | -------------------------------- | ---- | ------------------------------------------------------------------------------------- |
-| `AI_TOKENS_NOT_CONFIGURED`       | 503  | Service invoked before async init completed                                           |
+| `AI_TOKENS_NOT_CONFIGURED`       | 503  | Reserved; nothing raises it                                                           |
 | `AI_TOKENS_INVALID_CONFIG`       | 500  | Bad markup, negative limits, missing `scopeResolver`, missing fx                      |
 | `AI_TOKENS_UNKNOWN_PROVIDER`     | 400  | No preset/normalizer and usage is not already `NormalizedUsage`                       |
 | `AI_TOKENS_USAGE_MALFORMED`      | 422  | Normalizer could not read required token fields                                       |
-| `AI_TOKENS_PRICE_NOT_FOUND`      | 422  | No effective-dated rate after 6-step resolution chain (strict mode)                   |
+| `AI_TOKENS_PRICE_NOT_FOUND`      | 422  | No effective-dated rate after the model-resolution chain (strict mode)                |
 | `AI_TOKENS_FX_REQUIRED`          | 500  | `currency !== 'USD'` with no `fx` resolver                                            |
 | `AI_TOKENS_BUDGET_EXCEEDED`      | 402  | A hard spend budget blocks the call                                                   |
 | `AI_TOKENS_QUOTA_EXCEEDED`       | 429  | A hard token/count quota blocks the call                                              |
@@ -522,7 +538,7 @@ import { toJsonSafe } from '@bymax-one/nest-ai-tokens'
 
 // In your controller:
 return toJsonSafe(await metering.getStatus(tenantId, scope))
-// bigint fields (balanceNanoUsd, billedCostNanoUsd, etc.) become decimal strings.
+// bigint fields (wallet.balanceNanoUsd, budgets[].spent.nanoUsd, etc.) become decimal strings.
 
 // For display/formatting:
 import { formatNanoUsd } from '@bymax-one/nest-ai-tokens/shared'
@@ -548,6 +564,28 @@ The sections above document each of these with a runnable example. This is the i
 | `UsageReportService`   | `summarize` · `export`                                                                                                               |
 | `StreamUsageCollector` | Accumulates streamed chunks; prefers the provider's final usage over its own count                                                   |
 
+`LedgerService.verifyChain(tenantId, from?, to?)` resolves to a `ChainVerification`: `{ valid: true }`
+or `{ valid: false, brokenAtRecordId }`. It checks the chain that `ledger.hashChain: true` writes.
+
+### Decorators, helpers and catalogs
+
+| Export                                                                                         | Role                                                                                                                       |
+| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `@Meter` · `@RequireBudget` · `@AiFeature(name)`                                               | Handler metadata read by the interceptor and the guard; `@AiFeature` only tags the feature name                            |
+| `deriveIdempotencyKey` · `toJsonSafe` · `formatNanoUsd`                                        | Idempotency key from content, `bigint` to decimal strings for JSON, and display formatting                                 |
+| `floatUsdToNanoUsd` · `perMillion` · `computeCostNanoUsd`                                      | The money math: the only float-to-`bigint` entry, a cost at a nano-USD-per-million rate, and a usage priced against a rate |
+| `applyMarkup` · `resolveMultiplier4dp`                                                         | A markup applied in exact `bigint`, and a multiplier validated and rounded to 4 decimal places                             |
+| `isLegalLedgerTransition` · `isLegalTransitionPatchKey`                                        | The ledger lifecycle rules a custom store can reuse: which status changes and which columns each may touch                 |
+| `PROVIDER_IDS` · `SERVICE_TIERS` · `AI_OPERATIONS` · `TOKEN_CATEGORIES` · `WALLET_ENTRY_TYPES` | The catalogs the types are derived from                                                                                    |
+| `CounterValueOutOfRangeError` (`./redis`)                                                      | Thrown when a counter value leaves the safe-integer range; the budget service then falls back to the database consume      |
+
+### Injection tokens
+
+`BYMAX_AI_TOKENS_OPTIONS` (the resolved options) and the port tokens `BYMAX_AI_TOKENS_LEDGER_STORE`,
+`_PRICING_STORE`, `_WALLET_STORE`, `_BUDGET_STORE`, `_BUDGET_COUNTER`, `_TOKENIZER`, `_TELEMETRY`,
+`_EVENT_SINK`, `_CONTENT_STORE` and `_LOGGER`. The wallet and budget tokens exist only when their
+options block is set (with `forRoot`; `forRootAsync` always exports them).
+
 ### Request-scoped enforcement
 
 | Class                 | Role                                                                                                                                                                                                      |
@@ -672,7 +710,9 @@ There is one place text can be persisted, and it is opt-in: `IContentStore`, the
 sidecar. A host that enables it stores **masked** text under a short TTL, separate from the
 ledger, with a `purge()` that deletes by tenant, record or subject so an erasure request can
 be honoured without touching the accounting. It is off unless you provide a store — and if
-you do, text is being written, and where it is written is your implementation.
+you do, text is being written, and where it is written is your implementation. The library ships
+no `IContentStore` implementation and creates no table for one: you bring the store, its schema
+and its retention job.
 
 ### Budget checks are atomic
 
@@ -713,7 +753,7 @@ that reads a tenant id from request input lets a caller bill someone else.
 ## 🧱 Tech Stack
 
 - **Runtime:** Node.js 24+
-- **Framework:** NestJS 11 (guard + interceptor, `ConfigurableModuleBuilder`, `Symbol()` tokens)
+- **Framework:** NestJS 11 (guard + interceptor, `Symbol()` tokens)
 - **Persistence:** `@prisma/client ^6 || ^7` (peer) over PostgreSQL — both majors supported
 - **Budget acceleration:** `ioredis ^6` (peer), optional
 - **Events:** `@nestjs/event-emitter >=2` (peer), optional

package/dist/prisma/index.cjs

@@ -421,6 +421,9 @@ function mapPriceRow(row) {
     source: row.source
   };
 }
+function priceLockKey(provider, model, operation, serviceTier) {
+  return JSON.stringify([provider, model, operation, serviceTier]);
+}
 function firstOrThrow(rows) {
   const row = rows[0];
   if (row === void 0) throw new nestAiTokens.AiTokensException("AI_TOKENS_STORE_ERROR", void 0, {});
@@ -828,7 +831,7 @@ var PrismaAiTokensStore = class {
   async upsertPrice(input) {
     const serviceTier = input.serviceTier ?? "standard";
     const effectiveFrom = input.effectiveFrom ?? /* @__PURE__ */ new Date();
-    const key = `${input.provider}|${input.model}|${input.operation}|${serviceTier}`;
+    const key = priceLockKey(input.provider, input.model, input.operation, serviceTier);
     return this.prisma.$transaction(async (tx) => {
       await tx.$executeRaw`SELECT pg_advisory_xact_lock(hashtext(${key})::bigint)`;
       await tx.$executeRaw(client.Prisma.sql`
@@ -843,6 +846,33 @@ var PrismaAiTokensStore = class {
       return mapPriceRow(firstOrThrow(rows));
     });
   }
+  /**
+   * Insert a price row only when its (provider, model, operation, serviceTier) tuple has no
+   * row yet. The check and the insert run in one transaction under the same per-tuple
+   * `pg_advisory_xact_lock` as {@link upsertPrice}, so concurrent boots serialize on the
+   * tuple, the loser finds the winner's row and inserts nothing, and the lock is released
+   * when the transaction ends rather than when the connection does.
+   */
+  async seedPrice(input) {
+    const serviceTier = input.serviceTier ?? "standard";
+    const effectiveFrom = input.effectiveFrom ?? /* @__PURE__ */ new Date();
+    const key = priceLockKey(input.provider, input.model, input.operation, serviceTier);
+    return this.prisma.$transaction(async (tx) => {
+      await tx.$executeRaw`SELECT pg_advisory_xact_lock(hashtext(${key})::bigint)`;
+      const existing = await tx.$queryRaw(client.Prisma.sql`
+        SELECT "id" FROM "ai_model_prices"
+        WHERE "provider" = ${input.provider} AND "model" = ${input.model} AND "operation" = ${input.operation}
+          AND "serviceTier" = ${serviceTier}
+        LIMIT 1
+      `);
+      if (existing.length > 0) return false;
+      await tx.$queryRaw(client.Prisma.sql`
+        INSERT INTO "ai_model_prices" (${PRICE_COLUMNS_SQL}) VALUES (${client.Prisma.join(priceValues(input, serviceTier, effectiveFrom))})
+        RETURNING *
+      `);
+      return true;
+    });
+  }
   async getPriceHistory(provider, model, operation, serviceTier) {
     const tier = serviceTier === void 0 ? client.Prisma.empty : client.Prisma.sql`AND "serviceTier" = ${serviceTier}`;
     const rows = await this.prisma.$queryRaw(client.Prisma.sql`
@@ -858,7 +888,12 @@ var PrismaAiTokensStore = class {
     `);
     return rows.map((row) => ({ model: row.model, operation: row.operation, serviceTier: row.serviceTier }));
   }
-  /** Advisory seed lock (§6.4): the first caller wins; concurrent boots seed exactly once. */
+  /**
+   * Session-scoped advisory lock: the first caller on a connection wins, and the lock is held
+   * until that connection closes, not when a boot ends.
+   *
+   * @deprecated Use {@link seedPrice}, which seeds atomically under a transaction-scoped lock.
+   */
   async acquireSeedLock(key) {
     const rows = await this.prisma.$queryRaw(
       client.Prisma.sql`SELECT pg_try_advisory_lock(hashtext(${key})::bigint) AS "acquired"`

package/dist/prisma/index.d.cts

@@ -505,6 +505,15 @@ interface IPricingStore {
     resolveRate(provider: ProviderId, model: string, operation: AiOperation, serviceTier: ServiceTier, at: Date): Promise<PriceVersion | null>;
     /** Close the current open row (`effectiveTo = now`) and insert the new open row. */
     upsertPrice(input: NewPriceVersion): Promise<PriceVersion>;
+    /**
+     * Insert `input` only when no row, open or closed, exists for its
+     * (provider, model, operation, serviceTier) tuple; resolves `true` when it inserted.
+     * Atomic per tuple, so concurrent boots cannot both insert, and it never closes or
+     * alters an existing row. The snapshot seed uses it so a restart cannot revert a rate
+     * the host set with {@link IPricingStore.upsertPrice}. A store without it is seeded
+     * from {@link IPricingStore.getPriceHistory} and `upsertPrice`, which is not atomic.
+     */
+    seedPrice?(input: NewPriceVersion): Promise<boolean>;
     /** Full effective-dated history for a tuple (newest first). */
     getPriceHistory(provider: ProviderId, model: string, operation: AiOperation, serviceTier?: ServiceTier): Promise<PriceVersion[]>;
     /** All distinct (model, operation, serviceTier) for a provider — powers §6.6 prefix matching. */
@@ -615,9 +624,22 @@ declare class PrismaAiTokensStore implements IAiTokensStore {
     lastHash(tenantId: string): Promise<string | null>;
     resolveRate(provider: ProviderId, model: string, operation: AiOperation, serviceTier: ServiceTier, at: Date): Promise<PriceVersion | null>;
     upsertPrice(input: NewPriceVersion): Promise<PriceVersion>;
+    /**
+     * Insert a price row only when its (provider, model, operation, serviceTier) tuple has no
+     * row yet. The check and the insert run in one transaction under the same per-tuple
+     * `pg_advisory_xact_lock` as {@link upsertPrice}, so concurrent boots serialize on the
+     * tuple, the loser finds the winner's row and inserts nothing, and the lock is released
+     * when the transaction ends rather than when the connection does.
+     */
+    seedPrice(input: NewPriceVersion): Promise<boolean>;
     getPriceHistory(provider: ProviderId, model: string, operation: AiOperation, serviceTier?: ServiceTier): Promise<PriceVersion[]>;
     listModels(provider: ProviderId): Promise<PricedModel[]>;
-    /** Advisory seed lock (§6.4): the first caller wins; concurrent boots seed exactly once. */
+    /**
+     * Session-scoped advisory lock: the first caller on a connection wins, and the lock is held
+     * until that connection closes, not when a boot ends.
+     *
+     * @deprecated Use {@link seedPrice}, which seeds atomically under a transaction-scoped lock.
+     */
     acquireSeedLock(key: string): Promise<boolean>;
     /** Insert one usage row and return it; shared by the plain and chained paths. */
     private insert;

package/dist/prisma/index.d.ts

@@ -505,6 +505,15 @@ interface IPricingStore {
     resolveRate(provider: ProviderId, model: string, operation: AiOperation, serviceTier: ServiceTier, at: Date): Promise<PriceVersion | null>;
     /** Close the current open row (`effectiveTo = now`) and insert the new open row. */
     upsertPrice(input: NewPriceVersion): Promise<PriceVersion>;
+    /**
+     * Insert `input` only when no row, open or closed, exists for its
+     * (provider, model, operation, serviceTier) tuple; resolves `true` when it inserted.
+     * Atomic per tuple, so concurrent boots cannot both insert, and it never closes or
+     * alters an existing row. The snapshot seed uses it so a restart cannot revert a rate
+     * the host set with {@link IPricingStore.upsertPrice}. A store without it is seeded
+     * from {@link IPricingStore.getPriceHistory} and `upsertPrice`, which is not atomic.
+     */
+    seedPrice?(input: NewPriceVersion): Promise<boolean>;
     /** Full effective-dated history for a tuple (newest first). */
     getPriceHistory(provider: ProviderId, model: string, operation: AiOperation, serviceTier?: ServiceTier): Promise<PriceVersion[]>;
     /** All distinct (model, operation, serviceTier) for a provider — powers §6.6 prefix matching. */
@@ -615,9 +624,22 @@ declare class PrismaAiTokensStore implements IAiTokensStore {
     lastHash(tenantId: string): Promise<string | null>;
     resolveRate(provider: ProviderId, model: string, operation: AiOperation, serviceTier: ServiceTier, at: Date): Promise<PriceVersion | null>;
     upsertPrice(input: NewPriceVersion): Promise<PriceVersion>;
+    /**
+     * Insert a price row only when its (provider, model, operation, serviceTier) tuple has no
+     * row yet. The check and the insert run in one transaction under the same per-tuple
+     * `pg_advisory_xact_lock` as {@link upsertPrice}, so concurrent boots serialize on the
+     * tuple, the loser finds the winner's row and inserts nothing, and the lock is released
+     * when the transaction ends rather than when the connection does.
+     */
+    seedPrice(input: NewPriceVersion): Promise<boolean>;
     getPriceHistory(provider: ProviderId, model: string, operation: AiOperation, serviceTier?: ServiceTier): Promise<PriceVersion[]>;
     listModels(provider: ProviderId): Promise<PricedModel[]>;
-    /** Advisory seed lock (§6.4): the first caller wins; concurrent boots seed exactly once. */
+    /**
+     * Session-scoped advisory lock: the first caller on a connection wins, and the lock is held
+     * until that connection closes, not when a boot ends.
+     *
+     * @deprecated Use {@link seedPrice}, which seeds atomically under a transaction-scoped lock.
+     */
     acquireSeedLock(key: string): Promise<boolean>;
     /** Insert one usage row and return it; shared by the plain and chained paths. */
     private insert;

package/dist/prisma/index.mjs

@@ -419,6 +419,9 @@ function mapPriceRow(row) {
     source: row.source
   };
 }
+function priceLockKey(provider, model, operation, serviceTier) {
+  return JSON.stringify([provider, model, operation, serviceTier]);
+}
 function firstOrThrow(rows) {
   const row = rows[0];
   if (row === void 0) throw new AiTokensException("AI_TOKENS_STORE_ERROR", void 0, {});
@@ -826,7 +829,7 @@ var PrismaAiTokensStore = class {
   async upsertPrice(input) {
     const serviceTier = input.serviceTier ?? "standard";
     const effectiveFrom = input.effectiveFrom ?? /* @__PURE__ */ new Date();
-    const key = `${input.provider}|${input.model}|${input.operation}|${serviceTier}`;
+    const key = priceLockKey(input.provider, input.model, input.operation, serviceTier);
     return this.prisma.$transaction(async (tx) => {
       await tx.$executeRaw`SELECT pg_advisory_xact_lock(hashtext(${key})::bigint)`;
       await tx.$executeRaw(Prisma.sql`
@@ -841,6 +844,33 @@ var PrismaAiTokensStore = class {
       return mapPriceRow(firstOrThrow(rows));
     });
   }
+  /**
+   * Insert a price row only when its (provider, model, operation, serviceTier) tuple has no
+   * row yet. The check and the insert run in one transaction under the same per-tuple
+   * `pg_advisory_xact_lock` as {@link upsertPrice}, so concurrent boots serialize on the
+   * tuple, the loser finds the winner's row and inserts nothing, and the lock is released
+   * when the transaction ends rather than when the connection does.
+   */
+  async seedPrice(input) {
+    const serviceTier = input.serviceTier ?? "standard";
+    const effectiveFrom = input.effectiveFrom ?? /* @__PURE__ */ new Date();
+    const key = priceLockKey(input.provider, input.model, input.operation, serviceTier);
+    return this.prisma.$transaction(async (tx) => {
+      await tx.$executeRaw`SELECT pg_advisory_xact_lock(hashtext(${key})::bigint)`;
+      const existing = await tx.$queryRaw(Prisma.sql`
+        SELECT "id" FROM "ai_model_prices"
+        WHERE "provider" = ${input.provider} AND "model" = ${input.model} AND "operation" = ${input.operation}
+          AND "serviceTier" = ${serviceTier}
+        LIMIT 1
+      `);
+      if (existing.length > 0) return false;
+      await tx.$queryRaw(Prisma.sql`
+        INSERT INTO "ai_model_prices" (${PRICE_COLUMNS_SQL}) VALUES (${Prisma.join(priceValues(input, serviceTier, effectiveFrom))})
+        RETURNING *
+      `);
+      return true;
+    });
+  }
   async getPriceHistory(provider, model, operation, serviceTier) {
     const tier = serviceTier === void 0 ? Prisma.empty : Prisma.sql`AND "serviceTier" = ${serviceTier}`;
     const rows = await this.prisma.$queryRaw(Prisma.sql`
@@ -856,7 +886,12 @@ var PrismaAiTokensStore = class {
     `);
     return rows.map((row) => ({ model: row.model, operation: row.operation, serviceTier: row.serviceTier }));
   }
-  /** Advisory seed lock (§6.4): the first caller wins; concurrent boots seed exactly once. */
+  /**
+   * Session-scoped advisory lock: the first caller on a connection wins, and the lock is held
+   * until that connection closes, not when a boot ends.
+   *
+   * @deprecated Use {@link seedPrice}, which seeds atomically under a transaction-scoped lock.
+   */
   async acquireSeedLock(key) {
     const rows = await this.prisma.$queryRaw(
       Prisma.sql`SELECT pg_try_advisory_lock(hashtext(${key})::bigint) AS "acquired"`

package/dist/server/index.cjs

@@ -79,6 +79,7 @@ var WALLET_ENTRY_TYPES = ["grant", "debit", "refund", "adjustment", "expiry"];
 
 // src/shared/constants/error-codes.constants.ts
 var AI_TOKENS_ERROR_CODES = {
+  /** Reserved: nothing raises it. Nest resolves the async options before it builds any service. */
   AI_TOKENS_NOT_CONFIGURED: "AI_TOKENS_NOT_CONFIGURED",
   AI_TOKENS_INVALID_CONFIG: "AI_TOKENS_INVALID_CONFIG",
   AI_TOKENS_UNKNOWN_PROVIDER: "AI_TOKENS_UNKNOWN_PROVIDER",
@@ -1193,7 +1194,6 @@ function normalizeModelId(id) {
 
 // src/server/services/pricing.service.ts
 var SEED_EFFECTIVE_FROM = /* @__PURE__ */ new Date(0);
-var SEED_LOCK_KEY = "ai-tokens:model-prices";
 exports.PricingService = class PricingService {
   /**
    * @param options The resolved module options (pricing config lives here).
@@ -1224,7 +1224,7 @@ exports.PricingService = class PricingService {
     const serviceTier = input.serviceTier ?? "standard";
     const operation = input.operation === "responses" ? "chat" : input.operation;
     const bucket = Math.floor(input.at.getTime() / this.options.pricing.cacheTtlMs);
-    const cacheKey = `${input.provider}|${input.model}|${input.baseModel ?? ""}|${operation}|${serviceTier}|${String(bucket)}`;
+    const cacheKey = JSON.stringify([input.provider, input.model, input.baseModel, operation, serviceTier, bucket]);
     let resolved;
     const cached = this.cache.get(cacheKey);
     if (cached !== void 0 && this.now() < cached.expiresAt) {
@@ -1260,20 +1260,26 @@ exports.PricingService = class PricingService {
   getPriceHistory(provider, model, operation, serviceTier) {
     return this.store.getPriceHistory(provider, model, operation, serviceTier);
   }
-  /** Seed the registry from the pinned snapshot; idempotent and advisory-locked. */
+  /**
+   * Seed the registry from the pinned snapshot, adding only the tuples that have no row at
+   * all. A tuple that already has history, including one the host re-priced with
+   * `upsertPrice`, is left exactly as it is, so running this on every boot is a no-op once
+   * the registry is seeded.
+   */
   async seedFromSnapshot() {
-    const lockable = this.store;
-    if (typeof lockable.acquireSeedLock === "function") {
-      const acquired = await lockable.acquireSeedLock(SEED_LOCK_KEY);
-      if (!acquired) return;
-    }
     const { MODEL_PRICES_SEED } = await import('@bymax-one/nest-ai-tokens/prices');
     for (const row of MODEL_PRICES_SEED) {
-      await this.store.upsertPrice({ ...row, effectiveFrom: SEED_EFFECTIVE_FROM });
+      const input = { ...row, effectiveFrom: SEED_EFFECTIVE_FROM };
+      if (typeof this.store.seedPrice === "function") {
+        await this.store.seedPrice(input);
+        continue;
+      }
+      const history = await this.store.getPriceHistory(row.provider, row.model, row.operation, row.serviceTier);
+      if (history.length === 0) await this.store.upsertPrice(input);
     }
     this.cache.clear();
   }
-  /** The §6.6 six-step model-resolution chain (exact → baseModel → alias → normalized → prefix). */
+  /** The §6.6 model-resolution chain (exact → baseModel → alias → normalized → prefix). */
   async resolveUncached(provider, model, operation, serviceTier, at, baseModel) {
     const exact = await this.store.resolveRate(provider, model, operation, serviceTier, at);
     if (exact !== null) return exact;
@@ -2775,10 +2781,10 @@ exports.WalletService = class WalletService {
   options;
   events;
   /**
-   * The current balance, excluding not-yet-effective and expired grants (§9.2).
-   * Reads the materialized balance; expiry is applied lazily on debit, so a grant
-   * that lapses purely with the passage of time is reflected at the next debit or
-   * `reconcile` (the documented §9.3 lazy-materialization trade-off).
+   * The current balance (§9.2). Reads the materialized balance; expiry is applied
+   * lazily on debit, so a grant that lapses purely with the passage of time is still
+   * counted until the next debit or `reconcile` (the documented §9.3
+   * lazy-materialization trade-off).
    *
    * @param ref The wallet owner (a `'tenant' | 'team' | 'user'`, never `'key'`).
    * @returns The nano-USD balance and its presentation credits.
@@ -2965,7 +2971,7 @@ exports.WalletService = class WalletService {
    * `ai_tokens.audit`.
    *
    * @param ref The wallet owner.
-   * @returns The reconciled wallet.
+   * @returns The reconciled nano-USD balance and its presentation credits.
    */
   async reconcile(ref) {
     this.assertOwner(ref);
@@ -4078,6 +4084,26 @@ function writeHeader(response, name, value) {
   if (typeof response.setHeader === "function") response.setHeader(name, value);
   else if (typeof response.header === "function") response.header(name, value);
 }
+
+// src/server/disabled-service.ts
+var DISABLED = /* @__PURE__ */ Symbol("bymax.ai-tokens.disabled-service");
+function disabledService(service, block) {
+  const fail = () => {
+    throw new AiTokensException("AI_TOKENS_INVALID_CONFIG", void 0, {
+      reason: `${block} not configured: set options.${block} to enable ${service.name}`
+    });
+  };
+  const standIn = Object.create(service.prototype);
+  for (const name of Object.getOwnPropertyNames(service.prototype)) {
+    if (name !== "constructor") Object.defineProperty(standIn, name, { value: fail, enumerable: false });
+  }
+  Object.defineProperty(standIn, DISABLED, { value: true, enumerable: false });
+  return standIn;
+}
+function liveService(service) {
+  if (service === null || service === void 0) return null;
+  return service[DISABLED] === true ? null : service;
+}
 var REAP_BATCH_SIZE = 100;
 var MS_PER_SECOND = 1e3;
 var SCAN_FAILED_LOG_KEY = "ai_tokens.hold_reaper.scan_failed";
@@ -4208,7 +4234,7 @@ function buildServiceProviders() {
   return [
     {
       provide: exports.MeteringService,
-      useFactory: (ledger, pricing, markup, options, dispatcher, telemetrySink, wallets, budgets) => new exports.MeteringService(ledger, pricing, markup, options, createMeteringEventHooks(dispatcher), wallets, budgets, void 0, new TelemetryEmitter(telemetrySink), new ContentCapture(options.content)),
+      useFactory: (ledger, pricing, markup, options, dispatcher, telemetrySink, wallets, budgets) => new exports.MeteringService(ledger, pricing, markup, options, createMeteringEventHooks(dispatcher), liveService(wallets), liveService(budgets), void 0, new TelemetryEmitter(telemetrySink), new ContentCapture(options.content)),
       inject: [
         exports.LedgerService,
         exports.PricingService,
@@ -4238,21 +4264,21 @@ function buildServiceProviders() {
 function walletServiceProvider() {
   return {
     provide: exports.WalletService,
-    useFactory: (options, store, dispatcher) => options.wallets.enabled ? new exports.WalletService(store, options.wallets, createWalletEventHooks(dispatcher)) : null,
+    useFactory: (options, store, dispatcher) => options.wallets.enabled ? new exports.WalletService(store, options.wallets, createWalletEventHooks(dispatcher)) : disabledService(exports.WalletService, "wallets"),
     inject: [BYMAX_AI_TOKENS_OPTIONS, BYMAX_AI_TOKENS_WALLET_STORE, EventDispatcher]
   };
 }
 function budgetServiceProvider() {
   return {
     provide: exports.BudgetService,
-    useFactory: (options, store, ledger, dispatcher) => options.budgets.enabled ? new exports.BudgetService(store, ledger, options.budgets, void 0, createBudgetEventHooks(dispatcher)) : null,
+    useFactory: (options, store, ledger, dispatcher) => options.budgets.enabled ? new exports.BudgetService(store, ledger, options.budgets, void 0, createBudgetEventHooks(dispatcher)) : disabledService(exports.BudgetService, "budgets"),
     inject: [BYMAX_AI_TOKENS_OPTIONS, BYMAX_AI_TOKENS_BUDGET_STORE, exports.LedgerService, EventDispatcher]
   };
 }
 function budgetGuardProvider() {
   return {
     provide: exports.BudgetGuard,
-    useFactory: (options, budgets, metering, reflector) => options.budgets.enabled ? new exports.BudgetGuard(budgets, metering, reflector, options) : null,
+    useFactory: (options, budgets, metering, reflector) => options.budgets.enabled ? new exports.BudgetGuard(budgets, metering, reflector, options) : disabledService(exports.BudgetGuard, "budgets"),
     inject: [BYMAX_AI_TOKENS_OPTIONS, exports.BudgetService, exports.MeteringService, core.Reflector]
   };
 }
@@ -4299,7 +4325,7 @@ async function safeResolve(load) {
 }
 function buildAsyncOptionsProviders(descriptor) {
   if (descriptor.useFactory !== void 0) {
-    const factory = descriptor.useFactory;
+    const factory = descriptor.useFactory.bind(descriptor);
     return [
       {
         provide: BYMAX_AI_TOKENS_OPTIONS,

package/dist/server/index.d.cts

@@ -75,6 +75,7 @@ type WalletEntryType = (typeof WALLET_ENTRY_TYPES)[number];
  */
 /** Every error code the library can raise, mapped to itself for value access. */
 declare const AI_TOKENS_ERROR_CODES: {
+    /** Reserved: nothing raises it. Nest resolves the async options before it builds any service. */
     readonly AI_TOKENS_NOT_CONFIGURED: "AI_TOKENS_NOT_CONFIGURED";
     readonly AI_TOKENS_INVALID_CONFIG: "AI_TOKENS_INVALID_CONFIG";
     readonly AI_TOKENS_UNKNOWN_PROVIDER: "AI_TOKENS_UNKNOWN_PROVIDER";
@@ -1188,6 +1189,15 @@ interface IPricingStore {
     resolveRate(provider: ProviderId, model: string, operation: AiOperation, serviceTier: ServiceTier, at: Date): Promise<PriceVersion | null>;
     /** Close the current open row (`effectiveTo = now`) and insert the new open row. */
     upsertPrice(input: NewPriceVersion): Promise<PriceVersion>;
+    /**
+     * Insert `input` only when no row, open or closed, exists for its
+     * (provider, model, operation, serviceTier) tuple; resolves `true` when it inserted.
+     * Atomic per tuple, so concurrent boots cannot both insert, and it never closes or
+     * alters an existing row. The snapshot seed uses it so a restart cannot revert a rate
+     * the host set with {@link IPricingStore.upsertPrice}. A store without it is seeded
+     * from {@link IPricingStore.getPriceHistory} and `upsertPrice`, which is not atomic.
+     */
+    seedPrice?(input: NewPriceVersion): Promise<boolean>;
     /** Full effective-dated history for a tuple (newest first). */
     getPriceHistory(provider: ProviderId, model: string, operation: AiOperation, serviceTier?: ServiceTier): Promise<PriceVersion[]>;
     /** All distinct (model, operation, serviceTier) for a provider — powers §6.6 prefix matching. */
@@ -1575,11 +1585,24 @@ interface BymaxAiTokensModuleOptionsFactory {
 }
 /**
  * Asynchronous configuration for `BymaxAiTokensModule.forRootAsync()` — the
- * standard NestJS async dynamic-module options shape (the async factory is not
- * yet wired; the contract is defined here).
+ * standard NestJS async dynamic-module options shape. One of `useFactory`, `useClass`
+ * or `useExisting` is required, and `useFactory` takes precedence.
  */
 interface BymaxAiTokensModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
-    useFactory?: (...args: unknown[]) => BymaxAiTokensModuleOptions | Promise<BymaxAiTokensModuleOptions>;
+    /**
+     * Factory returning the module options. Its parameters are whatever `inject` resolves to, so
+     * declare them with the types you expect:
+     *
+     * ```ts
+     * useFactory: (config: ConfigService) => ({ store: new PrismaAiTokensStore(prisma) })
+     * ```
+     *
+     * Declared with method syntax on purpose: that makes the parameters bivariant, so a factory
+     * with typed parameters is accepted where `(...args: unknown[])` would reject it. Nest resolves
+     * the arguments from `inject` at run time, so no signature can make them statically safe, and
+     * method syntax keeps the factory callable, which a `never[]` rest parameter would not.
+     */
+    useFactory?(...args: unknown[]): BymaxAiTokensModuleOptions | Promise<BymaxAiTokensModuleOptions>;
     inject?: readonly (string | symbol | Type<unknown>)[];
     useExisting?: Type<BymaxAiTokensModuleOptionsFactory>;
     useClass?: Type<BymaxAiTokensModuleOptionsFactory>;
@@ -1757,7 +1780,7 @@ interface ResolvedAiTokensOptions {
 
 /**
  * @fileoverview `PricingService` — effective-dated rate resolution with the §6.6
- * six-step model-resolution chain, an in-memory TTL cache, price upserts, and the
+ * model-resolution chain, an in-memory TTL cache, price upserts, and the
  * idempotent snapshot seed (§6.3/§6.4). A call is priced at the rate in effect at
  * its timestamp; batch/flex/priority tiers must find their own row (no silent
  * fallback to standard rates).
@@ -1776,7 +1799,7 @@ interface ResolveRateInput {
     baseModel?: string;
 }
 /**
- * Effective-dated rate resolution with a six-step model-resolution chain, an
+ * Effective-dated rate resolution with a model-resolution chain, an
  * in-memory TTL cache, price upserts, and idempotent snapshot seed. Past
  * records are never re-rated (point-in-time pricing). See file overview.
  */
@@ -1812,9 +1835,14 @@ declare class PricingService implements OnModuleInit {
     upsertPrice(input: NewPriceVersion): Promise<PriceVersion>;
     /** Full effective-dated history for a tuple. */
     getPriceHistory(provider: ProviderId, model: string, operation: AiOperation, serviceTier?: ServiceTier): Promise<PriceVersion[]>;
-    /** Seed the registry from the pinned snapshot; idempotent and advisory-locked. */
+    /**
+     * Seed the registry from the pinned snapshot, adding only the tuples that have no row at
+     * all. A tuple that already has history, including one the host re-priced with
+     * `upsertPrice`, is left exactly as it is, so running this on every boot is a no-op once
+     * the registry is seeded.
+     */
     seedFromSnapshot(): Promise<void>;
-    /** The §6.6 six-step model-resolution chain (exact → baseModel → alias → normalized → prefix). */
+    /** The §6.6 model-resolution chain (exact → baseModel → alias → normalized → prefix). */
     private resolveUncached;
     /** §6.6 step 5: longest-`startsWith` match among priced models for provider+operation+tier. */
     private resolveByLongestPrefix;
@@ -2224,10 +2252,10 @@ declare class WalletService {
      */
     constructor(store: IWalletStore, options: WalletServiceOptions, events?: WalletEventHooks);
     /**
-     * The current balance, excluding not-yet-effective and expired grants (§9.2).
-     * Reads the materialized balance; expiry is applied lazily on debit, so a grant
-     * that lapses purely with the passage of time is reflected at the next debit or
-     * `reconcile` (the documented §9.3 lazy-materialization trade-off).
+     * The current balance (§9.2). Reads the materialized balance; expiry is applied
+     * lazily on debit, so a grant that lapses purely with the passage of time is still
+     * counted until the next debit or `reconcile` (the documented §9.3
+     * lazy-materialization trade-off).
      *
      * @param ref The wallet owner (a `'tenant' | 'team' | 'user'`, never `'key'`).
      * @returns The nano-USD balance and its presentation credits.
@@ -2306,7 +2334,7 @@ declare class WalletService {
      * `ai_tokens.audit`.
      *
      * @param ref The wallet owner.
-     * @returns The reconciled wallet.
+     * @returns The reconciled nano-USD balance and its presentation credits.
      */
     reconcile(ref: WalletRef): Promise<WalletBalance>;
     /** Append a non-debit entry, mapping a store idempotency/missing-wallet signal to the catalog. */
@@ -3119,7 +3147,7 @@ declare class MeteringInterceptor implements NestInterceptor {
  * @fileoverview The controller-level metering/enforcement decorators (spec §11.4).
  * `@Meter` marks a handler for the `MeteringInterceptor` and is metadata-only
  * here; `@RequireBudget` marks it for the `BudgetGuard`; `@AiFeature`
- * is a lightweight feature tag. Each stores its config under an exported symbol key
+ * is a lightweight feature tag. Each stores its config under an exported string key
  * that the guard/interceptor read via the NestJS `Reflector`. Feature precedence is
  * `@RequireBudget.feature` > `@Meter.feature` > `@AiFeature` (§11.4). These are pure
  * metadata; they never touch a wallet, budget, or the request.
@@ -3206,4 +3234,4 @@ declare class AiTokensException extends HttpException {
     constructor(code: AiTokensErrorCode, statusCode?: HttpStatus, details?: Record<string, unknown>);
 }
 
-export { AI_FEATURE_METADATA, AI_OPERATIONS, AI_TOKENS_ERROR_CODES, AMOUNT_FIELDS, type AccessStatus, type AdjustInput, AiFeature, type AiOperation, type AiTokensErrorCode, type AiTokensErrorResponse, type AiTokensEvent, type AiTokensEventType, AiTokensException, type AuditEventData, BYMAX_AI_TOKENS_BUDGET_COUNTER, BYMAX_AI_TOKENS_BUDGET_STORE, BYMAX_AI_TOKENS_CONTENT_STORE, BYMAX_AI_TOKENS_EVENT_SINK, BYMAX_AI_TOKENS_LEDGER_STORE, BYMAX_AI_TOKENS_LOGGER, BYMAX_AI_TOKENS_OPTIONS, BYMAX_AI_TOKENS_PRICING_STORE, BYMAX_AI_TOKENS_TELEMETRY, BYMAX_AI_TOKENS_TOKENIZER, BYMAX_AI_TOKENS_WALLET_STORE, type Budget, type BudgetDelta, type BudgetDimensionSnapshot, type BudgetExceededEventData, BudgetGuard, type BudgetLimits, type BudgetPolicy, type BudgetProjectedExceededEventData, BudgetService, type BudgetServiceOptions, type BudgetStatus, type BudgetThresholdCrossedEventData, type BudgetWindowKind, type BudgetWindowSpend, BymaxAiTokensModule, type BymaxAiTokensModuleAsyncOptions, type BymaxAiTokensModuleOptions, type BymaxAiTokensModuleOptionsFactory, type CostBreakdown, type CostEstimate, type DebitInput, type EstimateCostInput, type FormatNanoUsdOptions, type GrantInput, type Hold, type HoldEstimate, type HoldReleasedEventData, type IAiTokensStore, type IBudgetCounterStore, type IBudgetStore, type IContentStore, type IEventSink, type ILedgerStore, type IMarkupPolicy, type IPricingStore, type ITelemetrySink, type ITokenizer, type IWalletStore, type JsonSafe, type KnownProviderId, type LedgerAppendInput, type LedgerCostSummary, type LedgerFilter, LedgerService, METER_METADATA, Meter, type MeterConfig, type MeterResult, type MeteringContext, MeteringInterceptor, type MeteringScope, MeteringService, type NewPriceVersion, type NewUsageRecord, type NewWalletEntry, type NormalizedUsage, type OpenGrant, PROVIDER_IDS, type PriceMissingEventData, type PriceVersion, type PricedModel, PricingService, type ProviderId, type ProviderPreset, RELEASE_FIELDS, REQUIRE_BUDGET_METADATA, REVERSAL_LINKAGE_FIELD, type RatingMode, type RecordInput, type RefundInput, type ReportExportFormat, type ReportFilter, type ReportGroupBy, type RequestAiTokens, RequireBudget, type RequireBudgetConfig, type ResolveRateInput, SERVICE_TIERS, SETTLEMENT_FIELDS, SETTLEMENT_PATCH_KEYS, type ScopeType, type ServiceTier, StreamUsageCollector, type StreamUsageCollectorOptions, type SummarizeInput, TOKEN_CATEGORIES, type TokenCategory, type UpsertBudgetInput, type UsageNormalizer, type UsageRecord, type UsageRecordedEventData, type UsageReportOptions, UsageReportService, type UsageReversedEventData, type UsageStatus, type UsageSummary, WALLET_ENTRY_TYPES, type Wallet, type WalletBalance, type WalletDepletedEventData, type WalletEntry, type WalletEntryFilter, type WalletEntryPage, type WalletEntryType, type WalletGrantedEventData, type WalletLowBalanceEventData, type WalletRef, WalletService, type WalletServiceOptions, applyMarkup, computeCostNanoUsd, deriveIdempotencyKey, floatUsdToNanoUsd, formatNanoUsd, isLegalLedgerTransition, isLegalTransitionPatchKey, normalizeAnthropicUsage, normalizeBedrockConverseUsage, normalizeGeminiUsage, normalizeMistralUsage, normalizeOpenAiChatUsage, normalizeOpenAiCompatibleUsage, normalizeOpenAiResponsesUsage, normalizeOpenRouterUsage, normalizeVercelAiSdkUsage, perMillion, providerPresets, resolveMultiplier4dp, toJsonSafe };
+export { AI_FEATURE_METADATA, AI_OPERATIONS, AI_TOKENS_ERROR_CODES, AMOUNT_FIELDS, type AccessStatus, type AdjustInput, AiFeature, type AiOperation, type AiTokensErrorCode, type AiTokensErrorResponse, type AiTokensEvent, type AiTokensEventType, AiTokensException, type AuditEventData, BYMAX_AI_TOKENS_BUDGET_COUNTER, BYMAX_AI_TOKENS_BUDGET_STORE, BYMAX_AI_TOKENS_CONTENT_STORE, BYMAX_AI_TOKENS_EVENT_SINK, BYMAX_AI_TOKENS_LEDGER_STORE, BYMAX_AI_TOKENS_LOGGER, BYMAX_AI_TOKENS_OPTIONS, BYMAX_AI_TOKENS_PRICING_STORE, BYMAX_AI_TOKENS_TELEMETRY, BYMAX_AI_TOKENS_TOKENIZER, BYMAX_AI_TOKENS_WALLET_STORE, type Budget, type BudgetDelta, type BudgetDimensionSnapshot, type BudgetExceededEventData, BudgetGuard, type BudgetLimits, type BudgetPolicy, type BudgetProjectedExceededEventData, BudgetService, type BudgetServiceOptions, type BudgetStatus, type BudgetThresholdCrossedEventData, type BudgetWindowKind, type BudgetWindowSpend, BymaxAiTokensModule, type BymaxAiTokensModuleAsyncOptions, type BymaxAiTokensModuleOptions, type BymaxAiTokensModuleOptionsFactory, type ChainVerification, type CostBreakdown, type CostEstimate, type DebitInput, type EstimateCostInput, type FormatNanoUsdOptions, type GrantInput, type Hold, type HoldEstimate, type HoldReleasedEventData, type IAiTokensStore, type IBudgetCounterStore, type IBudgetStore, type IContentStore, type IEventSink, type ILedgerStore, type IMarkupPolicy, type IPricingStore, type ITelemetrySink, type ITokenizer, type IWalletStore, type JsonSafe, type KnownProviderId, type LedgerAppendInput, type LedgerCostSummary, type LedgerFilter, LedgerService, METER_METADATA, Meter, type MeterConfig, type MeterResult, type MeteringContext, MeteringInterceptor, type MeteringScope, MeteringService, type NewPriceVersion, type NewUsageRecord, type NewWalletEntry, type NormalizedUsage, type OpenGrant, PROVIDER_IDS, type PriceMissingEventData, type PriceVersion, type PricedModel, PricingService, type ProviderId, type ProviderPreset, RELEASE_FIELDS, REQUIRE_BUDGET_METADATA, REVERSAL_LINKAGE_FIELD, type RatingMode, type RecordInput, type RefundInput, type ReportExportFormat, type ReportFilter, type ReportGroupBy, type RequestAiTokens, RequireBudget, type RequireBudgetConfig, type ResolveRateInput, SERVICE_TIERS, SETTLEMENT_FIELDS, SETTLEMENT_PATCH_KEYS, type ScopeType, type ServiceTier, StreamUsageCollector, type StreamUsageCollectorOptions, type SummarizeInput, TOKEN_CATEGORIES, type TokenCategory, type UpsertBudgetInput, type UsageNormalizer, type UsageRecord, type UsageRecordedEventData, type UsageReportOptions, UsageReportService, type UsageReversedEventData, type UsageStatus, type UsageSummary, WALLET_ENTRY_TYPES, type Wallet, type WalletBalance, type WalletDepletedEventData, type WalletEntry, type WalletEntryFilter, type WalletEntryPage, type WalletEntryType, type WalletGrantedEventData, type WalletLowBalanceEventData, type WalletRef, WalletService, type WalletServiceOptions, applyMarkup, computeCostNanoUsd, deriveIdempotencyKey, floatUsdToNanoUsd, formatNanoUsd, isLegalLedgerTransition, isLegalTransitionPatchKey, normalizeAnthropicUsage, normalizeBedrockConverseUsage, normalizeGeminiUsage, normalizeMistralUsage, normalizeOpenAiChatUsage, normalizeOpenAiCompatibleUsage, normalizeOpenAiResponsesUsage, normalizeOpenRouterUsage, normalizeVercelAiSdkUsage, perMillion, providerPresets, resolveMultiplier4dp, toJsonSafe };

package/dist/server/index.d.ts

@@ -75,6 +75,7 @@ type WalletEntryType = (typeof WALLET_ENTRY_TYPES)[number];
  */
 /** Every error code the library can raise, mapped to itself for value access. */
 declare const AI_TOKENS_ERROR_CODES: {
+    /** Reserved: nothing raises it. Nest resolves the async options before it builds any service. */
     readonly AI_TOKENS_NOT_CONFIGURED: "AI_TOKENS_NOT_CONFIGURED";
     readonly AI_TOKENS_INVALID_CONFIG: "AI_TOKENS_INVALID_CONFIG";
     readonly AI_TOKENS_UNKNOWN_PROVIDER: "AI_TOKENS_UNKNOWN_PROVIDER";
@@ -1188,6 +1189,15 @@ interface IPricingStore {
     resolveRate(provider: ProviderId, model: string, operation: AiOperation, serviceTier: ServiceTier, at: Date): Promise<PriceVersion | null>;
     /** Close the current open row (`effectiveTo = now`) and insert the new open row. */
     upsertPrice(input: NewPriceVersion): Promise<PriceVersion>;
+    /**
+     * Insert `input` only when no row, open or closed, exists for its
+     * (provider, model, operation, serviceTier) tuple; resolves `true` when it inserted.
+     * Atomic per tuple, so concurrent boots cannot both insert, and it never closes or
+     * alters an existing row. The snapshot seed uses it so a restart cannot revert a rate
+     * the host set with {@link IPricingStore.upsertPrice}. A store without it is seeded
+     * from {@link IPricingStore.getPriceHistory} and `upsertPrice`, which is not atomic.
+     */
+    seedPrice?(input: NewPriceVersion): Promise<boolean>;
     /** Full effective-dated history for a tuple (newest first). */
     getPriceHistory(provider: ProviderId, model: string, operation: AiOperation, serviceTier?: ServiceTier): Promise<PriceVersion[]>;
     /** All distinct (model, operation, serviceTier) for a provider — powers §6.6 prefix matching. */
@@ -1575,11 +1585,24 @@ interface BymaxAiTokensModuleOptionsFactory {
 }
 /**
  * Asynchronous configuration for `BymaxAiTokensModule.forRootAsync()` — the
- * standard NestJS async dynamic-module options shape (the async factory is not
- * yet wired; the contract is defined here).
+ * standard NestJS async dynamic-module options shape. One of `useFactory`, `useClass`
+ * or `useExisting` is required, and `useFactory` takes precedence.
  */
 interface BymaxAiTokensModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
-    useFactory?: (...args: unknown[]) => BymaxAiTokensModuleOptions | Promise<BymaxAiTokensModuleOptions>;
+    /**
+     * Factory returning the module options. Its parameters are whatever `inject` resolves to, so
+     * declare them with the types you expect:
+     *
+     * ```ts
+     * useFactory: (config: ConfigService) => ({ store: new PrismaAiTokensStore(prisma) })
+     * ```
+     *
+     * Declared with method syntax on purpose: that makes the parameters bivariant, so a factory
+     * with typed parameters is accepted where `(...args: unknown[])` would reject it. Nest resolves
+     * the arguments from `inject` at run time, so no signature can make them statically safe, and
+     * method syntax keeps the factory callable, which a `never[]` rest parameter would not.
+     */
+    useFactory?(...args: unknown[]): BymaxAiTokensModuleOptions | Promise<BymaxAiTokensModuleOptions>;
     inject?: readonly (string | symbol | Type<unknown>)[];
     useExisting?: Type<BymaxAiTokensModuleOptionsFactory>;
     useClass?: Type<BymaxAiTokensModuleOptionsFactory>;
@@ -1757,7 +1780,7 @@ interface ResolvedAiTokensOptions {
 
 /**
  * @fileoverview `PricingService` — effective-dated rate resolution with the §6.6
- * six-step model-resolution chain, an in-memory TTL cache, price upserts, and the
+ * model-resolution chain, an in-memory TTL cache, price upserts, and the
  * idempotent snapshot seed (§6.3/§6.4). A call is priced at the rate in effect at
  * its timestamp; batch/flex/priority tiers must find their own row (no silent
  * fallback to standard rates).
@@ -1776,7 +1799,7 @@ interface ResolveRateInput {
     baseModel?: string;
 }
 /**
- * Effective-dated rate resolution with a six-step model-resolution chain, an
+ * Effective-dated rate resolution with a model-resolution chain, an
  * in-memory TTL cache, price upserts, and idempotent snapshot seed. Past
  * records are never re-rated (point-in-time pricing). See file overview.
  */
@@ -1812,9 +1835,14 @@ declare class PricingService implements OnModuleInit {
     upsertPrice(input: NewPriceVersion): Promise<PriceVersion>;
     /** Full effective-dated history for a tuple. */
     getPriceHistory(provider: ProviderId, model: string, operation: AiOperation, serviceTier?: ServiceTier): Promise<PriceVersion[]>;
-    /** Seed the registry from the pinned snapshot; idempotent and advisory-locked. */
+    /**
+     * Seed the registry from the pinned snapshot, adding only the tuples that have no row at
+     * all. A tuple that already has history, including one the host re-priced with
+     * `upsertPrice`, is left exactly as it is, so running this on every boot is a no-op once
+     * the registry is seeded.
+     */
     seedFromSnapshot(): Promise<void>;
-    /** The §6.6 six-step model-resolution chain (exact → baseModel → alias → normalized → prefix). */
+    /** The §6.6 model-resolution chain (exact → baseModel → alias → normalized → prefix). */
     private resolveUncached;
     /** §6.6 step 5: longest-`startsWith` match among priced models for provider+operation+tier. */
     private resolveByLongestPrefix;
@@ -2224,10 +2252,10 @@ declare class WalletService {
      */
     constructor(store: IWalletStore, options: WalletServiceOptions, events?: WalletEventHooks);
     /**
-     * The current balance, excluding not-yet-effective and expired grants (§9.2).
-     * Reads the materialized balance; expiry is applied lazily on debit, so a grant
-     * that lapses purely with the passage of time is reflected at the next debit or
-     * `reconcile` (the documented §9.3 lazy-materialization trade-off).
+     * The current balance (§9.2). Reads the materialized balance; expiry is applied
+     * lazily on debit, so a grant that lapses purely with the passage of time is still
+     * counted until the next debit or `reconcile` (the documented §9.3
+     * lazy-materialization trade-off).
      *
      * @param ref The wallet owner (a `'tenant' | 'team' | 'user'`, never `'key'`).
      * @returns The nano-USD balance and its presentation credits.
@@ -2306,7 +2334,7 @@ declare class WalletService {
      * `ai_tokens.audit`.
      *
      * @param ref The wallet owner.
-     * @returns The reconciled wallet.
+     * @returns The reconciled nano-USD balance and its presentation credits.
      */
     reconcile(ref: WalletRef): Promise<WalletBalance>;
     /** Append a non-debit entry, mapping a store idempotency/missing-wallet signal to the catalog. */
@@ -3119,7 +3147,7 @@ declare class MeteringInterceptor implements NestInterceptor {
  * @fileoverview The controller-level metering/enforcement decorators (spec §11.4).
  * `@Meter` marks a handler for the `MeteringInterceptor` and is metadata-only
  * here; `@RequireBudget` marks it for the `BudgetGuard`; `@AiFeature`
- * is a lightweight feature tag. Each stores its config under an exported symbol key
+ * is a lightweight feature tag. Each stores its config under an exported string key
  * that the guard/interceptor read via the NestJS `Reflector`. Feature precedence is
  * `@RequireBudget.feature` > `@Meter.feature` > `@AiFeature` (§11.4). These are pure
  * metadata; they never touch a wallet, budget, or the request.
@@ -3206,4 +3234,4 @@ declare class AiTokensException extends HttpException {
     constructor(code: AiTokensErrorCode, statusCode?: HttpStatus, details?: Record<string, unknown>);
 }
 
-export { AI_FEATURE_METADATA, AI_OPERATIONS, AI_TOKENS_ERROR_CODES, AMOUNT_FIELDS, type AccessStatus, type AdjustInput, AiFeature, type AiOperation, type AiTokensErrorCode, type AiTokensErrorResponse, type AiTokensEvent, type AiTokensEventType, AiTokensException, type AuditEventData, BYMAX_AI_TOKENS_BUDGET_COUNTER, BYMAX_AI_TOKENS_BUDGET_STORE, BYMAX_AI_TOKENS_CONTENT_STORE, BYMAX_AI_TOKENS_EVENT_SINK, BYMAX_AI_TOKENS_LEDGER_STORE, BYMAX_AI_TOKENS_LOGGER, BYMAX_AI_TOKENS_OPTIONS, BYMAX_AI_TOKENS_PRICING_STORE, BYMAX_AI_TOKENS_TELEMETRY, BYMAX_AI_TOKENS_TOKENIZER, BYMAX_AI_TOKENS_WALLET_STORE, type Budget, type BudgetDelta, type BudgetDimensionSnapshot, type BudgetExceededEventData, BudgetGuard, type BudgetLimits, type BudgetPolicy, type BudgetProjectedExceededEventData, BudgetService, type BudgetServiceOptions, type BudgetStatus, type BudgetThresholdCrossedEventData, type BudgetWindowKind, type BudgetWindowSpend, BymaxAiTokensModule, type BymaxAiTokensModuleAsyncOptions, type BymaxAiTokensModuleOptions, type BymaxAiTokensModuleOptionsFactory, type CostBreakdown, type CostEstimate, type DebitInput, type EstimateCostInput, type FormatNanoUsdOptions, type GrantInput, type Hold, type HoldEstimate, type HoldReleasedEventData, type IAiTokensStore, type IBudgetCounterStore, type IBudgetStore, type IContentStore, type IEventSink, type ILedgerStore, type IMarkupPolicy, type IPricingStore, type ITelemetrySink, type ITokenizer, type IWalletStore, type JsonSafe, type KnownProviderId, type LedgerAppendInput, type LedgerCostSummary, type LedgerFilter, LedgerService, METER_METADATA, Meter, type MeterConfig, type MeterResult, type MeteringContext, MeteringInterceptor, type MeteringScope, MeteringService, type NewPriceVersion, type NewUsageRecord, type NewWalletEntry, type NormalizedUsage, type OpenGrant, PROVIDER_IDS, type PriceMissingEventData, type PriceVersion, type PricedModel, PricingService, type ProviderId, type ProviderPreset, RELEASE_FIELDS, REQUIRE_BUDGET_METADATA, REVERSAL_LINKAGE_FIELD, type RatingMode, type RecordInput, type RefundInput, type ReportExportFormat, type ReportFilter, type ReportGroupBy, type RequestAiTokens, RequireBudget, type RequireBudgetConfig, type ResolveRateInput, SERVICE_TIERS, SETTLEMENT_FIELDS, SETTLEMENT_PATCH_KEYS, type ScopeType, type ServiceTier, StreamUsageCollector, type StreamUsageCollectorOptions, type SummarizeInput, TOKEN_CATEGORIES, type TokenCategory, type UpsertBudgetInput, type UsageNormalizer, type UsageRecord, type UsageRecordedEventData, type UsageReportOptions, UsageReportService, type UsageReversedEventData, type UsageStatus, type UsageSummary, WALLET_ENTRY_TYPES, type Wallet, type WalletBalance, type WalletDepletedEventData, type WalletEntry, type WalletEntryFilter, type WalletEntryPage, type WalletEntryType, type WalletGrantedEventData, type WalletLowBalanceEventData, type WalletRef, WalletService, type WalletServiceOptions, applyMarkup, computeCostNanoUsd, deriveIdempotencyKey, floatUsdToNanoUsd, formatNanoUsd, isLegalLedgerTransition, isLegalTransitionPatchKey, normalizeAnthropicUsage, normalizeBedrockConverseUsage, normalizeGeminiUsage, normalizeMistralUsage, normalizeOpenAiChatUsage, normalizeOpenAiCompatibleUsage, normalizeOpenAiResponsesUsage, normalizeOpenRouterUsage, normalizeVercelAiSdkUsage, perMillion, providerPresets, resolveMultiplier4dp, toJsonSafe };
+export { AI_FEATURE_METADATA, AI_OPERATIONS, AI_TOKENS_ERROR_CODES, AMOUNT_FIELDS, type AccessStatus, type AdjustInput, AiFeature, type AiOperation, type AiTokensErrorCode, type AiTokensErrorResponse, type AiTokensEvent, type AiTokensEventType, AiTokensException, type AuditEventData, BYMAX_AI_TOKENS_BUDGET_COUNTER, BYMAX_AI_TOKENS_BUDGET_STORE, BYMAX_AI_TOKENS_CONTENT_STORE, BYMAX_AI_TOKENS_EVENT_SINK, BYMAX_AI_TOKENS_LEDGER_STORE, BYMAX_AI_TOKENS_LOGGER, BYMAX_AI_TOKENS_OPTIONS, BYMAX_AI_TOKENS_PRICING_STORE, BYMAX_AI_TOKENS_TELEMETRY, BYMAX_AI_TOKENS_TOKENIZER, BYMAX_AI_TOKENS_WALLET_STORE, type Budget, type BudgetDelta, type BudgetDimensionSnapshot, type BudgetExceededEventData, BudgetGuard, type BudgetLimits, type BudgetPolicy, type BudgetProjectedExceededEventData, BudgetService, type BudgetServiceOptions, type BudgetStatus, type BudgetThresholdCrossedEventData, type BudgetWindowKind, type BudgetWindowSpend, BymaxAiTokensModule, type BymaxAiTokensModuleAsyncOptions, type BymaxAiTokensModuleOptions, type BymaxAiTokensModuleOptionsFactory, type ChainVerification, type CostBreakdown, type CostEstimate, type DebitInput, type EstimateCostInput, type FormatNanoUsdOptions, type GrantInput, type Hold, type HoldEstimate, type HoldReleasedEventData, type IAiTokensStore, type IBudgetCounterStore, type IBudgetStore, type IContentStore, type IEventSink, type ILedgerStore, type IMarkupPolicy, type IPricingStore, type ITelemetrySink, type ITokenizer, type IWalletStore, type JsonSafe, type KnownProviderId, type LedgerAppendInput, type LedgerCostSummary, type LedgerFilter, LedgerService, METER_METADATA, Meter, type MeterConfig, type MeterResult, type MeteringContext, MeteringInterceptor, type MeteringScope, MeteringService, type NewPriceVersion, type NewUsageRecord, type NewWalletEntry, type NormalizedUsage, type OpenGrant, PROVIDER_IDS, type PriceMissingEventData, type PriceVersion, type PricedModel, PricingService, type ProviderId, type ProviderPreset, RELEASE_FIELDS, REQUIRE_BUDGET_METADATA, REVERSAL_LINKAGE_FIELD, type RatingMode, type RecordInput, type RefundInput, type ReportExportFormat, type ReportFilter, type ReportGroupBy, type RequestAiTokens, RequireBudget, type RequireBudgetConfig, type ResolveRateInput, SERVICE_TIERS, SETTLEMENT_FIELDS, SETTLEMENT_PATCH_KEYS, type ScopeType, type ServiceTier, StreamUsageCollector, type StreamUsageCollectorOptions, type SummarizeInput, TOKEN_CATEGORIES, type TokenCategory, type UpsertBudgetInput, type UsageNormalizer, type UsageRecord, type UsageRecordedEventData, type UsageReportOptions, UsageReportService, type UsageReversedEventData, type UsageStatus, type UsageSummary, WALLET_ENTRY_TYPES, type Wallet, type WalletBalance, type WalletDepletedEventData, type WalletEntry, type WalletEntryFilter, type WalletEntryPage, type WalletEntryType, type WalletGrantedEventData, type WalletLowBalanceEventData, type WalletRef, WalletService, type WalletServiceOptions, applyMarkup, computeCostNanoUsd, deriveIdempotencyKey, floatUsdToNanoUsd, formatNanoUsd, isLegalLedgerTransition, isLegalTransitionPatchKey, normalizeAnthropicUsage, normalizeBedrockConverseUsage, normalizeGeminiUsage, normalizeMistralUsage, normalizeOpenAiChatUsage, normalizeOpenAiCompatibleUsage, normalizeOpenAiResponsesUsage, normalizeOpenRouterUsage, normalizeVercelAiSdkUsage, perMillion, providerPresets, resolveMultiplier4dp, toJsonSafe };

package/dist/server/index.mjs

@@ -77,6 +77,7 @@ var WALLET_ENTRY_TYPES = ["grant", "debit", "refund", "adjustment", "expiry"];
 
 // src/shared/constants/error-codes.constants.ts
 var AI_TOKENS_ERROR_CODES = {
+  /** Reserved: nothing raises it. Nest resolves the async options before it builds any service. */
   AI_TOKENS_NOT_CONFIGURED: "AI_TOKENS_NOT_CONFIGURED",
   AI_TOKENS_INVALID_CONFIG: "AI_TOKENS_INVALID_CONFIG",
   AI_TOKENS_UNKNOWN_PROVIDER: "AI_TOKENS_UNKNOWN_PROVIDER",
@@ -1191,7 +1192,6 @@ function normalizeModelId(id) {
 
 // src/server/services/pricing.service.ts
 var SEED_EFFECTIVE_FROM = /* @__PURE__ */ new Date(0);
-var SEED_LOCK_KEY = "ai-tokens:model-prices";
 var PricingService = class {
   /**
    * @param options The resolved module options (pricing config lives here).
@@ -1222,7 +1222,7 @@ var PricingService = class {
     const serviceTier = input.serviceTier ?? "standard";
     const operation = input.operation === "responses" ? "chat" : input.operation;
     const bucket = Math.floor(input.at.getTime() / this.options.pricing.cacheTtlMs);
-    const cacheKey = `${input.provider}|${input.model}|${input.baseModel ?? ""}|${operation}|${serviceTier}|${String(bucket)}`;
+    const cacheKey = JSON.stringify([input.provider, input.model, input.baseModel, operation, serviceTier, bucket]);
     let resolved;
     const cached = this.cache.get(cacheKey);
     if (cached !== void 0 && this.now() < cached.expiresAt) {
@@ -1258,20 +1258,26 @@ var PricingService = class {
   getPriceHistory(provider, model, operation, serviceTier) {
     return this.store.getPriceHistory(provider, model, operation, serviceTier);
   }
-  /** Seed the registry from the pinned snapshot; idempotent and advisory-locked. */
+  /**
+   * Seed the registry from the pinned snapshot, adding only the tuples that have no row at
+   * all. A tuple that already has history, including one the host re-priced with
+   * `upsertPrice`, is left exactly as it is, so running this on every boot is a no-op once
+   * the registry is seeded.
+   */
   async seedFromSnapshot() {
-    const lockable = this.store;
-    if (typeof lockable.acquireSeedLock === "function") {
-      const acquired = await lockable.acquireSeedLock(SEED_LOCK_KEY);
-      if (!acquired) return;
-    }
     const { MODEL_PRICES_SEED } = await import('@bymax-one/nest-ai-tokens/prices');
     for (const row of MODEL_PRICES_SEED) {
-      await this.store.upsertPrice({ ...row, effectiveFrom: SEED_EFFECTIVE_FROM });
+      const input = { ...row, effectiveFrom: SEED_EFFECTIVE_FROM };
+      if (typeof this.store.seedPrice === "function") {
+        await this.store.seedPrice(input);
+        continue;
+      }
+      const history = await this.store.getPriceHistory(row.provider, row.model, row.operation, row.serviceTier);
+      if (history.length === 0) await this.store.upsertPrice(input);
     }
     this.cache.clear();
   }
-  /** The §6.6 six-step model-resolution chain (exact → baseModel → alias → normalized → prefix). */
+  /** The §6.6 model-resolution chain (exact → baseModel → alias → normalized → prefix). */
   async resolveUncached(provider, model, operation, serviceTier, at, baseModel) {
     const exact = await this.store.resolveRate(provider, model, operation, serviceTier, at);
     if (exact !== null) return exact;
@@ -2773,10 +2779,10 @@ var WalletService = class {
   options;
   events;
   /**
-   * The current balance, excluding not-yet-effective and expired grants (§9.2).
-   * Reads the materialized balance; expiry is applied lazily on debit, so a grant
-   * that lapses purely with the passage of time is reflected at the next debit or
-   * `reconcile` (the documented §9.3 lazy-materialization trade-off).
+   * The current balance (§9.2). Reads the materialized balance; expiry is applied
+   * lazily on debit, so a grant that lapses purely with the passage of time is still
+   * counted until the next debit or `reconcile` (the documented §9.3
+   * lazy-materialization trade-off).
    *
    * @param ref The wallet owner (a `'tenant' | 'team' | 'user'`, never `'key'`).
    * @returns The nano-USD balance and its presentation credits.
@@ -2963,7 +2969,7 @@ var WalletService = class {
    * `ai_tokens.audit`.
    *
    * @param ref The wallet owner.
-   * @returns The reconciled wallet.
+   * @returns The reconciled nano-USD balance and its presentation credits.
    */
   async reconcile(ref) {
     this.assertOwner(ref);
@@ -4076,6 +4082,26 @@ function writeHeader(response, name, value) {
   if (typeof response.setHeader === "function") response.setHeader(name, value);
   else if (typeof response.header === "function") response.header(name, value);
 }
+
+// src/server/disabled-service.ts
+var DISABLED = /* @__PURE__ */ Symbol("bymax.ai-tokens.disabled-service");
+function disabledService(service, block) {
+  const fail = () => {
+    throw new AiTokensException("AI_TOKENS_INVALID_CONFIG", void 0, {
+      reason: `${block} not configured: set options.${block} to enable ${service.name}`
+    });
+  };
+  const standIn = Object.create(service.prototype);
+  for (const name of Object.getOwnPropertyNames(service.prototype)) {
+    if (name !== "constructor") Object.defineProperty(standIn, name, { value: fail, enumerable: false });
+  }
+  Object.defineProperty(standIn, DISABLED, { value: true, enumerable: false });
+  return standIn;
+}
+function liveService(service) {
+  if (service === null || service === void 0) return null;
+  return service[DISABLED] === true ? null : service;
+}
 var REAP_BATCH_SIZE = 100;
 var MS_PER_SECOND = 1e3;
 var SCAN_FAILED_LOG_KEY = "ai_tokens.hold_reaper.scan_failed";
@@ -4206,7 +4232,7 @@ function buildServiceProviders() {
   return [
     {
       provide: MeteringService,
-      useFactory: (ledger, pricing, markup, options, dispatcher, telemetrySink, wallets, budgets) => new MeteringService(ledger, pricing, markup, options, createMeteringEventHooks(dispatcher), wallets, budgets, void 0, new TelemetryEmitter(telemetrySink), new ContentCapture(options.content)),
+      useFactory: (ledger, pricing, markup, options, dispatcher, telemetrySink, wallets, budgets) => new MeteringService(ledger, pricing, markup, options, createMeteringEventHooks(dispatcher), liveService(wallets), liveService(budgets), void 0, new TelemetryEmitter(telemetrySink), new ContentCapture(options.content)),
       inject: [
         LedgerService,
         PricingService,
@@ -4236,21 +4262,21 @@ function buildServiceProviders() {
 function walletServiceProvider() {
   return {
     provide: WalletService,
-    useFactory: (options, store, dispatcher) => options.wallets.enabled ? new WalletService(store, options.wallets, createWalletEventHooks(dispatcher)) : null,
+    useFactory: (options, store, dispatcher) => options.wallets.enabled ? new WalletService(store, options.wallets, createWalletEventHooks(dispatcher)) : disabledService(WalletService, "wallets"),
     inject: [BYMAX_AI_TOKENS_OPTIONS, BYMAX_AI_TOKENS_WALLET_STORE, EventDispatcher]
   };
 }
 function budgetServiceProvider() {
   return {
     provide: BudgetService,
-    useFactory: (options, store, ledger, dispatcher) => options.budgets.enabled ? new BudgetService(store, ledger, options.budgets, void 0, createBudgetEventHooks(dispatcher)) : null,
+    useFactory: (options, store, ledger, dispatcher) => options.budgets.enabled ? new BudgetService(store, ledger, options.budgets, void 0, createBudgetEventHooks(dispatcher)) : disabledService(BudgetService, "budgets"),
     inject: [BYMAX_AI_TOKENS_OPTIONS, BYMAX_AI_TOKENS_BUDGET_STORE, LedgerService, EventDispatcher]
   };
 }
 function budgetGuardProvider() {
   return {
     provide: BudgetGuard,
-    useFactory: (options, budgets, metering, reflector) => options.budgets.enabled ? new BudgetGuard(budgets, metering, reflector, options) : null,
+    useFactory: (options, budgets, metering, reflector) => options.budgets.enabled ? new BudgetGuard(budgets, metering, reflector, options) : disabledService(BudgetGuard, "budgets"),
     inject: [BYMAX_AI_TOKENS_OPTIONS, BudgetService, MeteringService, Reflector]
   };
 }
@@ -4297,7 +4323,7 @@ async function safeResolve(load) {
 }
 function buildAsyncOptionsProviders(descriptor) {
   if (descriptor.useFactory !== void 0) {
-    const factory = descriptor.useFactory;
+    const factory = descriptor.useFactory.bind(descriptor);
     return [
       {
         provide: BYMAX_AI_TOKENS_OPTIONS,

package/dist/shared/index.cjs

@@ -49,6 +49,7 @@ var WALLET_ENTRY_TYPES = ["grant", "debit", "refund", "adjustment", "expiry"];
 
 // src/shared/constants/error-codes.constants.ts
 var AI_TOKENS_ERROR_CODES = {
+  /** Reserved: nothing raises it. Nest resolves the async options before it builds any service. */
   AI_TOKENS_NOT_CONFIGURED: "AI_TOKENS_NOT_CONFIGURED",
   AI_TOKENS_INVALID_CONFIG: "AI_TOKENS_INVALID_CONFIG",
   AI_TOKENS_UNKNOWN_PROVIDER: "AI_TOKENS_UNKNOWN_PROVIDER",

package/dist/shared/index.d.cts

@@ -70,6 +70,7 @@ type WalletEntryType = (typeof WALLET_ENTRY_TYPES)[number];
  */
 /** Every error code the library can raise, mapped to itself for value access. */
 declare const AI_TOKENS_ERROR_CODES: {
+    /** Reserved: nothing raises it. Nest resolves the async options before it builds any service. */
     readonly AI_TOKENS_NOT_CONFIGURED: "AI_TOKENS_NOT_CONFIGURED";
     readonly AI_TOKENS_INVALID_CONFIG: "AI_TOKENS_INVALID_CONFIG";
     readonly AI_TOKENS_UNKNOWN_PROVIDER: "AI_TOKENS_UNKNOWN_PROVIDER";

package/dist/shared/index.d.ts

@@ -70,6 +70,7 @@ type WalletEntryType = (typeof WALLET_ENTRY_TYPES)[number];
  */
 /** Every error code the library can raise, mapped to itself for value access. */
 declare const AI_TOKENS_ERROR_CODES: {
+    /** Reserved: nothing raises it. Nest resolves the async options before it builds any service. */
     readonly AI_TOKENS_NOT_CONFIGURED: "AI_TOKENS_NOT_CONFIGURED";
     readonly AI_TOKENS_INVALID_CONFIG: "AI_TOKENS_INVALID_CONFIG";
     readonly AI_TOKENS_UNKNOWN_PROVIDER: "AI_TOKENS_UNKNOWN_PROVIDER";

package/dist/shared/index.mjs

@@ -47,6 +47,7 @@ var WALLET_ENTRY_TYPES = ["grant", "debit", "refund", "adjustment", "expiry"];
 
 // src/shared/constants/error-codes.constants.ts
 var AI_TOKENS_ERROR_CODES = {
+  /** Reserved: nothing raises it. Nest resolves the async options before it builds any service. */
   AI_TOKENS_NOT_CONFIGURED: "AI_TOKENS_NOT_CONFIGURED",
   AI_TOKENS_INVALID_CONFIG: "AI_TOKENS_INVALID_CONFIG",
   AI_TOKENS_UNKNOWN_PROVIDER: "AI_TOKENS_UNKNOWN_PROVIDER",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-ai-tokens",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "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",