@bymax-one/nest-ai-tokens 1.1.2 → 1.1.4

package/CHANGELOG.md

@@ -8,6 +8,149 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and
 
 ## [Unreleased]
 
+## [1.1.4] - 2026-11-01
+
+**Apply:** `verifyChain` has a new result, `{ valid: false, status: 'never-enabled' }`, which has no
+`brokenAtRecordId`; handle it wherever you read that field. Enable `ledger.hashChain` before the
+first write: records written earlier are reported as unchained and are not protected.
+
+### Fixed
+
+- **Enabling `ledger.hashChain` on a ledger that already has records no longer makes `verifyChain`
+  report the oldest record as tampered.** `verifyChain` required every settled record to carry a
+  hash, so the first record written before the chain was enabled failed verification and ended the
+  walk, and the chained records after it were never checked. It now follows the chain by its links:
+  records without a hash are counted in the new `unchainedCount` and reported as not protected, the
+  hashed records must start at one genesis with no gap in the links, and a record whose hash was
+  removed while its `prevHash` stayed is reported as broken. A ledger with settled records and no
+  hashed one returns `{ valid: false, status: 'never-enabled' }`. The result type gains
+  `unchainedCount` and an optional `chainStartsAtRecordId`; the new `never-enabled` variant has no
+  `brokenAtRecordId`. A `from`/`to` call still checks each record's own hash only. A record that no other
+  record names as its predecessor (the newest one, and a hold that settled while a later-created record
+  was already hashed) can be deleted without detection, and the chain is unkeyed; both limits are in the README.
+
+  **Apply:** code that reads `brokenAtRecordId` after `valid === false` must also handle the
+  `never-enabled` variant, which has none. Enable the chain before the first write; a rise in
+  `unchainedCount` after enabling is worth investigating.
+
+### Changed
+
+- The GitHub Release body is now the tag's own `CHANGELOG.md` section instead of the generated
+  pull-request list, and the release stops before publishing when the version has no section.
+  No change to the package.
+- The release-notes step starts the section only at a line that begins `## [<version>]`, so a
+  version token elsewhere in a heading, such as `## [Unreleased] [1.1.1]`, no longer selects the
+  wrong body.
+- The unused optional peer `@opentelemetry/api` is removed from `peerDependencies` and
+  `peerDependenciesMeta`. The package imports nothing from it; telemetry goes through the
+  `ITelemetrySink` you implement. Consumers lose only an install hint.
+
+### Documentation
+
+- The README says that `MODEL_PRICES_SEED` has no rows for `azure-openai`, `vertex`, `bedrock` or
+  `openrouter`, so with `pricing.strict` on a call through the first three presets throws
+  `AI_TOKENS_PRICE_NOT_FOUND` until the host adds a price (the `openrouter` preset rates from the
+  provider-reported cost), and shows a minimal `upsertPrice` call.
+
+## [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
@@ -203,7 +346,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.
@@ -214,7 +357,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.
@@ -297,7 +440,9 @@ have regressed from. They are kept because the reasoning is worth having.
 [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.4]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.1.3...v1.1.4
 [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.2...HEAD
+[Unreleased]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.1.4...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,13 +330,20 @@ 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`                        |
 
 All normalizers are pure functions over plain objects — no provider SDK peer dependency. Pass the raw response object and get back a `NormalizedUsage`.
 
+`MODEL_PRICES_SEED` has no rows for `azure-openai`, `vertex`, `bedrock` or `openrouter`; it covers
+`openai`, `anthropic`, `gemini`, `mistral`, `deepseek`, `xai` and `groq`. With `pricing.strict` on
+(the default), a call through the `azure-openai`, `vertex` or `bedrock` preset throws
+`AI_TOKENS_PRICE_NOT_FOUND` until you add its price. The `openrouter` preset rates from the cost the
+provider reports, so it needs no price unless a call sets `ratingMode: 'rate-table'`. See
+[Pricing & Markup](#-pricing--markup).
+
 ---
 
 ## 💰 Pricing & Markup
@@ -325,7 +353,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
@@ -338,11 +366,25 @@ BymaxAiTokensModule.forRootAsync({
 // Margin: $0.015 per call
 ```
 
+A provider or model the snapshot does not price needs a rate before it can be rated. Add one with
+`PricingService.upsertPrice`; the new row closes the previous one at its `effectiveFrom`, which
+defaults to now. Rates are nano-USD per million tokens:
+
+```typescript
+await pricing.upsertPrice({
+  provider: 'bedrock',
+  model: 'my-model', // the model id your calls report
+  operation: 'chat',
+  inputNanoUsdPerMillion: 3_000_000_000n, // $3 per million input tokens
+  outputNanoUsdPerMillion: 15_000_000_000n, // $15 per million output tokens
+})
+```
+
 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 +412,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 +485,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 +494,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 +532,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 +559,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 +585,55 @@ 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                                                   |
 
+#### Verifying the hash chain
+
+`LedgerService.verifyChain(tenantId, from?, to?)` resolves to a `ChainVerification`:
+
+- `{ valid: true, unchainedCount, chainStartsAtRecordId? }` — every hashed record recomputes and, on a call
+  without `from`/`to`, the hashed records form one chain. `chainStartsAtRecordId` is the genesis record
+  when the verified records include it.
+- `{ valid: false, brokenAtRecordId, unchainedCount }` — the record that fails: a record whose hash was
+  removed while its link stayed, a changed record, or, without `from`/`to`, a gap (a second chain start)
+  or a chain that does not start at a genesis record (its first head). Those checks run in that order,
+  and within each the earliest record in listing order is reported. Two records may share a predecessor:
+  a hold that settles after a later record links to the record created last, as the next record does.
+- `{ valid: false, status: 'never-enabled', unchainedCount }` — settled records exist and none carries a hash or a link. This
+  is not evidence of tampering; `ledger.hashChain` was simply never on for this tenant.
+
+Enable `ledger.hashChain` before the first write. Records written before it was enabled are **unchained**:
+they are counted in `unchainedCount`, not verified and not protected.
+
+What it does not catch, plainly:
+
+1. A record that no other record names as its predecessor can be deleted without detection. That is
+   the newest record, and a hold that settled while a later-created record was already hashed (a record
+   links to the hashed record created last, so that hold is never linked to). A hold that settles as
+   the newest-created record is linked by the next record and is not affected.
+2. The chain is unkeyed. Someone with write access who recomputes the whole tail is not detected, so
+   anchor the latest hash outside the database.
+3. An `unchainedCount` that rises after the chain was enabled is a signal to investigate. A rolling deploy
+   with mixed `hashChain` settings can also cause it.
+4. A call with `from` or `to` checks each record's own hash only, not the links between records.
+
+### 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 +758,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 +801,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;