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

package/CHANGELOG.md

@@ -8,6 +8,34 @@ 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
@@ -135,4 +163,5 @@ have regressed from. They are kept because the reasoning is worth having.
 
 [1.0.0]: https://github.com/bymaxone/nest-ai-tokens/releases/tag/v1.0.0
 [1.0.1]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.0.0...v1.0.1
-[Unreleased]: https://github.com/bymaxone/nest-ai-tokens/compare/v1.0.1...HEAD
+[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/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.1",
+  "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",
@@ -171,26 +171,6 @@
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.65.0"
   },
-  "pnpm": {
-    "overrides": {
-      "brace-expansion@1": "^1.1.17",
-      "brace-expansion@2": "^2.1.3",
-      "brace-expansion@5": "^5.0.8",
-      "esbuild": "0.28.1",
-      "fast-uri": "^3.1.4",
-      "multer": "2.2.0",
-      "protobufjs": "^7.6.5",
-      "qs": "6.15.2",
-      "undici": "^8.9.0",
-      "uuid": "11.1.1"
-    },
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "@prisma/client",
-      "@prisma/engines",
-      "prisma"
-    ]
-  },
   "keywords": [
     "nestjs",
     "ai",
@@ -208,7 +188,7 @@
     "budget",
     "markup"
   ],
-  "packageManager": "pnpm@10.8.1",
+  "packageManager": "pnpm@11.20.0",
   "engines": {
     "node": ">=24.0.0"
   },