@bymax-one/nest-ai-tokens 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -8,6 +8,58 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and
 
 ## [Unreleased]
 
+## [1.0.2] - 2026-08-05
+
+### Fixed
+
+- **The module could not be initialised by a consumer at all.** `MeteringInterceptor` is
+  registered as a plain class provider, so Nest resolves its constructor — but only the
+  third parameter carried a token. Nest reads two separate metadata keys for this:
+  `self:paramtypes`, written by `@Inject()`, and `design:paramtypes`, written by
+  TypeScript. The published bundle is built by tsup/esbuild, and esbuild states it cannot
+  implement `emitDecoratorMetadata` because it does not replicate TypeScript's type
+  system — so the second key was never there. The first two parameters had neither, and
+  the container threw `Nest can't resolve dependencies of the MeteringInterceptor
+  (?, +, Symbol(BYMAX_AI_TOKENS_OPTIONS))` before any provider was created. Both now
+  carry `@Inject`.
+
+### Changed
+
+- `emitDecoratorMetadata` is `false` in `tsconfig.json`. It was `true`, which was never
+  true of the artifact: tsup prints `You have emitDecoratorMetadata enabled but
+  @swc/core was not installed, skipping swc plugin` on every build, and that warning had
+  been printed on every build of this package. Turning it off makes the source compile
+  the way the bundle is built, so a parameter that depends on reflected types now fails
+  where it is cheap to see.
+- The imports that existed only to feed that metadata are `import type` again. The lint
+  rule reported each one the moment the flag went off, which makes it a precise detector
+  for this defect: an import that is value-only because a constructor parameter needs its
+  type is an import that will not survive the bundle.
+
+## [1.0.1] - 2026-08-04
+
+### Removed
+
+- The README's `Migration` section, which described migrating an AI cost layer out of a
+  named private monorepo. It reached the npm page of a public package, where it named a
+  repository its readers cannot see and cannot act on. The normative rule it carried —
+  translate `0`/`null` limits to no budget row — is already stated under the budget
+  semantics and is unchanged.
+
+### Security
+
+- The Redis credentials are no longer disclosed when `RedisBudgetCounterStore` is
+  serialized. The store kept the live client — or the connection URL it is opened from —
+  in a TypeScript `private` property, which is erased at runtime and leaves an enumerable
+  own property. A connection URL carries the password inline and an ioredis instance
+  carries `options.password` as a plain field, so `JSON.stringify`, object spread and
+  `util.inspect` emitted the password in plaintext, which is what a structured logger does
+  when it renders its arguments and what an error reporter does when it captures the scope
+  of a throw. The source and the in-flight lazy connection both move to ECMAScript private
+  fields.
+
+Reading on purpose is unchanged and no public type or export moved.
+
 ## [1.0.0] - 2026-08-03
 
 First published release. Everything below ships in it.
@@ -110,4 +162,6 @@ have regressed from. They are kept because the reasoning is worth having.
 ---
 
 [1.0.0]: https://github.com/bymaxone/nest-ai-tokens/releases/tag/v1.0.0
-[Unreleased]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.0.0...HEAD
+[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
+[Unreleased]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.0.2...HEAD

package/README.md

@@ -395,7 +395,7 @@ const status = await metering.getStatus(tenantId, { type: 'user', id: userId })
 // status[].remaining, status[].exhausted, status[].policy
 ```
 
-**Unlimited semantics:** no budget row = unlimited. `limit = 0` = hard block. Never use `null` or `0` to mean unlimited (see §22 migration notes).
+**Unlimited semantics:** no budget row = unlimited. `limit = 0` = hard block. Never use `null` or `0` to mean unlimited.
 
 ---
 
@@ -532,14 +532,6 @@ formatNanoUsd(5_000_000n, { currency: 'BRL', fxRateNano: 5_000_000_000n }) // '0
 
 ---
 
-## 🚚 Migration
-
-If you are migrating the `_commons_/ai/*` layer from `bymax-fitness`, see [docs/technical_specification.md §22](./docs/technical_specification.md) for the full field-by-field mapping table, the zero/null → unlimited translation rules, and backfill notes.
-
-Key caution: `bymax-fitness` treats `0` as unlimited on most paths and as blocked on one path. Do not import plan rows verbatim. Translate `0`/`null` limits to **no budget row** (the normative unlimited representation in this library).
-
----
-
 ## 📖 API Reference
 
 The sections above document each of these with a runnable example. This is the index.

package/dist/redis/index.cjs

@@ -36,15 +36,26 @@ var CounterValueOutOfRangeError = class extends Error {
 };
 var RedisBudgetCounterStore = class {
   keyPrefix;
-  source;
-  connecting = null;
+  /**
+   * The live client or the connection URL it is opened from.
+   *
+   * An ECMAScript private field rather than a TypeScript `private` one, which is
+   * erased at runtime: a connection URL carries the Redis password inline, and an
+   * ioredis instance carries `options.password` as a plain field. Leaving either
+   * enumerable would let anything that serializes this store — a structured
+   * logger rendering its arguments, an error reporter capturing the scope of a
+   * throw — emit the credentials in plaintext.
+   */
+  #source;
+  /** The in-flight lazy connection, which resolves to the same credentialed client. */
+  #connecting = null;
   /**
    * @param redis A live `ioredis` client, or a connection URL to lazily connect.
    * @param options Optional key prefix.
    */
   constructor(redis, options = {}) {
     this.keyPrefix = options.keyPrefix ?? "";
-    this.source = redis;
+    this.#source = redis;
   }
   /**
    * Atomically increment `key` by `amount` iff the result stays `<= limit`, setting
@@ -95,9 +106,9 @@ var RedisBudgetCounterStore = class {
   }
   /** Resolve the live client, lazily connecting a URL via a dynamic `ioredis` import. */
   resolve() {
-    if (typeof this.source !== "string") return Promise.resolve(this.source);
-    this.connecting ??= this.connect(this.source);
-    return this.connecting;
+    if (typeof this.#source !== "string") return Promise.resolve(this.#source);
+    this.#connecting ??= this.connect(this.#source);
+    return this.#connecting;
   }
   /** Dynamically import `ioredis` and connect the given URL. */
   async connect(url) {

package/dist/redis/index.d.cts

@@ -54,9 +54,8 @@ declare class CounterValueOutOfRangeError extends Error {
 }
 /** The official Redis adapter for the live budget counter port. */
 declare class RedisBudgetCounterStore implements IBudgetCounterStore {
+    #private;
     private readonly keyPrefix;
-    private readonly source;
-    private connecting;
     /**
      * @param redis A live `ioredis` client, or a connection URL to lazily connect.
      * @param options Optional key prefix.

package/dist/redis/index.d.ts

@@ -54,9 +54,8 @@ declare class CounterValueOutOfRangeError extends Error {
 }
 /** The official Redis adapter for the live budget counter port. */
 declare class RedisBudgetCounterStore implements IBudgetCounterStore {
+    #private;
     private readonly keyPrefix;
-    private readonly source;
-    private connecting;
     /**
      * @param redis A live `ioredis` client, or a connection URL to lazily connect.
      * @param options Optional key prefix.

package/dist/redis/index.mjs

@@ -34,15 +34,26 @@ var CounterValueOutOfRangeError = class extends Error {
 };
 var RedisBudgetCounterStore = class {
   keyPrefix;
-  source;
-  connecting = null;
+  /**
+   * The live client or the connection URL it is opened from.
+   *
+   * An ECMAScript private field rather than a TypeScript `private` one, which is
+   * erased at runtime: a connection URL carries the Redis password inline, and an
+   * ioredis instance carries `options.password` as a plain field. Leaving either
+   * enumerable would let anything that serializes this store — a structured
+   * logger rendering its arguments, an error reporter capturing the scope of a
+   * throw — emit the credentials in plaintext.
+   */
+  #source;
+  /** The in-flight lazy connection, which resolves to the same credentialed client. */
+  #connecting = null;
   /**
    * @param redis A live `ioredis` client, or a connection URL to lazily connect.
    * @param options Optional key prefix.
    */
   constructor(redis, options = {}) {
     this.keyPrefix = options.keyPrefix ?? "";
-    this.source = redis;
+    this.#source = redis;
   }
   /**
    * Atomically increment `key` by `amount` iff the result stays `<= limit`, setting
@@ -93,9 +104,9 @@ var RedisBudgetCounterStore = class {
   }
   /** Resolve the live client, lazily connecting a URL via a dynamic `ioredis` import. */
   resolve() {
-    if (typeof this.source !== "string") return Promise.resolve(this.source);
-    this.connecting ??= this.connect(this.source);
-    return this.connecting;
+    if (typeof this.#source !== "string") return Promise.resolve(this.#source);
+    this.#connecting ??= this.connect(this.#source);
+    return this.#connecting;
   }
   /** Dynamically import `ioredis` and connect the given URL. */
   async connect(url) {

package/dist/server/index.cjs

@@ -1185,240 +1185,6 @@ function exhaustedError(status, feature) {
   }
   return null;
 }
-exports.MeteringInterceptor = class MeteringInterceptor {
-  /**
-   * @param reflector The NestJS reflector (`@Meter` metadata).
-   * @param metering The metering facade (capture/record).
-   * @param options The resolved options (fallback `scopeResolver` when no guard ran).
-   */
-  constructor(reflector, metering, options) {
-    this.reflector = reflector;
-    this.metering = metering;
-    this.scopeResolver = options.scopeResolver;
-  }
-  reflector;
-  metering;
-  logger = new common.Logger(exports.MeteringInterceptor.name);
-  scopeResolver;
-  /**
-   * Capture (or record) the handler's usage after it resolves; release the guard's
-   * hold on a handler error.
-   *
-   * @param executionContext The request execution context.
-   * @param next The downstream handler.
-   * @returns The handler's result stream, unchanged in value.
-   */
-  intercept(executionContext, next) {
-    const targets = [executionContext.getHandler(), executionContext.getClass()];
-    const config = this.reflector.getAllAndOverride(METER_METADATA, targets);
-    if (config === void 0) return next.handle();
-    const request = executionContext.switchToHttp().getRequest();
-    const enrichment = request.aiTokens;
-    return next.handle().pipe(
-      rxjs.mergeMap((result) => rxjs.from(this.settle(executionContext, config, enrichment, result))),
-      operators.catchError((error) => this.onError(enrichment, error))
-    );
-  }
-  /** Settle the handler's usage and set the cost headers; returns the untouched result. */
-  async settle(executionContext, config, enrichment, result) {
-    const usage = extractUsage(result, config);
-    const record = await this.capture(executionContext, config, enrichment, usage);
-    if (config.exposeHeaders === true) this.setHeaders(executionContext, record, enrichment);
-    return result;
-  }
-  /** Capture the guard's hold when present, else record enforcing post-hoc. */
-  async capture(executionContext, config, enrichment, usage) {
-    if (enrichment?.hold !== void 0) return this.metering.capture(enrichment.hold, usage, config.preset);
-    const context = await this.resolveContext(executionContext, config, enrichment);
-    return this.metering.record({
-      usage,
-      // Stryker disable next-line ConditionalExpression -- CE true: spreading { preset: undefined } is equivalent to {} because MeteringService checks preset !== undefined
-      ...config.preset !== void 0 ? { preset: config.preset } : {},
-      // Stryker disable next-line ConditionalExpression -- CE true: spreading { tags: undefined } is equivalent to {} because MeteringService checks tags !== undefined
-      context: { ...context, enforce: true, isSystemCost: config.isSystemCost ?? false, ...config.tags !== void 0 ? { tags: config.tags } : {} }
-    });
-  }
-  /** The metering context: the guard's enrichment, else the host `scopeResolver`. */
-  async resolveContext(executionContext, config, enrichment) {
-    if (enrichment !== void 0) return enrichment.context;
-    if (this.scopeResolver === void 0) {
-      throw new AiTokensException("AI_TOKENS_INVALID_CONFIG", void 0, { reason: "MeteringInterceptor requires options.scopeResolver when no BudgetGuard ran" });
-    }
-    const resolved = await this.scopeResolver(executionContext);
-    return { ...resolved, feature: config.feature, ...config.preset !== void 0 ? { preset: config.preset } : {} };
-  }
-  /** Release the guard's hold (if any) and rethrow the ORIGINAL handler error. */
-  onError(enrichment, error) {
-    if (enrichment?.hold === void 0) return rxjs.throwError(() => error);
-    const holdId = enrichment.hold.id;
-    const released = this.metering.release(enrichment.hold, "handler threw").catch(() => {
-      this.logger.warn(`failed to release hold ${holdId} after a handler error; the reaper will reclaim it`);
-    });
-    return rxjs.from(released).pipe(rxjs.mergeMap(() => rxjs.throwError(() => error)));
-  }
-  /** Set the three `x-ai-tokens-*` headers as decimal strings via the HTTP adapter. */
-  setHeaders(executionContext, record, enrichment) {
-    const response = executionContext.switchToHttp().getResponse();
-    writeHeader(response, "x-ai-tokens-cost", record.rawCostNanoUsd.toString());
-    writeHeader(response, "x-ai-tokens-billed-cost", record.billedCostNanoUsd.toString());
-    const remaining = minBudgetRemaining(enrichment);
-    if (remaining !== void 0) writeHeader(response, "x-ai-tokens-budget-remaining", remaining.toString());
-  }
-};
-exports.MeteringInterceptor = __decorateClass([
-  common.Injectable(),
-  __decorateParam(2, common.Inject(BYMAX_AI_TOKENS_OPTIONS))
-], exports.MeteringInterceptor);
-function extractUsage(result, config) {
-  const extract = config.extract ?? ((value) => typeof value === "object" && value !== null ? value.usage : void 0);
-  const usage = extract(result);
-  if (usage === void 0 || usage === null) {
-    throw new AiTokensException("AI_TOKENS_USAGE_MALFORMED", void 0, { reason: "the handler result carried no extractable usage" });
-  }
-  return usage;
-}
-function minBudgetRemaining(enrichment) {
-  let min;
-  for (const status of enrichment?.status ?? []) {
-    const remaining = status.remaining.nanoUsd;
-    if (remaining !== void 0 && (min === void 0 || remaining < min)) min = remaining;
-  }
-  return min;
-}
-function writeHeader(response, name, value) {
-  if (typeof response.setHeader === "function") response.setHeader(name, value);
-  else if (typeof response.header === "function") response.header(name, value);
-}
-var REAP_BATCH_SIZE = 100;
-var MS_PER_SECOND = 1e3;
-var HoldReaper = class {
-  /**
-   * @param ledger The ledger service (expired-hold scan + atomic void claim).
-   * @param metering The metering facade (shared hold-restoration path).
-   * @param options The resolved options carrying the hold TTL + sweep interval.
-   * @param now The injected clock (testability).
-   */
-  constructor(ledger, metering, options, now = () => /* @__PURE__ */ new Date()) {
-    this.ledger = ledger;
-    this.metering = metering;
-    this.options = options;
-    this.now = now;
-  }
-  ledger;
-  metering;
-  options;
-  now;
-  logger = new common.Logger(HoldReaper.name);
-  timer;
-  /** Start the periodic sweep on module boot (interval `unref()`'d so it never blocks exit). */
-  onApplicationBootstrap() {
-    const intervalMs = this.options.holds.reaperIntervalSeconds * MS_PER_SECOND;
-    this.timer = setInterval(() => void this.sweep(), intervalMs);
-    this.timer.unref();
-  }
-  /** Stop the sweep on shutdown (no open handles left for Jest). */
-  onApplicationShutdown() {
-    if (this.timer !== void 0) clearInterval(this.timer);
-    this.timer = void 0;
-  }
-  /**
-   * Reclaim one batch of expired pending holds. For each: win the atomic
-   * `pending → released` claim (a `null` result means another replica won — skip),
-   * then run the shared restoration + `hold.released` emission. A failure on one
-   * hold is logged and never aborts the batch (deterministic, idempotent, safe to
-   * run repeatedly).
-   */
-  async sweep() {
-    const cutoff = new Date(this.now().getTime() - this.options.holds.ttlSeconds * MS_PER_SECOND);
-    const expired = await this.ledger.findExpiredHolds(cutoff, REAP_BATCH_SIZE);
-    for (const record of expired) {
-      try {
-        const claimed = await this.ledger.transition(record.id, "pending", "released");
-        if (claimed === null) continue;
-        await this.metering.restoreReleasedHold(claimed, "expired", true);
-      } catch {
-        this.logger.warn(`failed to reap expired hold ${record.id}`);
-      }
-    }
-  }
-};
-HoldReaper = __decorateClass([
-  common.Injectable()
-], HoldReaper);
-
-// src/server/telemetry/otel-emitter.ts
-function buildGenAiAttributes(record) {
-  return {
-    "gen_ai.provider.name": record.provider,
-    "gen_ai.request.model": record.requestedModel ?? record.model,
-    "gen_ai.response.model": record.model,
-    "gen_ai.operation.name": record.operation,
-    "gen_ai.request.service_tier": record.serviceTier,
-    "gen_ai.usage.input_tokens": record.inputTokens,
-    "gen_ai.usage.output_tokens": record.outputTokens
-  };
-}
-var TelemetryEmitter = class {
-  /** @param sink The host telemetry sink, or `null` to disable telemetry. */
-  constructor(sink) {
-    this.sink = sink;
-  }
-  sink;
-  /**
-   * Record a usage measurement for a posted record (no-op without a sink).
-   *
-   * @param record The posted usage record.
-   */
-  recordUsage(record) {
-    if (this.sink === null) return;
-    this.sink.recordUsage(buildGenAiAttributes(record), record);
-  }
-  /**
-   * Record an operation duration for a posted record (no-op without a sink, or when
-   * the sink does not implement `recordDuration`).
-   *
-   * @param record The posted usage record.
-   * @param milliseconds The measured operation duration.
-   */
-  recordDuration(record, milliseconds) {
-    const sink = this.sink;
-    if (sink?.recordDuration === void 0) return;
-    sink.recordDuration(buildGenAiAttributes(record), milliseconds);
-  }
-};
-var IDENTITY = (text) => text;
-var ContentCapture = class _ContentCapture {
-  /** @param options The resolved content-sidecar settings (disabled by default). */
-  constructor(options) {
-    this.options = options;
-  }
-  options;
-  logger = new common.Logger(_ContentCapture.name);
-  /**
-   * Persist the masked prompt/completion to the content sidecar. A no-op when the
-   * feature is disabled or no text was supplied. Failures are logged (never the
-   * text) and never rethrown — content capture must not break metering.
-   *
-   * @param input The record id, tenant, and the host-supplied text.
-   */
-  async capture(input) {
-    if (!this.options.enabled) return;
-    if (input.prompt === void 0 && input.completion === void 0) return;
-    const { store, ttlSeconds } = this.options;
-    const mask = this.options.mask ?? IDENTITY;
-    try {
-      if (input.prompt !== void 0) {
-        await store.put({ usageRecordId: input.usageRecordId, tenantId: input.tenantId, role: "prompt", text: mask(input.prompt), ttlSeconds });
-      }
-      if (input.completion !== void 0) {
-        await store.put({ usageRecordId: input.usageRecordId, tenantId: input.tenantId, role: "completion", text: mask(input.completion), ttlSeconds });
-      }
-    } catch {
-      this.logger.error(`failed to write content sidecar for record ${input.usageRecordId}`);
-    }
-  }
-};
-var NO_OP_CONTENT_CAPTURE = new ContentCapture({ enabled: false });
 
 // src/server/utils/model-id.ts
 function normalizeModelId(id) {
@@ -2248,8 +2014,82 @@ function numberOf(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 
+// src/server/telemetry/otel-emitter.ts
+function buildGenAiAttributes(record) {
+  return {
+    "gen_ai.provider.name": record.provider,
+    "gen_ai.request.model": record.requestedModel ?? record.model,
+    "gen_ai.response.model": record.model,
+    "gen_ai.operation.name": record.operation,
+    "gen_ai.request.service_tier": record.serviceTier,
+    "gen_ai.usage.input_tokens": record.inputTokens,
+    "gen_ai.usage.output_tokens": record.outputTokens
+  };
+}
+var TelemetryEmitter = class {
+  /** @param sink The host telemetry sink, or `null` to disable telemetry. */
+  constructor(sink) {
+    this.sink = sink;
+  }
+  sink;
+  /**
+   * Record a usage measurement for a posted record (no-op without a sink).
+   *
+   * @param record The posted usage record.
+   */
+  recordUsage(record) {
+    if (this.sink === null) return;
+    this.sink.recordUsage(buildGenAiAttributes(record), record);
+  }
+  /**
+   * Record an operation duration for a posted record (no-op without a sink, or when
+   * the sink does not implement `recordDuration`).
+   *
+   * @param record The posted usage record.
+   * @param milliseconds The measured operation duration.
+   */
+  recordDuration(record, milliseconds) {
+    const sink = this.sink;
+    if (sink?.recordDuration === void 0) return;
+    sink.recordDuration(buildGenAiAttributes(record), milliseconds);
+  }
+};
+
 // src/server/telemetry/no-op-telemetry.ts
 var NO_OP_TELEMETRY = new TelemetryEmitter(null);
+var IDENTITY = (text) => text;
+var ContentCapture = class _ContentCapture {
+  /** @param options The resolved content-sidecar settings (disabled by default). */
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  logger = new common.Logger(_ContentCapture.name);
+  /**
+   * Persist the masked prompt/completion to the content sidecar. A no-op when the
+   * feature is disabled or no text was supplied. Failures are logged (never the
+   * text) and never rethrown — content capture must not break metering.
+   *
+   * @param input The record id, tenant, and the host-supplied text.
+   */
+  async capture(input) {
+    if (!this.options.enabled) return;
+    if (input.prompt === void 0 && input.completion === void 0) return;
+    const { store, ttlSeconds } = this.options;
+    const mask = this.options.mask ?? IDENTITY;
+    try {
+      if (input.prompt !== void 0) {
+        await store.put({ usageRecordId: input.usageRecordId, tenantId: input.tenantId, role: "prompt", text: mask(input.prompt), ttlSeconds });
+      }
+      if (input.completion !== void 0) {
+        await store.put({ usageRecordId: input.usageRecordId, tenantId: input.tenantId, role: "completion", text: mask(input.completion), ttlSeconds });
+      }
+    } catch {
+      this.logger.error(`failed to write content sidecar for record ${input.usageRecordId}`);
+    }
+  }
+};
+var NO_OP_CONTENT_CAPTURE = new ContentCapture({ enabled: false });
 
 // src/server/services/hold-support.ts
 var UNSPECIFIED = "unspecified";
@@ -4116,6 +3956,170 @@ var exampleRecord = {
   updatedAt: /* @__PURE__ */ new Date(0)
 };
 
+// src/server/enforcement/metering.interceptor.ts
+exports.MeteringInterceptor = class MeteringInterceptor {
+  /**
+   * @param reflector The NestJS reflector (`@Meter` metadata).
+   * @param metering The metering facade (capture/record).
+   * @param options The resolved options (fallback `scopeResolver` when no guard ran).
+   */
+  constructor(reflector, metering, options) {
+    this.reflector = reflector;
+    this.metering = metering;
+    this.scopeResolver = options.scopeResolver;
+  }
+  reflector;
+  metering;
+  logger = new common.Logger(exports.MeteringInterceptor.name);
+  scopeResolver;
+  /**
+   * Capture (or record) the handler's usage after it resolves; release the guard's
+   * hold on a handler error.
+   *
+   * @param executionContext The request execution context.
+   * @param next The downstream handler.
+   * @returns The handler's result stream, unchanged in value.
+   */
+  intercept(executionContext, next) {
+    const targets = [executionContext.getHandler(), executionContext.getClass()];
+    const config = this.reflector.getAllAndOverride(METER_METADATA, targets);
+    if (config === void 0) return next.handle();
+    const request = executionContext.switchToHttp().getRequest();
+    const enrichment = request.aiTokens;
+    return next.handle().pipe(
+      rxjs.mergeMap((result) => rxjs.from(this.settle(executionContext, config, enrichment, result))),
+      operators.catchError((error) => this.onError(enrichment, error))
+    );
+  }
+  /** Settle the handler's usage and set the cost headers; returns the untouched result. */
+  async settle(executionContext, config, enrichment, result) {
+    const usage = extractUsage(result, config);
+    const record = await this.capture(executionContext, config, enrichment, usage);
+    if (config.exposeHeaders === true) this.setHeaders(executionContext, record, enrichment);
+    return result;
+  }
+  /** Capture the guard's hold when present, else record enforcing post-hoc. */
+  async capture(executionContext, config, enrichment, usage) {
+    if (enrichment?.hold !== void 0) return this.metering.capture(enrichment.hold, usage, config.preset);
+    const context = await this.resolveContext(executionContext, config, enrichment);
+    return this.metering.record({
+      usage,
+      // Stryker disable next-line ConditionalExpression -- CE true: spreading { preset: undefined } is equivalent to {} because MeteringService checks preset !== undefined
+      ...config.preset !== void 0 ? { preset: config.preset } : {},
+      // Stryker disable next-line ConditionalExpression -- CE true: spreading { tags: undefined } is equivalent to {} because MeteringService checks tags !== undefined
+      context: { ...context, enforce: true, isSystemCost: config.isSystemCost ?? false, ...config.tags !== void 0 ? { tags: config.tags } : {} }
+    });
+  }
+  /** The metering context: the guard's enrichment, else the host `scopeResolver`. */
+  async resolveContext(executionContext, config, enrichment) {
+    if (enrichment !== void 0) return enrichment.context;
+    if (this.scopeResolver === void 0) {
+      throw new AiTokensException("AI_TOKENS_INVALID_CONFIG", void 0, { reason: "MeteringInterceptor requires options.scopeResolver when no BudgetGuard ran" });
+    }
+    const resolved = await this.scopeResolver(executionContext);
+    return { ...resolved, feature: config.feature, ...config.preset !== void 0 ? { preset: config.preset } : {} };
+  }
+  /** Release the guard's hold (if any) and rethrow the ORIGINAL handler error. */
+  onError(enrichment, error) {
+    if (enrichment?.hold === void 0) return rxjs.throwError(() => error);
+    const holdId = enrichment.hold.id;
+    const released = this.metering.release(enrichment.hold, "handler threw").catch(() => {
+      this.logger.warn(`failed to release hold ${holdId} after a handler error; the reaper will reclaim it`);
+    });
+    return rxjs.from(released).pipe(rxjs.mergeMap(() => rxjs.throwError(() => error)));
+  }
+  /** Set the three `x-ai-tokens-*` headers as decimal strings via the HTTP adapter. */
+  setHeaders(executionContext, record, enrichment) {
+    const response = executionContext.switchToHttp().getResponse();
+    writeHeader(response, "x-ai-tokens-cost", record.rawCostNanoUsd.toString());
+    writeHeader(response, "x-ai-tokens-billed-cost", record.billedCostNanoUsd.toString());
+    const remaining = minBudgetRemaining(enrichment);
+    if (remaining !== void 0) writeHeader(response, "x-ai-tokens-budget-remaining", remaining.toString());
+  }
+};
+exports.MeteringInterceptor = __decorateClass([
+  common.Injectable(),
+  __decorateParam(0, common.Inject(core.Reflector)),
+  __decorateParam(1, common.Inject(exports.MeteringService)),
+  __decorateParam(2, common.Inject(BYMAX_AI_TOKENS_OPTIONS))
+], exports.MeteringInterceptor);
+function extractUsage(result, config) {
+  const extract = config.extract ?? ((value) => typeof value === "object" && value !== null ? value.usage : void 0);
+  const usage = extract(result);
+  if (usage === void 0 || usage === null) {
+    throw new AiTokensException("AI_TOKENS_USAGE_MALFORMED", void 0, { reason: "the handler result carried no extractable usage" });
+  }
+  return usage;
+}
+function minBudgetRemaining(enrichment) {
+  let min;
+  for (const status of enrichment?.status ?? []) {
+    const remaining = status.remaining.nanoUsd;
+    if (remaining !== void 0 && (min === void 0 || remaining < min)) min = remaining;
+  }
+  return min;
+}
+function writeHeader(response, name, value) {
+  if (typeof response.setHeader === "function") response.setHeader(name, value);
+  else if (typeof response.header === "function") response.header(name, value);
+}
+var REAP_BATCH_SIZE = 100;
+var MS_PER_SECOND = 1e3;
+var HoldReaper = class {
+  /**
+   * @param ledger The ledger service (expired-hold scan + atomic void claim).
+   * @param metering The metering facade (shared hold-restoration path).
+   * @param options The resolved options carrying the hold TTL + sweep interval.
+   * @param now The injected clock (testability).
+   */
+  constructor(ledger, metering, options, now = () => /* @__PURE__ */ new Date()) {
+    this.ledger = ledger;
+    this.metering = metering;
+    this.options = options;
+    this.now = now;
+  }
+  ledger;
+  metering;
+  options;
+  now;
+  logger = new common.Logger(HoldReaper.name);
+  timer;
+  /** Start the periodic sweep on module boot (interval `unref()`'d so it never blocks exit). */
+  onApplicationBootstrap() {
+    const intervalMs = this.options.holds.reaperIntervalSeconds * MS_PER_SECOND;
+    this.timer = setInterval(() => void this.sweep(), intervalMs);
+    this.timer.unref();
+  }
+  /** Stop the sweep on shutdown (no open handles left for Jest). */
+  onApplicationShutdown() {
+    if (this.timer !== void 0) clearInterval(this.timer);
+    this.timer = void 0;
+  }
+  /**
+   * Reclaim one batch of expired pending holds. For each: win the atomic
+   * `pending → released` claim (a `null` result means another replica won — skip),
+   * then run the shared restoration + `hold.released` emission. A failure on one
+   * hold is logged and never aborts the batch (deterministic, idempotent, safe to
+   * run repeatedly).
+   */
+  async sweep() {
+    const cutoff = new Date(this.now().getTime() - this.options.holds.ttlSeconds * MS_PER_SECOND);
+    const expired = await this.ledger.findExpiredHolds(cutoff, REAP_BATCH_SIZE);
+    for (const record of expired) {
+      try {
+        const claimed = await this.ledger.transition(record.id, "pending", "released");
+        if (claimed === null) continue;
+        await this.metering.restoreReleasedHold(claimed, "expired", true);
+      } catch {
+        this.logger.warn(`failed to reap expired hold ${record.id}`);
+      }
+    }
+  }
+};
+HoldReaper = __decorateClass([
+  common.Injectable()
+], HoldReaper);
+
 // src/server/bymax-ai-tokens.module.ts
 var CORE_TOKENS = [
   BYMAX_AI_TOKENS_OPTIONS,

package/dist/server/index.mjs

@@ -1,5 +1,5 @@
-import { HttpStatus, Injectable, Inject, Global, Module, HttpException, SetMetadata, Logger } from '@nestjs/common';
-import { ModuleRef, Reflector } from '@nestjs/core';
+import { HttpStatus, Injectable, Inject, Global, Module, Logger, HttpException, SetMetadata } from '@nestjs/common';
+import { Reflector, ModuleRef } from '@nestjs/core';
 import { randomUUID } from 'crypto';
 import { mergeMap, from, throwError } from 'rxjs';
 import { catchError } from 'rxjs/operators';
@@ -1183,240 +1183,6 @@ function exhaustedError(status, feature) {
   }
   return null;
 }
-var MeteringInterceptor = class {
-  /**
-   * @param reflector The NestJS reflector (`@Meter` metadata).
-   * @param metering The metering facade (capture/record).
-   * @param options The resolved options (fallback `scopeResolver` when no guard ran).
-   */
-  constructor(reflector, metering, options) {
-    this.reflector = reflector;
-    this.metering = metering;
-    this.scopeResolver = options.scopeResolver;
-  }
-  reflector;
-  metering;
-  logger = new Logger(MeteringInterceptor.name);
-  scopeResolver;
-  /**
-   * Capture (or record) the handler's usage after it resolves; release the guard's
-   * hold on a handler error.
-   *
-   * @param executionContext The request execution context.
-   * @param next The downstream handler.
-   * @returns The handler's result stream, unchanged in value.
-   */
-  intercept(executionContext, next) {
-    const targets = [executionContext.getHandler(), executionContext.getClass()];
-    const config = this.reflector.getAllAndOverride(METER_METADATA, targets);
-    if (config === void 0) return next.handle();
-    const request = executionContext.switchToHttp().getRequest();
-    const enrichment = request.aiTokens;
-    return next.handle().pipe(
-      mergeMap((result) => from(this.settle(executionContext, config, enrichment, result))),
-      catchError((error) => this.onError(enrichment, error))
-    );
-  }
-  /** Settle the handler's usage and set the cost headers; returns the untouched result. */
-  async settle(executionContext, config, enrichment, result) {
-    const usage = extractUsage(result, config);
-    const record = await this.capture(executionContext, config, enrichment, usage);
-    if (config.exposeHeaders === true) this.setHeaders(executionContext, record, enrichment);
-    return result;
-  }
-  /** Capture the guard's hold when present, else record enforcing post-hoc. */
-  async capture(executionContext, config, enrichment, usage) {
-    if (enrichment?.hold !== void 0) return this.metering.capture(enrichment.hold, usage, config.preset);
-    const context = await this.resolveContext(executionContext, config, enrichment);
-    return this.metering.record({
-      usage,
-      // Stryker disable next-line ConditionalExpression -- CE true: spreading { preset: undefined } is equivalent to {} because MeteringService checks preset !== undefined
-      ...config.preset !== void 0 ? { preset: config.preset } : {},
-      // Stryker disable next-line ConditionalExpression -- CE true: spreading { tags: undefined } is equivalent to {} because MeteringService checks tags !== undefined
-      context: { ...context, enforce: true, isSystemCost: config.isSystemCost ?? false, ...config.tags !== void 0 ? { tags: config.tags } : {} }
-    });
-  }
-  /** The metering context: the guard's enrichment, else the host `scopeResolver`. */
-  async resolveContext(executionContext, config, enrichment) {
-    if (enrichment !== void 0) return enrichment.context;
-    if (this.scopeResolver === void 0) {
-      throw new AiTokensException("AI_TOKENS_INVALID_CONFIG", void 0, { reason: "MeteringInterceptor requires options.scopeResolver when no BudgetGuard ran" });
-    }
-    const resolved = await this.scopeResolver(executionContext);
-    return { ...resolved, feature: config.feature, ...config.preset !== void 0 ? { preset: config.preset } : {} };
-  }
-  /** Release the guard's hold (if any) and rethrow the ORIGINAL handler error. */
-  onError(enrichment, error) {
-    if (enrichment?.hold === void 0) return throwError(() => error);
-    const holdId = enrichment.hold.id;
-    const released = this.metering.release(enrichment.hold, "handler threw").catch(() => {
-      this.logger.warn(`failed to release hold ${holdId} after a handler error; the reaper will reclaim it`);
-    });
-    return from(released).pipe(mergeMap(() => throwError(() => error)));
-  }
-  /** Set the three `x-ai-tokens-*` headers as decimal strings via the HTTP adapter. */
-  setHeaders(executionContext, record, enrichment) {
-    const response = executionContext.switchToHttp().getResponse();
-    writeHeader(response, "x-ai-tokens-cost", record.rawCostNanoUsd.toString());
-    writeHeader(response, "x-ai-tokens-billed-cost", record.billedCostNanoUsd.toString());
-    const remaining = minBudgetRemaining(enrichment);
-    if (remaining !== void 0) writeHeader(response, "x-ai-tokens-budget-remaining", remaining.toString());
-  }
-};
-MeteringInterceptor = __decorateClass([
-  Injectable(),
-  __decorateParam(2, Inject(BYMAX_AI_TOKENS_OPTIONS))
-], MeteringInterceptor);
-function extractUsage(result, config) {
-  const extract = config.extract ?? ((value) => typeof value === "object" && value !== null ? value.usage : void 0);
-  const usage = extract(result);
-  if (usage === void 0 || usage === null) {
-    throw new AiTokensException("AI_TOKENS_USAGE_MALFORMED", void 0, { reason: "the handler result carried no extractable usage" });
-  }
-  return usage;
-}
-function minBudgetRemaining(enrichment) {
-  let min;
-  for (const status of enrichment?.status ?? []) {
-    const remaining = status.remaining.nanoUsd;
-    if (remaining !== void 0 && (min === void 0 || remaining < min)) min = remaining;
-  }
-  return min;
-}
-function writeHeader(response, name, value) {
-  if (typeof response.setHeader === "function") response.setHeader(name, value);
-  else if (typeof response.header === "function") response.header(name, value);
-}
-var REAP_BATCH_SIZE = 100;
-var MS_PER_SECOND = 1e3;
-var HoldReaper = class {
-  /**
-   * @param ledger The ledger service (expired-hold scan + atomic void claim).
-   * @param metering The metering facade (shared hold-restoration path).
-   * @param options The resolved options carrying the hold TTL + sweep interval.
-   * @param now The injected clock (testability).
-   */
-  constructor(ledger, metering, options, now = () => /* @__PURE__ */ new Date()) {
-    this.ledger = ledger;
-    this.metering = metering;
-    this.options = options;
-    this.now = now;
-  }
-  ledger;
-  metering;
-  options;
-  now;
-  logger = new Logger(HoldReaper.name);
-  timer;
-  /** Start the periodic sweep on module boot (interval `unref()`'d so it never blocks exit). */
-  onApplicationBootstrap() {
-    const intervalMs = this.options.holds.reaperIntervalSeconds * MS_PER_SECOND;
-    this.timer = setInterval(() => void this.sweep(), intervalMs);
-    this.timer.unref();
-  }
-  /** Stop the sweep on shutdown (no open handles left for Jest). */
-  onApplicationShutdown() {
-    if (this.timer !== void 0) clearInterval(this.timer);
-    this.timer = void 0;
-  }
-  /**
-   * Reclaim one batch of expired pending holds. For each: win the atomic
-   * `pending → released` claim (a `null` result means another replica won — skip),
-   * then run the shared restoration + `hold.released` emission. A failure on one
-   * hold is logged and never aborts the batch (deterministic, idempotent, safe to
-   * run repeatedly).
-   */
-  async sweep() {
-    const cutoff = new Date(this.now().getTime() - this.options.holds.ttlSeconds * MS_PER_SECOND);
-    const expired = await this.ledger.findExpiredHolds(cutoff, REAP_BATCH_SIZE);
-    for (const record of expired) {
-      try {
-        const claimed = await this.ledger.transition(record.id, "pending", "released");
-        if (claimed === null) continue;
-        await this.metering.restoreReleasedHold(claimed, "expired", true);
-      } catch {
-        this.logger.warn(`failed to reap expired hold ${record.id}`);
-      }
-    }
-  }
-};
-HoldReaper = __decorateClass([
-  Injectable()
-], HoldReaper);
-
-// src/server/telemetry/otel-emitter.ts
-function buildGenAiAttributes(record) {
-  return {
-    "gen_ai.provider.name": record.provider,
-    "gen_ai.request.model": record.requestedModel ?? record.model,
-    "gen_ai.response.model": record.model,
-    "gen_ai.operation.name": record.operation,
-    "gen_ai.request.service_tier": record.serviceTier,
-    "gen_ai.usage.input_tokens": record.inputTokens,
-    "gen_ai.usage.output_tokens": record.outputTokens
-  };
-}
-var TelemetryEmitter = class {
-  /** @param sink The host telemetry sink, or `null` to disable telemetry. */
-  constructor(sink) {
-    this.sink = sink;
-  }
-  sink;
-  /**
-   * Record a usage measurement for a posted record (no-op without a sink).
-   *
-   * @param record The posted usage record.
-   */
-  recordUsage(record) {
-    if (this.sink === null) return;
-    this.sink.recordUsage(buildGenAiAttributes(record), record);
-  }
-  /**
-   * Record an operation duration for a posted record (no-op without a sink, or when
-   * the sink does not implement `recordDuration`).
-   *
-   * @param record The posted usage record.
-   * @param milliseconds The measured operation duration.
-   */
-  recordDuration(record, milliseconds) {
-    const sink = this.sink;
-    if (sink?.recordDuration === void 0) return;
-    sink.recordDuration(buildGenAiAttributes(record), milliseconds);
-  }
-};
-var IDENTITY = (text) => text;
-var ContentCapture = class _ContentCapture {
-  /** @param options The resolved content-sidecar settings (disabled by default). */
-  constructor(options) {
-    this.options = options;
-  }
-  options;
-  logger = new Logger(_ContentCapture.name);
-  /**
-   * Persist the masked prompt/completion to the content sidecar. A no-op when the
-   * feature is disabled or no text was supplied. Failures are logged (never the
-   * text) and never rethrown — content capture must not break metering.
-   *
-   * @param input The record id, tenant, and the host-supplied text.
-   */
-  async capture(input) {
-    if (!this.options.enabled) return;
-    if (input.prompt === void 0 && input.completion === void 0) return;
-    const { store, ttlSeconds } = this.options;
-    const mask = this.options.mask ?? IDENTITY;
-    try {
-      if (input.prompt !== void 0) {
-        await store.put({ usageRecordId: input.usageRecordId, tenantId: input.tenantId, role: "prompt", text: mask(input.prompt), ttlSeconds });
-      }
-      if (input.completion !== void 0) {
-        await store.put({ usageRecordId: input.usageRecordId, tenantId: input.tenantId, role: "completion", text: mask(input.completion), ttlSeconds });
-      }
-    } catch {
-      this.logger.error(`failed to write content sidecar for record ${input.usageRecordId}`);
-    }
-  }
-};
-var NO_OP_CONTENT_CAPTURE = new ContentCapture({ enabled: false });
 
 // src/server/utils/model-id.ts
 function normalizeModelId(id) {
@@ -2246,8 +2012,82 @@ function numberOf(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 
+// src/server/telemetry/otel-emitter.ts
+function buildGenAiAttributes(record) {
+  return {
+    "gen_ai.provider.name": record.provider,
+    "gen_ai.request.model": record.requestedModel ?? record.model,
+    "gen_ai.response.model": record.model,
+    "gen_ai.operation.name": record.operation,
+    "gen_ai.request.service_tier": record.serviceTier,
+    "gen_ai.usage.input_tokens": record.inputTokens,
+    "gen_ai.usage.output_tokens": record.outputTokens
+  };
+}
+var TelemetryEmitter = class {
+  /** @param sink The host telemetry sink, or `null` to disable telemetry. */
+  constructor(sink) {
+    this.sink = sink;
+  }
+  sink;
+  /**
+   * Record a usage measurement for a posted record (no-op without a sink).
+   *
+   * @param record The posted usage record.
+   */
+  recordUsage(record) {
+    if (this.sink === null) return;
+    this.sink.recordUsage(buildGenAiAttributes(record), record);
+  }
+  /**
+   * Record an operation duration for a posted record (no-op without a sink, or when
+   * the sink does not implement `recordDuration`).
+   *
+   * @param record The posted usage record.
+   * @param milliseconds The measured operation duration.
+   */
+  recordDuration(record, milliseconds) {
+    const sink = this.sink;
+    if (sink?.recordDuration === void 0) return;
+    sink.recordDuration(buildGenAiAttributes(record), milliseconds);
+  }
+};
+
 // src/server/telemetry/no-op-telemetry.ts
 var NO_OP_TELEMETRY = new TelemetryEmitter(null);
+var IDENTITY = (text) => text;
+var ContentCapture = class _ContentCapture {
+  /** @param options The resolved content-sidecar settings (disabled by default). */
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  logger = new Logger(_ContentCapture.name);
+  /**
+   * Persist the masked prompt/completion to the content sidecar. A no-op when the
+   * feature is disabled or no text was supplied. Failures are logged (never the
+   * text) and never rethrown — content capture must not break metering.
+   *
+   * @param input The record id, tenant, and the host-supplied text.
+   */
+  async capture(input) {
+    if (!this.options.enabled) return;
+    if (input.prompt === void 0 && input.completion === void 0) return;
+    const { store, ttlSeconds } = this.options;
+    const mask = this.options.mask ?? IDENTITY;
+    try {
+      if (input.prompt !== void 0) {
+        await store.put({ usageRecordId: input.usageRecordId, tenantId: input.tenantId, role: "prompt", text: mask(input.prompt), ttlSeconds });
+      }
+      if (input.completion !== void 0) {
+        await store.put({ usageRecordId: input.usageRecordId, tenantId: input.tenantId, role: "completion", text: mask(input.completion), ttlSeconds });
+      }
+    } catch {
+      this.logger.error(`failed to write content sidecar for record ${input.usageRecordId}`);
+    }
+  }
+};
+var NO_OP_CONTENT_CAPTURE = new ContentCapture({ enabled: false });
 
 // src/server/services/hold-support.ts
 var UNSPECIFIED = "unspecified";
@@ -4114,6 +3954,170 @@ var exampleRecord = {
   updatedAt: /* @__PURE__ */ new Date(0)
 };
 
+// src/server/enforcement/metering.interceptor.ts
+var MeteringInterceptor = class {
+  /**
+   * @param reflector The NestJS reflector (`@Meter` metadata).
+   * @param metering The metering facade (capture/record).
+   * @param options The resolved options (fallback `scopeResolver` when no guard ran).
+   */
+  constructor(reflector, metering, options) {
+    this.reflector = reflector;
+    this.metering = metering;
+    this.scopeResolver = options.scopeResolver;
+  }
+  reflector;
+  metering;
+  logger = new Logger(MeteringInterceptor.name);
+  scopeResolver;
+  /**
+   * Capture (or record) the handler's usage after it resolves; release the guard's
+   * hold on a handler error.
+   *
+   * @param executionContext The request execution context.
+   * @param next The downstream handler.
+   * @returns The handler's result stream, unchanged in value.
+   */
+  intercept(executionContext, next) {
+    const targets = [executionContext.getHandler(), executionContext.getClass()];
+    const config = this.reflector.getAllAndOverride(METER_METADATA, targets);
+    if (config === void 0) return next.handle();
+    const request = executionContext.switchToHttp().getRequest();
+    const enrichment = request.aiTokens;
+    return next.handle().pipe(
+      mergeMap((result) => from(this.settle(executionContext, config, enrichment, result))),
+      catchError((error) => this.onError(enrichment, error))
+    );
+  }
+  /** Settle the handler's usage and set the cost headers; returns the untouched result. */
+  async settle(executionContext, config, enrichment, result) {
+    const usage = extractUsage(result, config);
+    const record = await this.capture(executionContext, config, enrichment, usage);
+    if (config.exposeHeaders === true) this.setHeaders(executionContext, record, enrichment);
+    return result;
+  }
+  /** Capture the guard's hold when present, else record enforcing post-hoc. */
+  async capture(executionContext, config, enrichment, usage) {
+    if (enrichment?.hold !== void 0) return this.metering.capture(enrichment.hold, usage, config.preset);
+    const context = await this.resolveContext(executionContext, config, enrichment);
+    return this.metering.record({
+      usage,
+      // Stryker disable next-line ConditionalExpression -- CE true: spreading { preset: undefined } is equivalent to {} because MeteringService checks preset !== undefined
+      ...config.preset !== void 0 ? { preset: config.preset } : {},
+      // Stryker disable next-line ConditionalExpression -- CE true: spreading { tags: undefined } is equivalent to {} because MeteringService checks tags !== undefined
+      context: { ...context, enforce: true, isSystemCost: config.isSystemCost ?? false, ...config.tags !== void 0 ? { tags: config.tags } : {} }
+    });
+  }
+  /** The metering context: the guard's enrichment, else the host `scopeResolver`. */
+  async resolveContext(executionContext, config, enrichment) {
+    if (enrichment !== void 0) return enrichment.context;
+    if (this.scopeResolver === void 0) {
+      throw new AiTokensException("AI_TOKENS_INVALID_CONFIG", void 0, { reason: "MeteringInterceptor requires options.scopeResolver when no BudgetGuard ran" });
+    }
+    const resolved = await this.scopeResolver(executionContext);
+    return { ...resolved, feature: config.feature, ...config.preset !== void 0 ? { preset: config.preset } : {} };
+  }
+  /** Release the guard's hold (if any) and rethrow the ORIGINAL handler error. */
+  onError(enrichment, error) {
+    if (enrichment?.hold === void 0) return throwError(() => error);
+    const holdId = enrichment.hold.id;
+    const released = this.metering.release(enrichment.hold, "handler threw").catch(() => {
+      this.logger.warn(`failed to release hold ${holdId} after a handler error; the reaper will reclaim it`);
+    });
+    return from(released).pipe(mergeMap(() => throwError(() => error)));
+  }
+  /** Set the three `x-ai-tokens-*` headers as decimal strings via the HTTP adapter. */
+  setHeaders(executionContext, record, enrichment) {
+    const response = executionContext.switchToHttp().getResponse();
+    writeHeader(response, "x-ai-tokens-cost", record.rawCostNanoUsd.toString());
+    writeHeader(response, "x-ai-tokens-billed-cost", record.billedCostNanoUsd.toString());
+    const remaining = minBudgetRemaining(enrichment);
+    if (remaining !== void 0) writeHeader(response, "x-ai-tokens-budget-remaining", remaining.toString());
+  }
+};
+MeteringInterceptor = __decorateClass([
+  Injectable(),
+  __decorateParam(0, Inject(Reflector)),
+  __decorateParam(1, Inject(MeteringService)),
+  __decorateParam(2, Inject(BYMAX_AI_TOKENS_OPTIONS))
+], MeteringInterceptor);
+function extractUsage(result, config) {
+  const extract = config.extract ?? ((value) => typeof value === "object" && value !== null ? value.usage : void 0);
+  const usage = extract(result);
+  if (usage === void 0 || usage === null) {
+    throw new AiTokensException("AI_TOKENS_USAGE_MALFORMED", void 0, { reason: "the handler result carried no extractable usage" });
+  }
+  return usage;
+}
+function minBudgetRemaining(enrichment) {
+  let min;
+  for (const status of enrichment?.status ?? []) {
+    const remaining = status.remaining.nanoUsd;
+    if (remaining !== void 0 && (min === void 0 || remaining < min)) min = remaining;
+  }
+  return min;
+}
+function writeHeader(response, name, value) {
+  if (typeof response.setHeader === "function") response.setHeader(name, value);
+  else if (typeof response.header === "function") response.header(name, value);
+}
+var REAP_BATCH_SIZE = 100;
+var MS_PER_SECOND = 1e3;
+var HoldReaper = class {
+  /**
+   * @param ledger The ledger service (expired-hold scan + atomic void claim).
+   * @param metering The metering facade (shared hold-restoration path).
+   * @param options The resolved options carrying the hold TTL + sweep interval.
+   * @param now The injected clock (testability).
+   */
+  constructor(ledger, metering, options, now = () => /* @__PURE__ */ new Date()) {
+    this.ledger = ledger;
+    this.metering = metering;
+    this.options = options;
+    this.now = now;
+  }
+  ledger;
+  metering;
+  options;
+  now;
+  logger = new Logger(HoldReaper.name);
+  timer;
+  /** Start the periodic sweep on module boot (interval `unref()`'d so it never blocks exit). */
+  onApplicationBootstrap() {
+    const intervalMs = this.options.holds.reaperIntervalSeconds * MS_PER_SECOND;
+    this.timer = setInterval(() => void this.sweep(), intervalMs);
+    this.timer.unref();
+  }
+  /** Stop the sweep on shutdown (no open handles left for Jest). */
+  onApplicationShutdown() {
+    if (this.timer !== void 0) clearInterval(this.timer);
+    this.timer = void 0;
+  }
+  /**
+   * Reclaim one batch of expired pending holds. For each: win the atomic
+   * `pending → released` claim (a `null` result means another replica won — skip),
+   * then run the shared restoration + `hold.released` emission. A failure on one
+   * hold is logged and never aborts the batch (deterministic, idempotent, safe to
+   * run repeatedly).
+   */
+  async sweep() {
+    const cutoff = new Date(this.now().getTime() - this.options.holds.ttlSeconds * MS_PER_SECOND);
+    const expired = await this.ledger.findExpiredHolds(cutoff, REAP_BATCH_SIZE);
+    for (const record of expired) {
+      try {
+        const claimed = await this.ledger.transition(record.id, "pending", "released");
+        if (claimed === null) continue;
+        await this.metering.restoreReleasedHold(claimed, "expired", true);
+      } catch {
+        this.logger.warn(`failed to reap expired hold ${record.id}`);
+      }
+    }
+  }
+};
+HoldReaper = __decorateClass([
+  Injectable()
+], HoldReaper);
+
 // src/server/bymax-ai-tokens.module.ts
 var CORE_TOKENS = [
   BYMAX_AI_TOKENS_OPTIONS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-ai-tokens",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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",
@@ -73,6 +73,31 @@
     },
     "./package.json": "./package.json"
   },
+  "scripts": {
+    "build": "pnpm clean && tsup",
+    "check:exports": "attw --pack . --profile strict",
+    "check:published": "node scripts/check-published-surface.mjs",
+    "check:runtime": "node scripts/check-consumer-runtime.mjs",
+    "clean": "node -e \"const {rmSync}=require('node:fs');for(const d of ['dist','coverage'])rmSync(d,{recursive:true,force:true})\"",
+    "db:generate": "prisma generate",
+    "docs:check": "node scripts/check-jsdoc.mjs && tsc --noEmit -p tsconfig.e2e.json",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "mutation": "stryker run",
+    "mutation:dry-run": "stryker run --dryRunOnly",
+    "mutation:incremental": "stryker run --incremental",
+    "prepare": "prisma generate",
+    "prepublishOnly": "pnpm clean && pnpm typecheck && pnpm lint && pnpm test:cov:all && pnpm build && pnpm size && pnpm check:published",
+    "release": "npm publish --provenance --access public",
+    "size": "node scripts/check-size.mjs",
+    "test": "jest",
+    "test:all": "pnpm test && pnpm test:e2e",
+    "test:cov": "jest --coverage",
+    "test:cov:all": "jest --config jest.coverage.config.ts --coverage",
+    "test:e2e": "jest --config jest.e2e.config.ts",
+    "test:watch": "jest --watch",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.server.json"
+  },
   "dependencies": {},
   "peerDependencies": {
     "@nestjs/common": "^11.0.16",
@@ -163,6 +188,7 @@
     "budget",
     "markup"
   ],
+  "packageManager": "pnpm@11.20.0",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -189,28 +215,5 @@
         "./dist/redis/index.d.cts"
       ]
     }
-  },
-  "scripts": {
-    "build": "pnpm clean && tsup",
-    "check:exports": "attw --pack . --profile strict",
-    "check:published": "node scripts/check-published-surface.mjs",
-    "check:runtime": "node scripts/check-consumer-runtime.mjs",
-    "clean": "node -e \"const {rmSync}=require('node:fs');for(const d of ['dist','coverage'])rmSync(d,{recursive:true,force:true})\"",
-    "db:generate": "prisma generate",
-    "docs:check": "node scripts/check-jsdoc.mjs && tsc --noEmit -p tsconfig.e2e.json",
-    "lint": "eslint src",
-    "lint:fix": "eslint src --fix",
-    "mutation": "stryker run",
-    "mutation:dry-run": "stryker run --dryRunOnly",
-    "mutation:incremental": "stryker run --incremental",
-    "release": "npm publish --provenance --access public",
-    "size": "node scripts/check-size.mjs",
-    "test": "jest",
-    "test:all": "pnpm test && pnpm test:e2e",
-    "test:cov": "jest --coverage",
-    "test:cov:all": "jest --config jest.coverage.config.ts --coverage",
-    "test:e2e": "jest --config jest.e2e.config.ts",
-    "test:watch": "jest --watch",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.server.json"
   }
-}
+}