@bymax-one/nest-ai-tokens 1.0.0

package/dist/server/index.mjs

@@ -0,0 +1,4354 @@
+import { HttpStatus, Injectable, Inject, Global, Module, HttpException, SetMetadata, Logger } from '@nestjs/common';
+import { ModuleRef, Reflector } from '@nestjs/core';
+import { randomUUID } from 'crypto';
+import { mergeMap, from, throwError } from 'rxjs';
+import { catchError } from 'rxjs/operators';
+import { Readable } from 'stream';
+
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (decorator(result)) || result;
+  return result;
+};
+var __decorateParam = (index, decorator) => (target, key) => decorator(target, key, index);
+
+// src/server/bymax-ai-tokens.constants.ts
+var BYMAX_AI_TOKENS_OPTIONS = /* @__PURE__ */ Symbol("BYMAX_AI_TOKENS_OPTIONS");
+var BYMAX_AI_TOKENS_LEDGER_STORE = /* @__PURE__ */ Symbol("BYMAX_AI_TOKENS_LEDGER_STORE");
+var BYMAX_AI_TOKENS_PRICING_STORE = /* @__PURE__ */ Symbol("BYMAX_AI_TOKENS_PRICING_STORE");
+var BYMAX_AI_TOKENS_WALLET_STORE = /* @__PURE__ */ Symbol("BYMAX_AI_TOKENS_WALLET_STORE");
+var BYMAX_AI_TOKENS_BUDGET_STORE = /* @__PURE__ */ Symbol("BYMAX_AI_TOKENS_BUDGET_STORE");
+var BYMAX_AI_TOKENS_BUDGET_COUNTER = /* @__PURE__ */ Symbol("BYMAX_AI_TOKENS_BUDGET_COUNTER");
+var BYMAX_AI_TOKENS_TOKENIZER = /* @__PURE__ */ Symbol("BYMAX_AI_TOKENS_TOKENIZER");
+var BYMAX_AI_TOKENS_TELEMETRY = /* @__PURE__ */ Symbol("BYMAX_AI_TOKENS_TELEMETRY");
+var BYMAX_AI_TOKENS_EVENT_SINK = /* @__PURE__ */ Symbol("BYMAX_AI_TOKENS_EVENT_SINK");
+var BYMAX_AI_TOKENS_CONTENT_STORE = /* @__PURE__ */ Symbol("BYMAX_AI_TOKENS_CONTENT_STORE");
+var BYMAX_AI_TOKENS_LOGGER = /* @__PURE__ */ Symbol("BYMAX_AI_TOKENS_LOGGER");
+
+// src/shared/constants/provider-ids.constants.ts
+var PROVIDER_IDS = [
+  "openai",
+  "azure-openai",
+  "anthropic",
+  "gemini",
+  "vertex",
+  "mistral",
+  "bedrock",
+  "openrouter",
+  "deepseek",
+  "xai",
+  "groq"
+];
+
+// src/shared/constants/operations.constants.ts
+var AI_OPERATIONS = [
+  "chat",
+  "responses",
+  "embeddings",
+  "image",
+  "video",
+  "audio",
+  "rerank",
+  "moderation"
+];
+
+// src/shared/constants/service-tiers.constants.ts
+var SERVICE_TIERS = ["standard", "batch", "flex", "priority"];
+
+// src/shared/constants/token-categories.constants.ts
+var TOKEN_CATEGORIES = [
+  "input",
+  "output",
+  "cacheRead",
+  "cacheWrite5m",
+  "cacheWrite1h",
+  "reasoning",
+  "audioIn",
+  "audioOut",
+  "imageIn",
+  "imageOut"
+];
+
+// src/shared/constants/wallet-entry-types.constants.ts
+var WALLET_ENTRY_TYPES = ["grant", "debit", "refund", "adjustment", "expiry"];
+
+// src/shared/constants/error-codes.constants.ts
+var AI_TOKENS_ERROR_CODES = {
+  AI_TOKENS_NOT_CONFIGURED: "AI_TOKENS_NOT_CONFIGURED",
+  AI_TOKENS_INVALID_CONFIG: "AI_TOKENS_INVALID_CONFIG",
+  AI_TOKENS_UNKNOWN_PROVIDER: "AI_TOKENS_UNKNOWN_PROVIDER",
+  AI_TOKENS_USAGE_MALFORMED: "AI_TOKENS_USAGE_MALFORMED",
+  AI_TOKENS_PRICE_NOT_FOUND: "AI_TOKENS_PRICE_NOT_FOUND",
+  AI_TOKENS_FX_REQUIRED: "AI_TOKENS_FX_REQUIRED",
+  AI_TOKENS_BUDGET_EXCEEDED: "AI_TOKENS_BUDGET_EXCEEDED",
+  AI_TOKENS_QUOTA_EXCEEDED: "AI_TOKENS_QUOTA_EXCEEDED",
+  AI_TOKENS_INSUFFICIENT_CREDITS: "AI_TOKENS_INSUFFICIENT_CREDITS",
+  AI_TOKENS_HOLD_NOT_FOUND: "AI_TOKENS_HOLD_NOT_FOUND",
+  AI_TOKENS_HOLD_EXPIRED: "AI_TOKENS_HOLD_EXPIRED",
+  AI_TOKENS_HOLD_ALREADY_SETTLED: "AI_TOKENS_HOLD_ALREADY_SETTLED",
+  AI_TOKENS_IDEMPOTENCY_CONFLICT: "AI_TOKENS_IDEMPOTENCY_CONFLICT",
+  AI_TOKENS_STREAM_USAGE_MISSING: "AI_TOKENS_STREAM_USAGE_MISSING",
+  AI_TOKENS_STORE_ERROR: "AI_TOKENS_STORE_ERROR"
+};
+
+// src/shared/constants/ledger-fields.constants.ts
+var AMOUNT_FIELDS = [
+  "inputTokens",
+  "outputTokens",
+  "cacheReadTokens",
+  "cacheWrite5mTokens",
+  "cacheWrite1hTokens",
+  "reasoningTokens",
+  "audioInTokens",
+  "audioOutTokens",
+  "imageInTokens",
+  "imageOutTokens",
+  "totalTokens",
+  "rawCostNanoUsd",
+  "surchargeNanoUsd",
+  "billedCostNanoUsd"
+];
+var SETTLEMENT_FIELDS = [
+  ...AMOUNT_FIELDS,
+  "priceVersionId",
+  "priceMissing",
+  "markupMultiplier"
+];
+var RELEASE_FIELDS = ["correlationId", "requestId"];
+var REVERSAL_LINKAGE_FIELD = "reversedByRecordId";
+var SETTLEMENT_PATCH_KEYS = /* @__PURE__ */ new Set([...SETTLEMENT_FIELDS, REVERSAL_LINKAGE_FIELD]);
+var RELEASE_FIELD_SET = new Set(RELEASE_FIELDS);
+function isLegalLedgerTransition(from2, to) {
+  if (from2 === "pending") return to === "posted" || to === "released";
+  return from2 === "posted" && to === "reversed";
+}
+function isLegalTransitionPatchKey(from2, to, key) {
+  if (from2 === "pending" && to === "posted") return SETTLEMENT_PATCH_KEYS.has(key);
+  if (from2 === "pending" && to === "released") return RELEASE_FIELD_SET.has(key);
+  if (from2 === "posted" && to === "reversed") return key === REVERSAL_LINKAGE_FIELD;
+  return false;
+}
+
+// src/shared/normalizers/usage-fields.ts
+function asObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+function asArray(value) {
+  return Array.isArray(value) ? value : void 0;
+}
+function num(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function requireNum(value, provider, field) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  throw new Error(`${provider}: missing or invalid numeric field "${field}"`);
+}
+function str(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function knownServiceTier(value) {
+  const candidate = str(value);
+  return candidate !== void 0 && SERVICE_TIERS.includes(candidate) ? candidate : void 0;
+}
+function openAiServiceTier(value) {
+  const candidate = str(value);
+  return knownServiceTier(candidate === "default" ? "standard" : candidate);
+}
+function toolUseCounts(value) {
+  const source = asObject(value);
+  if (source === void 0) return void 0;
+  const counts = {};
+  for (const [key, raw] of Object.entries(source)) {
+    if (typeof raw === "number" && Number.isFinite(raw)) counts[key] = raw;
+  }
+  return Object.keys(counts).length > 0 ? counts : void 0;
+}
+function buildUsage(draft) {
+  const usage = {
+    provider: draft.provider,
+    model: draft.model,
+    operation: draft.operation,
+    inputTokens: draft.inputTokens,
+    outputTokens: draft.outputTokens,
+    cacheReadTokens: draft.cacheReadTokens ?? 0,
+    cacheWrite5mTokens: draft.cacheWrite5mTokens ?? 0,
+    cacheWrite1hTokens: draft.cacheWrite1hTokens ?? 0,
+    reasoningTokens: draft.reasoningTokens ?? 0,
+    audioInTokens: draft.audioInTokens ?? 0,
+    audioOutTokens: draft.audioOutTokens ?? 0,
+    imageInTokens: draft.imageInTokens ?? 0,
+    imageOutTokens: draft.imageOutTokens ?? 0
+  };
+  if (draft.serviceTier !== void 0) usage.serviceTier = draft.serviceTier;
+  if (draft.serverToolUse !== void 0) usage.serverToolUse = draft.serverToolUse;
+  if (draft.providerReportedCostNanoUsd !== void 0) {
+    usage.providerReportedCostNanoUsd = draft.providerReportedCostNanoUsd;
+  }
+  if (draft.raw !== void 0) usage.raw = draft.raw;
+  return usage;
+}
+function readResponse(raw, provider, usageKey = "usage") {
+  const response = asObject(raw) ?? {};
+  const usage = asObject(response[usageKey]);
+  if (usage === void 0) throw new Error(`${provider}: missing "${usageKey}" object`);
+  return { response, usage };
+}
+
+// src/shared/normalizers/openai-chat.normalizer.ts
+function normalizeOpenAiChatUsage(raw) {
+  const { response, usage } = readResponse(raw, "openai-chat");
+  const promptTokens = requireNum(usage.prompt_tokens, "openai-chat", "usage.prompt_tokens");
+  const completionTokens = requireNum(usage.completion_tokens, "openai-chat", "usage.completion_tokens");
+  const promptDetails = asObject(usage.prompt_tokens_details);
+  const completionDetails = asObject(usage.completion_tokens_details);
+  const cacheReadTokens = num(promptDetails?.cached_tokens);
+  const audioInTokens = num(promptDetails?.audio_tokens);
+  const reasoningTokens = num(completionDetails?.reasoning_tokens);
+  const audioOutTokens = num(completionDetails?.audio_tokens);
+  const serviceTier = openAiServiceTier(response.service_tier);
+  return buildUsage({
+    provider: "openai",
+    model: str(response.model) ?? "",
+    operation: "chat",
+    inputTokens: promptTokens - cacheReadTokens - audioInTokens,
+    outputTokens: completionTokens - reasoningTokens,
+    cacheReadTokens,
+    reasoningTokens,
+    audioInTokens,
+    audioOutTokens,
+    serviceTier,
+    raw: usage
+  });
+}
+
+// src/shared/normalizers/openai-responses.normalizer.ts
+function normalizeOpenAiResponsesUsage(raw) {
+  const { response, usage } = readResponse(raw, "openai-responses");
+  const inputTokensTotal = requireNum(usage.input_tokens, "openai-responses", "usage.input_tokens");
+  const outputTokensTotal = requireNum(usage.output_tokens, "openai-responses", "usage.output_tokens");
+  const inputDetails = asObject(usage.input_tokens_details);
+  const outputDetails = asObject(usage.output_tokens_details);
+  const cacheReadTokens = num(inputDetails?.cached_tokens);
+  const audioInTokens = num(inputDetails?.audio_tokens);
+  const reasoningTokens = num(outputDetails?.reasoning_tokens);
+  const audioOutTokens = num(outputDetails?.audio_tokens);
+  const serviceTier = openAiServiceTier(response.service_tier);
+  return buildUsage({
+    provider: "openai",
+    model: str(response.model) ?? "",
+    operation: "responses",
+    inputTokens: inputTokensTotal - cacheReadTokens - audioInTokens,
+    outputTokens: outputTokensTotal - reasoningTokens,
+    cacheReadTokens,
+    reasoningTokens,
+    audioInTokens,
+    audioOutTokens,
+    serviceTier,
+    raw: usage
+  });
+}
+
+// src/shared/normalizers/openai-compatible.normalizer.ts
+function normalizeOpenAiCompatibleUsage(raw) {
+  const { response, usage } = readResponse(raw, "openai-compatible");
+  const promptTokens = requireNum(usage.prompt_tokens, "openai-compatible", "usage.prompt_tokens");
+  const completionTokens = requireNum(usage.completion_tokens, "openai-compatible", "usage.completion_tokens");
+  const promptDetails = asObject(usage.prompt_tokens_details);
+  const completionDetails = asObject(usage.completion_tokens_details);
+  const cacheReadTokens = num(usage.prompt_cache_hit_tokens) + num(promptDetails?.cached_tokens);
+  const reasoningTokens = num(completionDetails?.reasoning_tokens);
+  const serviceTier = openAiServiceTier(response.service_tier);
+  return buildUsage({
+    provider: "",
+    model: str(response.model) ?? "",
+    operation: "chat",
+    inputTokens: promptTokens - cacheReadTokens,
+    outputTokens: completionTokens - reasoningTokens,
+    cacheReadTokens,
+    reasoningTokens,
+    serviceTier,
+    raw: usage
+  });
+}
+
+// src/shared/normalizers/anthropic.normalizer.ts
+function normalizeAnthropicUsage(raw) {
+  const { response, usage } = readResponse(raw, "anthropic");
+  const inputTokens = requireNum(usage.input_tokens, "anthropic", "usage.input_tokens");
+  const outputTokens = requireNum(usage.output_tokens, "anthropic", "usage.output_tokens");
+  const cacheReadTokens = num(usage.cache_read_input_tokens);
+  const cacheCreation = asObject(usage.cache_creation);
+  const cacheWrite5mTokens = cacheCreation ? num(cacheCreation.ephemeral_5m_input_tokens) : num(usage.cache_creation_input_tokens);
+  const cacheWrite1hTokens = cacheCreation ? num(cacheCreation.ephemeral_1h_input_tokens) : 0;
+  return buildUsage({
+    provider: "anthropic",
+    model: str(response.model) ?? "",
+    operation: "chat",
+    inputTokens,
+    outputTokens,
+    cacheReadTokens,
+    cacheWrite5mTokens,
+    cacheWrite1hTokens,
+    serviceTier: knownServiceTier(usage.service_tier),
+    serverToolUse: toolUseCounts(usage.server_tool_use),
+    raw: usage
+  });
+}
+
+// src/shared/normalizers/gemini.normalizer.ts
+function normalizeGeminiUsage(raw) {
+  const { response, usage } = readResponse(raw, "gemini", "usageMetadata");
+  const promptTokenCount = requireNum(usage.promptTokenCount, "gemini", "usageMetadata.promptTokenCount");
+  const candidatesTokenCount = num(usage.candidatesTokenCount);
+  const cacheReadTokens = num(usage.cachedContentTokenCount);
+  const reasoningTokens = num(usage.thoughtsTokenCount);
+  const toolUseInputTokens = num(usage.toolUsePromptTokenCount);
+  return buildUsage({
+    provider: "gemini",
+    model: str(response.modelVersion) ?? str(response.model) ?? "",
+    operation: "chat",
+    inputTokens: promptTokenCount - cacheReadTokens + toolUseInputTokens,
+    outputTokens: candidatesTokenCount,
+    cacheReadTokens,
+    reasoningTokens,
+    raw: usage
+  });
+}
+
+// src/shared/normalizers/bedrock-converse.normalizer.ts
+function splitCacheWrite(usage) {
+  const details = asArray(usage.cacheDetails);
+  if (details === void 0) {
+    return { cacheWrite5mTokens: num(usage.cacheWriteInputTokens), cacheWrite1hTokens: 0 };
+  }
+  let cacheWrite5mTokens = 0;
+  let cacheWrite1hTokens = 0;
+  for (const item of details) {
+    const entry = asObject(item);
+    if (entry === void 0) continue;
+    const count = num(entry.cacheWriteInputTokens);
+    if (str(entry.ttl) === "1h") cacheWrite1hTokens += count;
+    else cacheWrite5mTokens += count;
+  }
+  return { cacheWrite5mTokens, cacheWrite1hTokens };
+}
+function normalizeBedrockConverseUsage(raw) {
+  const { response, usage } = readResponse(raw, "bedrock-converse");
+  const inputTokens = requireNum(usage.inputTokens, "bedrock-converse", "usage.inputTokens");
+  const outputTokens = requireNum(usage.outputTokens, "bedrock-converse", "usage.outputTokens");
+  const { cacheWrite5mTokens, cacheWrite1hTokens } = splitCacheWrite(usage);
+  return buildUsage({
+    provider: "bedrock",
+    model: str(response.model) ?? "",
+    operation: "chat",
+    inputTokens,
+    outputTokens,
+    cacheReadTokens: num(usage.cacheReadInputTokens),
+    cacheWrite5mTokens,
+    cacheWrite1hTokens,
+    raw: usage
+  });
+}
+
+// src/shared/normalizers/mistral.normalizer.ts
+function normalizeMistralUsage(raw) {
+  const { response, usage } = readResponse(raw, "mistral");
+  return buildUsage({
+    provider: "mistral",
+    model: str(response.model) ?? "",
+    operation: "chat",
+    // Stryker disable next-line StringLiteral -- provider and field names in error messages are internal diagnostics
+    inputTokens: requireNum(usage.prompt_tokens, "mistral", "usage.prompt_tokens"),
+    // Stryker disable next-line StringLiteral -- provider and field names in error messages are internal diagnostics
+    outputTokens: requireNum(usage.completion_tokens, "mistral", "usage.completion_tokens"),
+    raw: usage
+  });
+}
+
+// src/shared/pricing/money.ts
+var NANO_PER_USD = 1000000000n;
+var DEFAULT_DISPLAY_DECIMALS = 6;
+function perMillion(tokens, ratePerMillionNano) {
+  return BigInt(tokens) * ratePerMillionNano / 1000000n;
+}
+function floatUsdToNanoUsd(usd) {
+  if (!Number.isFinite(usd)) {
+    throw new RangeError(`floatUsdToNanoUsd: expected a finite number, received ${String(usd)}`);
+  }
+  const sign = usd < 0 ? -1n : 1n;
+  const abs = Math.abs(usd);
+  const wholeDollars = Math.floor(abs);
+  const fractionalDollars = abs - wholeDollars;
+  const wholeNano = BigInt(wholeDollars) * NANO_PER_USD;
+  const fractionalNano = BigInt(Math.round(fractionalDollars * 1e9));
+  return sign * (wholeNano + fractionalNano);
+}
+function formatNanoUsd(nanoUsd, opts) {
+  const decimals = opts?.decimals ?? DEFAULT_DISPLAY_DECIMALS;
+  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 9) {
+    throw new RangeError(`formatNanoUsd: decimals must be an integer in [0, 9], received ${String(decimals)}`);
+  }
+  const currency = opts?.currency ?? "USD";
+  const converted = opts?.fxRateNano == null ? nanoUsd : nanoUsd * opts.fxRateNano / NANO_PER_USD;
+  const negative = converted < 0n;
+  const magnitude = negative ? -converted : converted;
+  const nanoPerDisplayUnit = 10n ** BigInt(9 - decimals);
+  const displayUnits = (magnitude + nanoPerDisplayUnit / 2n) / nanoPerDisplayUnit;
+  const scale = 10n ** BigInt(decimals);
+  const integerPart = displayUnits / scale;
+  const fractionalPart = displayUnits % scale;
+  const fractionalText = decimals > 0 ? `.${fractionalPart.toString().padStart(decimals, "0")}` : "";
+  const body = `${integerPart.toString()}${fractionalText}`;
+  const signText = negative ? "-" : "";
+  return currency === "USD" ? `${signText}$${body}` : `${signText}${body} ${currency}`;
+}
+
+// src/shared/normalizers/openrouter.normalizer.ts
+function normalizeOpenRouterUsage(raw) {
+  const { response, usage } = readResponse(raw, "openrouter");
+  const promptTokens = requireNum(usage.prompt_tokens, "openrouter", "usage.prompt_tokens");
+  const completionTokens = requireNum(usage.completion_tokens, "openrouter", "usage.completion_tokens");
+  const promptDetails = asObject(usage.prompt_tokens_details);
+  const completionDetails = asObject(usage.completion_tokens_details);
+  const cacheReadTokens = num(promptDetails?.cached_tokens);
+  const cacheWrite5mTokens = num(promptDetails?.cache_write_tokens);
+  const reasoningTokens = num(completionDetails?.reasoning_tokens);
+  const cost = usage.cost;
+  const providerReportedCostNanoUsd = typeof cost === "number" && Number.isFinite(cost) ? floatUsdToNanoUsd(cost) : void 0;
+  return buildUsage({
+    provider: "openrouter",
+    model: str(response.model) ?? "",
+    operation: "chat",
+    inputTokens: promptTokens - cacheReadTokens - cacheWrite5mTokens,
+    outputTokens: completionTokens - reasoningTokens,
+    cacheReadTokens,
+    cacheWrite5mTokens,
+    reasoningTokens,
+    serviceTier: openAiServiceTier(response.service_tier),
+    providerReportedCostNanoUsd,
+    raw: usage
+  });
+}
+
+// src/shared/normalizers/vercel-ai-sdk.normalizer.ts
+function normalizeVercelAiSdkUsage(raw) {
+  const { response, usage } = readResponse(raw, "vercel-ai-sdk");
+  const inputTokensTotal = requireNum(usage.inputTokens, "vercel-ai-sdk", "usage.inputTokens");
+  const outputTokensTotal = requireNum(usage.outputTokens, "vercel-ai-sdk", "usage.outputTokens");
+  const inputDetails = asObject(usage.inputTokenDetails);
+  const outputDetails = asObject(usage.outputTokenDetails);
+  const cacheReadTokens = num(usage.cachedInputTokens) + num(inputDetails?.cacheReadTokens);
+  const cacheWrite5mTokens = num(inputDetails?.cacheWriteTokens);
+  const reasoningTokens = num(usage.reasoningTokens) + num(outputDetails?.reasoningTokens);
+  return buildUsage({
+    provider: "",
+    model: str(response.model) ?? "",
+    operation: "chat",
+    inputTokens: inputTokensTotal - cacheReadTokens - cacheWrite5mTokens,
+    outputTokens: outputTokensTotal - reasoningTokens,
+    cacheReadTokens,
+    cacheWrite5mTokens,
+    reasoningTokens,
+    raw: usage
+  });
+}
+
+// src/shared/pricing/compute-cost.ts
+function computeCostNanoUsd(usage, rate) {
+  const totalInput = usage.inputTokens + usage.cacheReadTokens + usage.cacheWrite5mTokens + usage.cacheWrite1hTokens;
+  const overTier = rate.tierThresholdTokens != null && totalInput > rate.tierThresholdTokens;
+  const inputRate = overTier ? rate.tierInputNanoUsdPerMillion ?? rate.inputNanoUsdPerMillion : rate.inputNanoUsdPerMillion;
+  const outputRate = overTier ? rate.tierOutputNanoUsdPerMillion ?? rate.outputNanoUsdPerMillion : rate.outputNanoUsdPerMillion;
+  const tokenNanoUsd = perMillion(usage.inputTokens, inputRate) + perMillion(usage.outputTokens, outputRate) + perMillion(usage.cacheReadTokens, rate.cacheReadNanoUsdPerMillion) + perMillion(usage.cacheWrite5mTokens, rate.cacheWrite5mNanoUsdPerMillion) + perMillion(usage.cacheWrite1hTokens, rate.cacheWrite1hNanoUsdPerMillion) + perMillion(usage.reasoningTokens, rate.reasoningNanoUsdPerMillion) + perMillion(usage.audioInTokens, rate.audioInNanoUsdPerMillion) + perMillion(usage.audioOutTokens, rate.audioOutNanoUsdPerMillion) + perMillion(usage.imageInTokens, rate.imageInNanoUsdPerMillion) + perMillion(usage.imageOutTokens, rate.imageOutNanoUsdPerMillion);
+  let surchargeNanoUsd = 0n;
+  for (const [unit, count] of Object.entries({ ...usage.serverToolUse })) {
+    const unitRate = rate.unitRates?.[unit];
+    if (unitRate != null) surchargeNanoUsd += BigInt(count) * unitRate;
+  }
+  return { totalNanoUsd: tokenNanoUsd + surchargeNanoUsd, tokenNanoUsd, surchargeNanoUsd };
+}
+
+// src/shared/pricing/apply-markup.ts
+var MARKUP_SCALE = 10000n;
+function assertValidMultiplier(multiplier) {
+  if (!Number.isFinite(multiplier) || multiplier <= 0) {
+    throw new RangeError(`applyMarkup: multiplier must be finite and > 0, received ${String(multiplier)}`);
+  }
+}
+function resolveMultiplier4dp(multiplier) {
+  assertValidMultiplier(multiplier);
+  return Math.round(multiplier * 1e4) / 1e4;
+}
+function applyMarkup(rawCostNanoUsd, multiplier) {
+  assertValidMultiplier(multiplier);
+  return rawCostNanoUsd * BigInt(Math.round(multiplier * 1e4)) / MARKUP_SCALE;
+}
+
+// src/shared/utils/sha256.ts
+var K_WORDS = [
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+];
+var INITIAL_HASH = [
+  1779033703,
+  3144134277,
+  1013904242,
+  2773480762,
+  1359893119,
+  2600822924,
+  528734635,
+  1541459225
+];
+var kView = new DataView(new ArrayBuffer(64 * 4));
+K_WORDS.forEach((value, index) => {
+  kView.setUint32(index * 4, value);
+});
+function rotr(x, n) {
+  return (x >>> n | x << 32 - n) >>> 0;
+}
+function expandSchedule(w) {
+  for (let i = 16; i < 64; i++) {
+    const w15 = w.getUint32((i - 15) * 4);
+    const w2 = w.getUint32((i - 2) * 4);
+    const s0 = rotr(w15, 7) ^ rotr(w15, 18) ^ w15 >>> 3;
+    const s1 = rotr(w2, 17) ^ rotr(w2, 19) ^ w2 >>> 10;
+    w.setUint32(i * 4, w.getUint32((i - 16) * 4) + s0 + w.getUint32((i - 7) * 4) + s1 >>> 0);
+  }
+}
+function compressBlock(h, w) {
+  let a = h.getUint32(0);
+  let b = h.getUint32(4);
+  let c = h.getUint32(8);
+  let d = h.getUint32(12);
+  let e = h.getUint32(16);
+  let f = h.getUint32(20);
+  let g = h.getUint32(24);
+  let hh = h.getUint32(28);
+  for (let i = 0; i < 64; i++) {
+    const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+    const ch = e & f ^ ~e & g;
+    const t1 = hh + s1 + ch + kView.getUint32(i * 4) + w.getUint32(i * 4) >>> 0;
+    const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+    const maj = a & b ^ a & c ^ b & c;
+    const t2 = s0 + maj >>> 0;
+    hh = g;
+    g = f;
+    f = e;
+    e = d + t1 >>> 0;
+    d = c;
+    c = b;
+    b = a;
+    a = t1 + t2 >>> 0;
+  }
+  const next = [a, b, c, d, e, f, g, hh];
+  next.forEach((value, index) => {
+    h.setUint32(index * 4, h.getUint32(index * 4) + value >>> 0);
+  });
+}
+function sha256Hex(input) {
+  const message = new TextEncoder().encode(input);
+  const bitLength = message.length * 8;
+  const paddedLength = Math.ceil((message.length + 9) / 64) * 64;
+  const bytes = new Uint8Array(paddedLength);
+  bytes.set(message);
+  bytes[message.length] = 128;
+  const view = new DataView(bytes.buffer);
+  view.setUint32(paddedLength - 8, Math.floor(bitLength / 4294967296));
+  view.setUint32(paddedLength - 4, bitLength >>> 0);
+  const hView = new DataView(new ArrayBuffer(32));
+  INITIAL_HASH.forEach((value, index) => {
+    hView.setUint32(index * 4, value);
+  });
+  const wView = new DataView(new ArrayBuffer(64 * 4));
+  for (let offset = 0; offset < paddedLength; offset += 64) {
+    for (let i = 0; i < 16; i++) wView.setUint32(i * 4, view.getUint32(offset + i * 4));
+    expandSchedule(wView);
+    compressBlock(hView, wView);
+  }
+  let hex = "";
+  for (let i = 0; i < 8; i++) hex += hView.getUint32(i * 4).toString(16).padStart(8, "0");
+  return hex;
+}
+
+// src/shared/utils/idempotency.ts
+function canonicalize(value) {
+  if (value === null || value === void 0) return "null";
+  if (typeof value === "bigint") return JSON.stringify(`${value.toString()}n`);
+  if (typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+  if (typeof value === "number") return Number.isFinite(value) ? String(value) : "null";
+  if (value instanceof Date) return JSON.stringify(value.toISOString());
+  if (Array.isArray(value)) {
+    return `[${value.map((element) => canonicalize(element)).join(",")}]`;
+  }
+  if (typeof value === "object") {
+    const record = value;
+    const members = Object.keys(record).filter((key) => record[key] !== void 0).sort().map((key) => `${JSON.stringify(key)}:${canonicalize(record[key])}`);
+    return `{${members.join(",")}}`;
+  }
+  return "null";
+}
+function deriveIdempotencyKey(payload) {
+  return sha256Hex(canonicalize(payload));
+}
+
+// src/server/errors/ai-tokens-error-messages.ts
+var AI_TOKENS_ERROR_MESSAGES = {
+  AI_TOKENS_NOT_CONFIGURED: "The AI tokens module was invoked before its asynchronous configuration finished initializing.",
+  AI_TOKENS_INVALID_CONFIG: "The AI tokens module configuration is invalid; check markup, limits, currency/fx, and store port methods.",
+  AI_TOKENS_UNKNOWN_PROVIDER: "Raw usage was provided without a preset or normalizer and is not already a NormalizedUsage.",
+  AI_TOKENS_USAGE_MALFORMED: "The provider usage payload is missing required token fields.",
+  AI_TOKENS_PRICE_NOT_FOUND: "No effective-dated price was found for the requested model, operation, and service tier.",
+  AI_TOKENS_FX_REQUIRED: "A non-USD presentation currency requires an fx resolver, which is not configured.",
+  AI_TOKENS_BUDGET_EXCEEDED: "A hard spend budget blocks this call.",
+  AI_TOKENS_QUOTA_EXCEEDED: "A hard token or operation-count quota blocks this call.",
+  AI_TOKENS_INSUFFICIENT_CREDITS: "The wallet balance, including any overdraft, is below the required amount.",
+  AI_TOKENS_HOLD_NOT_FOUND: "The referenced hold does not exist for this tenant and scope.",
+  AI_TOKENS_HOLD_EXPIRED: "The referenced hold expired and was swept; retry via record().",
+  AI_TOKENS_HOLD_ALREADY_SETTLED: "The referenced hold was already released and cannot be captured.",
+  AI_TOKENS_IDEMPOTENCY_CONFLICT: "The idempotency key was reused with a different payload, or the record was already reversed.",
+  AI_TOKENS_STREAM_USAGE_MISSING: "The stream ended without provider usage and no tokenizer fallback was available.",
+  AI_TOKENS_STORE_ERROR: "The persistence adapter raised an unexpected error."
+};
+var AI_TOKENS_ERROR_STATUS = {
+  AI_TOKENS_NOT_CONFIGURED: HttpStatus.SERVICE_UNAVAILABLE,
+  AI_TOKENS_INVALID_CONFIG: HttpStatus.INTERNAL_SERVER_ERROR,
+  AI_TOKENS_UNKNOWN_PROVIDER: HttpStatus.BAD_REQUEST,
+  AI_TOKENS_USAGE_MALFORMED: HttpStatus.UNPROCESSABLE_ENTITY,
+  AI_TOKENS_PRICE_NOT_FOUND: HttpStatus.UNPROCESSABLE_ENTITY,
+  AI_TOKENS_FX_REQUIRED: HttpStatus.INTERNAL_SERVER_ERROR,
+  AI_TOKENS_BUDGET_EXCEEDED: HttpStatus.PAYMENT_REQUIRED,
+  AI_TOKENS_QUOTA_EXCEEDED: HttpStatus.TOO_MANY_REQUESTS,
+  AI_TOKENS_INSUFFICIENT_CREDITS: HttpStatus.PAYMENT_REQUIRED,
+  AI_TOKENS_HOLD_NOT_FOUND: HttpStatus.NOT_FOUND,
+  AI_TOKENS_HOLD_EXPIRED: HttpStatus.GONE,
+  AI_TOKENS_HOLD_ALREADY_SETTLED: HttpStatus.CONFLICT,
+  AI_TOKENS_IDEMPOTENCY_CONFLICT: HttpStatus.CONFLICT,
+  AI_TOKENS_STREAM_USAGE_MISSING: HttpStatus.UNPROCESSABLE_ENTITY,
+  AI_TOKENS_STORE_ERROR: HttpStatus.BAD_GATEWAY
+};
+
+// src/server/errors/ai-tokens-exception.ts
+var AiTokensException = class extends HttpException {
+  /**
+   * @param code The error code.
+   * @param statusCode The HTTP status; defaults to the code's mapped status.
+   * @param details Optional structured context (never includes prompt/response text).
+   */
+  constructor(code, statusCode = AI_TOKENS_ERROR_STATUS[code], details) {
+    super({ error: { code, message: AI_TOKENS_ERROR_MESSAGES[code], details } }, statusCode);
+  }
+};
+
+// src/server/config/validate-options.ts
+var LEDGER_METHODS = [
+  "append",
+  "transition",
+  "findByIdempotencyKey",
+  "findById",
+  "findExpiredHolds",
+  "query",
+  "sumCost",
+  "lastHash"
+];
+var PRICING_METHODS = ["resolveRate", "upsertPrice", "getPriceHistory", "listModels"];
+var WALLET_METHODS = [
+  "getWallet",
+  "appendEntry",
+  "conditionalDebit",
+  "openGrants",
+  "listEntries",
+  "reconcile"
+];
+var BUDGET_METHODS = [
+  "upsert",
+  "remove",
+  "findBudgetById",
+  "findMatching",
+  "conditionalConsume",
+  "adjustWindow",
+  "getWindow",
+  "setWindowStart"
+];
+function invalidConfig(reason) {
+  return new AiTokensException("AI_TOKENS_INVALID_CONFIG", void 0, { reason });
+}
+function firstMissingMethod(store, methods) {
+  const record = store;
+  return methods.find((method) => typeof record[method] !== "function");
+}
+function validateStorePorts(options) {
+  const store = options.store;
+  if (store === void 0 || store === null) throw invalidConfig("options.store is required");
+  const missingLedger = firstMissingMethod(options.store, LEDGER_METHODS);
+  if (missingLedger !== void 0) {
+    throw invalidConfig(`store is missing the required ledger method "${missingLedger}"`);
+  }
+  const missingPricing = firstMissingMethod(options.store, PRICING_METHODS);
+  if (missingPricing !== void 0) {
+    throw invalidConfig(`store is missing the required pricing method "${missingPricing}"`);
+  }
+}
+function validateFeaturePorts(options) {
+  if (options.wallets !== void 0) {
+    const missing = firstMissingMethod(options.store, WALLET_METHODS);
+    if (missing !== void 0) throw invalidConfig(`wallets enabled but store is missing "${missing}"`);
+  }
+  if (options.budgets !== void 0) {
+    const missing = firstMissingMethod(options.store, BUDGET_METHODS);
+    if (missing !== void 0) throw invalidConfig(`budgets enabled but store is missing "${missing}"`);
+  }
+}
+function validateCurrency(options) {
+  if (options.currency !== void 0 && options.currency !== "USD" && options.fx === void 0) {
+    throw new AiTokensException("AI_TOKENS_FX_REQUIRED", void 0, { currency: options.currency });
+  }
+}
+function validateMarkup(markup) {
+  if (markup === void 0) return;
+  if (typeof markup === "number") {
+    try {
+      resolveMultiplier4dp(markup);
+    } catch {
+      throw invalidConfig(`markup must be a finite number greater than 0, received ${String(markup)}`);
+    }
+    return;
+  }
+  if (typeof markup.resolve !== "function") {
+    throw invalidConfig("markup policy must implement a resolve() method");
+  }
+}
+function validateBudgetThresholds(options) {
+  const thresholds = options.budgets?.alertThresholds;
+  if (thresholds === void 0) return;
+  for (const threshold of thresholds) {
+    if (!(threshold > 0 && threshold <= 1)) {
+      throw invalidConfig(`budget alert thresholds must be within (0, 1], received ${String(threshold)}`);
+    }
+  }
+}
+function validateHolds(options) {
+  const holds = options.holds;
+  if (holds === void 0) return;
+  if (holds.ttlSeconds !== void 0 && holds.ttlSeconds <= 0) {
+    throw invalidConfig("holds.ttlSeconds must be greater than 0");
+  }
+  if (holds.reaperIntervalSeconds !== void 0 && holds.reaperIntervalSeconds <= 0) {
+    throw invalidConfig("holds.reaperIntervalSeconds must be greater than 0");
+  }
+}
+function validatePricing(options) {
+  const cacheTtlMs = options.pricing?.cacheTtlMs;
+  if (cacheTtlMs === void 0) return;
+  if (!Number.isInteger(cacheTtlMs) || cacheTtlMs <= 0) {
+    throw invalidConfig(
+      // Stryker disable next-line StringLiteral -- error reason template is internal diagnostics
+      `pricing.cacheTtlMs must be a positive integer number of milliseconds, received ${String(cacheTtlMs)}`
+    );
+  }
+}
+function validateWallets(options) {
+  const wallets = options.wallets;
+  if (wallets === void 0) return;
+  if (wallets.creditRateNanoUsd !== void 0 && wallets.creditRateNanoUsd <= 0n) {
+    throw invalidConfig("wallets.creditRateNanoUsd must be greater than 0");
+  }
+  if (wallets.overdraftNanoUsd !== void 0 && wallets.overdraftNanoUsd < 0n) {
+    throw invalidConfig("wallets.overdraftNanoUsd must not be negative");
+  }
+}
+function validateOptions(options) {
+  validateStorePorts(options);
+  validateFeaturePorts(options);
+  validateCurrency(options);
+  validateMarkup(options.markup);
+  validateBudgetThresholds(options);
+  validateHolds(options);
+  validateWallets(options);
+  validatePricing(options);
+}
+
+// src/server/config/default-options.constants.ts
+var DEFAULT_AI_TOKENS_OPTIONS = {
+  ratingMode: "rate-table",
+  currency: "USD",
+  markup: 1,
+  pricing: { seedFromSnapshot: true, strict: true, cacheTtlMs: 3e5 },
+  wallets: { creditRateNanoUsd: 1000000000n, overdraftNanoUsd: 0n, burnOrder: "expiry" },
+  budgets: { defaultPolicy: "block", alertThresholds: [0.8, 1], failClosed: true },
+  holds: { ttlSeconds: 3600, reaperIntervalSeconds: 300 },
+  ledger: { hashChain: false },
+  events: { emitter: true },
+  telemetry: { metrics: true },
+  reporting: { maxExportRows: 1e6 },
+  content: { ttlSeconds: 604800 }
+};
+
+// src/server/config/apply-defaults.ts
+function resolveMarkup(markup) {
+  if (markup === void 0) return DEFAULT_AI_TOKENS_OPTIONS.markup;
+  if (typeof markup === "number") return resolveMultiplier4dp(markup);
+  return markup;
+}
+function resolvePricing(pricing) {
+  return {
+    seedFromSnapshot: pricing?.seedFromSnapshot ?? DEFAULT_AI_TOKENS_OPTIONS.pricing.seedFromSnapshot,
+    strict: pricing?.strict ?? DEFAULT_AI_TOKENS_OPTIONS.pricing.strict,
+    cacheTtlMs: pricing?.cacheTtlMs ?? DEFAULT_AI_TOKENS_OPTIONS.pricing.cacheTtlMs,
+    modelAliases: pricing?.modelAliases ?? {}
+  };
+}
+function resolveWallets(wallets) {
+  if (wallets === void 0) return { enabled: false };
+  return {
+    enabled: true,
+    creditRateNanoUsd: wallets.creditRateNanoUsd ?? DEFAULT_AI_TOKENS_OPTIONS.wallets.creditRateNanoUsd,
+    overdraftNanoUsd: wallets.overdraftNanoUsd ?? DEFAULT_AI_TOKENS_OPTIONS.wallets.overdraftNanoUsd,
+    burnOrder: wallets.burnOrder ?? DEFAULT_AI_TOKENS_OPTIONS.wallets.burnOrder
+  };
+}
+function resolveBudgets(budgets) {
+  if (budgets === void 0) return { enabled: false };
+  return {
+    enabled: true,
+    defaultPolicy: budgets.defaultPolicy ?? DEFAULT_AI_TOKENS_OPTIONS.budgets.defaultPolicy,
+    alertThresholds: budgets.alertThresholds ?? DEFAULT_AI_TOKENS_OPTIONS.budgets.alertThresholds,
+    failClosed: budgets.failClosed ?? DEFAULT_AI_TOKENS_OPTIONS.budgets.failClosed,
+    counter: budgets.counter,
+    onThrottle: budgets.onThrottle
+  };
+}
+function resolveTelemetry(telemetry) {
+  if (telemetry?.sink === void 0) return { enabled: false };
+  return { enabled: true, sink: telemetry.sink, metrics: telemetry.metrics ?? DEFAULT_AI_TOKENS_OPTIONS.telemetry.metrics };
+}
+function resolveContent(content) {
+  if (content === void 0) return { enabled: false };
+  return {
+    enabled: true,
+    store: content.store,
+    mask: content.mask,
+    ttlSeconds: content.ttlSeconds ?? DEFAULT_AI_TOKENS_OPTIONS.content.ttlSeconds
+  };
+}
+function resolveEvents(events) {
+  return { emitter: events?.emitter ?? DEFAULT_AI_TOKENS_OPTIONS.events.emitter, sink: events?.sink };
+}
+function resolveHolds(holds) {
+  return {
+    ttlSeconds: holds?.ttlSeconds ?? DEFAULT_AI_TOKENS_OPTIONS.holds.ttlSeconds,
+    reaperIntervalSeconds: holds?.reaperIntervalSeconds ?? DEFAULT_AI_TOKENS_OPTIONS.holds.reaperIntervalSeconds
+  };
+}
+function resolveLedger(ledger) {
+  return { hashChain: ledger?.hashChain ?? DEFAULT_AI_TOKENS_OPTIONS.ledger.hashChain };
+}
+function resolveReporting(reporting) {
+  return { maxExportRows: reporting?.maxExportRows ?? DEFAULT_AI_TOKENS_OPTIONS.reporting.maxExportRows };
+}
+function applyDefaults(options) {
+  return Object.freeze({
+    store: options.store,
+    scopeResolver: options.scopeResolver,
+    ratingMode: options.ratingMode ?? DEFAULT_AI_TOKENS_OPTIONS.ratingMode,
+    currency: options.currency ?? DEFAULT_AI_TOKENS_OPTIONS.currency,
+    fx: options.fx,
+    markup: resolveMarkup(options.markup),
+    pricing: resolvePricing(options.pricing),
+    wallets: resolveWallets(options.wallets),
+    budgets: resolveBudgets(options.budgets),
+    holds: resolveHolds(options.holds),
+    ledger: resolveLedger(options.ledger),
+    tokenizer: options.tokenizer,
+    events: resolveEvents(options.events),
+    telemetry: resolveTelemetry(options.telemetry),
+    reporting: resolveReporting(options.reporting),
+    content: resolveContent(options.content)
+  });
+}
+
+// src/server/utils/to-json-safe.ts
+function convert(value) {
+  if (typeof value === "bigint") return value.toString();
+  if (value instanceof Date) return new Date(value.getTime());
+  if (Array.isArray(value)) return value.map((element) => convert(element));
+  if (typeof value === "object" && value !== null) {
+    const output = {};
+    for (const [key, member] of Object.entries(value)) output[key] = convert(member);
+    return output;
+  }
+  return value;
+}
+function toJsonSafe(value) {
+  return convert(value);
+}
+
+// src/server/events/event-emitter.bridge.ts
+async function resolveEmitterChannel(moduleRef, enabled) {
+  if (!enabled) return null;
+  try {
+    const emitterModule = await import('@nestjs/event-emitter');
+    const emitter = moduleRef.get(emitterModule.EventEmitter2, { strict: false });
+    return {
+      emit: (type, envelope) => {
+        emitter.emit(type, envelope);
+      }
+    };
+  } catch {
+    return null;
+  }
+}
+
+// src/server/events/event-dispatcher.ts
+var EventDispatcher = class {
+  /**
+   * @param moduleRef The DI container, used to resolve the optional emitter peer.
+   * @param options The resolved options carrying the events configuration.
+   */
+  constructor(moduleRef, options) {
+    this.moduleRef = moduleRef;
+    this.options = options;
+  }
+  moduleRef;
+  options;
+  logger = new Logger(EventDispatcher.name);
+  emitterChannel = null;
+  /** Resolve the optional emitter channel once, at module init. */
+  async onModuleInit() {
+    this.emitterChannel = await resolveEmitterChannel(this.moduleRef, this.options.events.emitter);
+  }
+  /**
+   * Build and deliver one event on every configured channel. Never throws. The
+   * `data` payload is typed at each call site against the §12.2 catalog.
+   *
+   * @param type The event type.
+   * @param tenantId The owning tenant.
+   * @param scope The optional payer scope.
+   * @param data The event payload.
+   */
+  async emit(type, tenantId, scope, data) {
+    const envelope = {
+      id: randomUUID(),
+      type,
+      occurredAt: /* @__PURE__ */ new Date(),
+      tenantId,
+      ...scope !== void 0 ? { scope } : {},
+      data
+    };
+    this.emitViaEmitter(envelope);
+    await this.emitViaSink(envelope);
+  }
+  /**
+   * Emit an admin-plane audit event (§14.4). The tenant is read from `details`.
+   *
+   * @param action The admin action performed.
+   * @param details Structured context (never prompt/response text).
+   */
+  audit(action, details) {
+    const tenantId = typeof details.tenantId === "string" ? details.tenantId : "";
+    const data = { action, details };
+    return this.emit("ai_tokens.audit", tenantId, void 0, data);
+  }
+  /** Deliver on the in-process emitter channel (bigints intact); log a listener error. */
+  emitViaEmitter(envelope) {
+    try {
+      this.emitterChannel?.emit(envelope.type, envelope);
+    } catch {
+      this.logger.error(`event emitter listener failed for ${envelope.type} (${envelope.id})`);
+    }
+  }
+  /** Deliver on the programmatic sink (bigints as decimal strings); log a delivery failure. */
+  async emitViaSink(envelope) {
+    const { sink } = this.options.events;
+    if (sink === void 0) return;
+    try {
+      await sink.deliver(toJsonSafe(envelope));
+    } catch {
+      this.logger.error(`event sink delivery failed for ${envelope.type} (${envelope.id})`);
+    }
+  }
+};
+EventDispatcher = __decorateClass([
+  Injectable()
+], EventDispatcher);
+
+// src/server/events/event-hooks.ts
+function scopeOfWallet(ref) {
+  return { type: ref.ownerType, id: ref.ownerId };
+}
+function createMeteringEventHooks(dispatcher) {
+  return {
+    usageRecorded: (record) => {
+      const data = {
+        usageRecordId: record.id,
+        feature: record.feature,
+        provider: record.provider,
+        model: record.model,
+        serviceTier: record.serviceTier,
+        totalTokens: record.totalTokens,
+        rawCostNanoUsd: record.rawCostNanoUsd,
+        billedCostNanoUsd: record.billedCostNanoUsd,
+        enforced: record.enforced,
+        isSystemCost: record.isSystemCost
+      };
+      return dispatcher.emit("ai_tokens.usage.recorded", record.tenantId, record.scope, data);
+    },
+    priceMissing: (record) => {
+      const data = {
+        provider: record.provider,
+        model: record.model,
+        operation: record.operation,
+        serviceTier: record.serviceTier,
+        usageRecordId: record.id
+      };
+      return dispatcher.emit("ai_tokens.price.missing", record.tenantId, record.scope, data);
+    },
+    holdReleased: (record, reason, expired) => {
+      const data = { holdId: record.id, reason, expired };
+      return dispatcher.emit("ai_tokens.hold.released", record.tenantId, record.scope, data);
+    },
+    usageReversed: (original, reversalRecordId, reason) => {
+      const data = { usageRecordId: original.id, reversalRecordId, reason };
+      return dispatcher.emit("ai_tokens.usage.reversed", original.tenantId, original.scope, data);
+    },
+    audit: (action, details) => dispatcher.audit(action, details)
+  };
+}
+function createLedgerAuditHook(dispatcher) {
+  return (action, details) => {
+    void dispatcher.audit(action, details);
+  };
+}
+function createWalletEventHooks(dispatcher) {
+  return {
+    granted: (ref, data) => dispatcher.emit("ai_tokens.wallet.granted", ref.tenantId, scopeOfWallet(ref), data),
+    depleted: (ref, data) => dispatcher.emit("ai_tokens.wallet.depleted", ref.tenantId, scopeOfWallet(ref), data),
+    audit: (action, details) => dispatcher.audit(action, details)
+  };
+}
+function createBudgetEventHooks(dispatcher) {
+  return {
+    thresholdCrossed: (tenantId, scope, data) => dispatcher.emit("ai_tokens.budget.threshold_crossed", tenantId, scope, data),
+    exceeded: (tenantId, scope, data) => dispatcher.emit("ai_tokens.budget.exceeded", tenantId, scope, data),
+    projectedExceeded: (tenantId, scope, data) => dispatcher.emit("ai_tokens.budget.projected_exceeded", tenantId, scope, data),
+    audit: (action, details) => dispatcher.audit(action, details)
+  };
+}
+var METER_METADATA = "bymax:ai-tokens:meter";
+var REQUIRE_BUDGET_METADATA = "bymax:ai-tokens:require-budget";
+var AI_FEATURE_METADATA = "bymax:ai-tokens:ai-feature";
+function Meter(config) {
+  return SetMetadata(METER_METADATA, config);
+}
+function RequireBudget(config = {}) {
+  return SetMetadata(REQUIRE_BUDGET_METADATA, config);
+}
+function AiFeature(name) {
+  return SetMetadata(AI_FEATURE_METADATA, name);
+}
+
+// src/server/enforcement/budget.guard.ts
+var BudgetGuard = class {
+  /**
+   * @param budgets The budget service (status check).
+   * @param metering The metering facade (hold placement in `@RequireBudget.estimate` mode).
+   * @param reflector The NestJS reflector (decorator metadata).
+   * @param options The resolved options carrying the required `scopeResolver`.
+   * @throws {AiTokensException} `AI_TOKENS_INVALID_CONFIG` when `scopeResolver` is absent (fail-fast at init).
+   */
+  constructor(budgets, metering, reflector, options) {
+    this.budgets = budgets;
+    this.metering = metering;
+    this.reflector = reflector;
+    if (options.scopeResolver === void 0) {
+      throw new AiTokensException("AI_TOKENS_INVALID_CONFIG", void 0, {
+        // Stryker disable next-line StringLiteral -- error reason text is internal diagnostics
+        reason: "BudgetGuard requires options.scopeResolver to resolve the caller scope"
+      });
+    }
+    this.scopeResolver = options.scopeResolver;
+  }
+  budgets;
+  metering;
+  reflector;
+  scopeResolver;
+  /**
+   * Resolve the scope, merge decorator config, and block on any exhausted hard
+   * budget; otherwise enrich the request and allow.
+   *
+   * @param executionContext The request execution context.
+   * @returns `true` when the request may proceed.
+   * @throws {AiTokensException} `AI_TOKENS_BUDGET_EXCEEDED` / `AI_TOKENS_QUOTA_EXCEEDED` when a hard budget is exhausted (or an estimate shortfall from the placed hold).
+   */
+  async canActivate(executionContext) {
+    const context = await this.scopeResolver(executionContext);
+    const targets = [executionContext.getHandler(), executionContext.getClass()];
+    const meter = this.reflector.getAllAndOverride(METER_METADATA, targets);
+    const requireBudget = this.reflector.getAllAndOverride(REQUIRE_BUDGET_METADATA, targets);
+    const aiFeature = this.reflector.getAllAndOverride(AI_FEATURE_METADATA, targets);
+    const feature = requireBudget?.feature ?? meter?.feature ?? aiFeature ?? context.feature;
+    const statuses = await this.budgets.status(context.tenantId, context.scope);
+    for (const status of statuses) {
+      const error = exhaustedError(status, feature);
+      if (error !== null) throw error;
+    }
+    const meterContext = { ...context, feature, ...meter?.preset !== void 0 ? { preset: meter.preset } : {} };
+    const hold = requireBudget?.estimate !== void 0 ? await this.metering.hold(meterContext, requireBudget.estimate) : void 0;
+    const request = executionContext.switchToHttp().getRequest();
+    request.aiTokens = { status: statuses, context: meterContext, ...hold !== void 0 ? { hold } : {} };
+    return true;
+  }
+};
+BudgetGuard = __decorateClass([
+  Injectable(),
+  __decorateParam(3, Inject(BYMAX_AI_TOKENS_OPTIONS))
+], BudgetGuard);
+function featureMatches(features, feature) {
+  return features === void 0 || features.length === 0 || features.includes(feature);
+}
+function exhaustedError(status, feature) {
+  if (status.policy !== "block" || !featureMatches(status.features, feature)) return null;
+  if (status.limit.nanoUsd !== void 0 && status.spent.nanoUsd >= status.limit.nanoUsd) {
+    return new AiTokensException("AI_TOKENS_BUDGET_EXCEEDED", void 0, { budgetId: status.budgetId, dimension: "cost" });
+  }
+  if (status.limit.tokens !== void 0 && status.spent.tokens >= status.limit.tokens) {
+    return new AiTokensException("AI_TOKENS_QUOTA_EXCEEDED", void 0, { budgetId: status.budgetId, dimension: "tokens" });
+  }
+  if (status.limit.count !== void 0 && status.spent.count >= status.limit.count) {
+    return new AiTokensException("AI_TOKENS_QUOTA_EXCEEDED", void 0, { budgetId: status.budgetId, dimension: "count" });
+  }
+  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) {
+  return id.trim().replace(/^models\//, "").replace(/^(us|eu|apac|ap|sa|ca|me|af)\./i, "").replace(/-\d{4}-\d{2}-\d{2}$/, "").replace(/-\d{8}$/, "").toLowerCase();
+}
+
+// src/server/services/pricing.service.ts
+var SEED_EFFECTIVE_FROM = /* @__PURE__ */ new Date(0);
+var SEED_LOCK_KEY = "ai-tokens:model-prices";
+var PricingService = class {
+  /**
+   * @param options The resolved module options (pricing config lives here).
+   * @param store The pricing store port.
+   * @param now A clock returning epoch milliseconds; injected for testability.
+   */
+  constructor(options, store, now = () => Date.now()) {
+    this.options = options;
+    this.store = store;
+    this.now = now;
+  }
+  options;
+  store;
+  now;
+  cache = /* @__PURE__ */ new Map();
+  /** Seed the registry on boot when enabled. */
+  async onModuleInit() {
+    if (this.options.pricing.seedFromSnapshot) await this.seedFromSnapshot();
+  }
+  /**
+   * Resolve the price version in effect at `input.at`, applying the §6.6 chain.
+   *
+   * @param input The provider/model/operation/timestamp (+ optional tier/baseModel).
+   * @returns The matching price version, or `null` in non-strict mode on a miss.
+   * @throws {AiTokensException} `AI_TOKENS_PRICE_NOT_FOUND` on a miss in strict mode.
+   */
+  async resolveRate(input) {
+    const serviceTier = input.serviceTier ?? "standard";
+    const operation = input.operation === "responses" ? "chat" : input.operation;
+    const bucket = Math.floor(input.at.getTime() / this.options.pricing.cacheTtlMs);
+    const cacheKey = `${input.provider}|${input.model}|${input.baseModel ?? ""}|${operation}|${serviceTier}|${String(bucket)}`;
+    let resolved;
+    const cached = this.cache.get(cacheKey);
+    if (cached !== void 0 && this.now() < cached.expiresAt) {
+      resolved = cached.value;
+    } else {
+      resolved = await this.resolveUncached(input.provider, input.model, operation, serviceTier, input.at, input.baseModel);
+      this.cache.set(cacheKey, { value: resolved, expiresAt: this.now() + this.options.pricing.cacheTtlMs });
+    }
+    if (resolved === null && this.options.pricing.strict) {
+      throw new AiTokensException("AI_TOKENS_PRICE_NOT_FOUND", void 0, {
+        provider: input.provider,
+        model: input.model,
+        operation: input.operation,
+        serviceTier
+      });
+    }
+    return resolved;
+  }
+  /**
+   * Close the current open row and insert a new one; clears the resolution cache.
+   * ADMIN PLANE: this sets prices — the host MUST restrict it to privileged roles
+   * (§14.4) and should audit every call.
+   *
+   * @param input The new price version (rates default to `0n`, tier to `'standard'`).
+   * @returns The newly-inserted open price row.
+   */
+  async upsertPrice(input) {
+    const row = await this.store.upsertPrice(input);
+    this.cache.clear();
+    return row;
+  }
+  /** Full effective-dated history for a tuple. */
+  getPriceHistory(provider, model, operation, serviceTier) {
+    return this.store.getPriceHistory(provider, model, operation, serviceTier);
+  }
+  /** Seed the registry from the pinned snapshot; idempotent and advisory-locked. */
+  async seedFromSnapshot() {
+    const lockable = this.store;
+    if (typeof lockable.acquireSeedLock === "function") {
+      const acquired = await lockable.acquireSeedLock(SEED_LOCK_KEY);
+      if (!acquired) return;
+    }
+    const { MODEL_PRICES_SEED } = await import('@bymax-one/nest-ai-tokens/prices');
+    for (const row of MODEL_PRICES_SEED) {
+      await this.store.upsertPrice({ ...row, effectiveFrom: SEED_EFFECTIVE_FROM });
+    }
+    this.cache.clear();
+  }
+  /** The §6.6 six-step model-resolution chain (exact → baseModel → alias → normalized → prefix). */
+  async resolveUncached(provider, model, operation, serviceTier, at, baseModel) {
+    const exact = await this.store.resolveRate(provider, model, operation, serviceTier, at);
+    if (exact !== null) return exact;
+    if (baseModel !== void 0) {
+      const byBase = await this.store.resolveRate(provider, baseModel, operation, serviceTier, at);
+      if (byBase !== null) return byBase;
+    }
+    const alias = this.options.pricing.modelAliases[model];
+    if (alias !== void 0) {
+      const byAlias = await this.store.resolveRate(provider, alias, operation, serviceTier, at);
+      if (byAlias !== null) return byAlias;
+    }
+    const normalized = normalizeModelId(model);
+    if (normalized !== model) {
+      const byNormalized = await this.store.resolveRate(provider, normalized, operation, serviceTier, at);
+      if (byNormalized !== null) return byNormalized;
+    }
+    return this.resolveByLongestPrefix(provider, normalized, operation, serviceTier, at);
+  }
+  /** §6.6 step 5: longest-`startsWith` match among priced models for provider+operation+tier. */
+  async resolveByLongestPrefix(provider, normalizedModel, operation, serviceTier, at) {
+    const models = await this.store.listModels(provider);
+    let best;
+    let bestLength = -1;
+    for (const priced of models) {
+      if (priced.operation !== operation || priced.serviceTier !== serviceTier) continue;
+      const candidate = normalizeModelId(priced.model);
+      if (normalizedModel.startsWith(candidate) && candidate.length > bestLength) {
+        best = priced.model;
+        bestLength = candidate.length;
+      }
+    }
+    if (best === void 0) return null;
+    return this.store.resolveRate(provider, best, operation, serviceTier, at);
+  }
+};
+PricingService = __decorateClass([
+  Injectable()
+], PricingService);
+
+// src/server/utils/payload-hash.ts
+function computePayloadHash(record) {
+  return deriveIdempotencyKey({
+    scope: record.scope,
+    beneficiary: record.beneficiary,
+    requestedBy: record.requestedBy,
+    provider: record.provider,
+    model: record.model,
+    requestedModel: record.requestedModel,
+    operation: record.operation,
+    serviceTier: record.serviceTier,
+    feature: record.feature,
+    tags: record.tags,
+    inputTokens: record.inputTokens,
+    outputTokens: record.outputTokens,
+    cacheReadTokens: record.cacheReadTokens,
+    cacheWrite5mTokens: record.cacheWrite5mTokens,
+    cacheWrite1hTokens: record.cacheWrite1hTokens,
+    reasoningTokens: record.reasoningTokens,
+    audioInTokens: record.audioInTokens,
+    audioOutTokens: record.audioOutTokens,
+    imageInTokens: record.imageInTokens,
+    imageOutTokens: record.imageOutTokens,
+    totalTokens: record.totalTokens,
+    extraUnits: record.extraUnits,
+    priceVersionId: record.priceVersionId,
+    rawCostNanoUsd: record.rawCostNanoUsd,
+    surchargeNanoUsd: record.surchargeNanoUsd,
+    billedCostNanoUsd: record.billedCostNanoUsd,
+    markupMultiplier: record.markupMultiplier,
+    currency: record.currency,
+    priceMissing: record.priceMissing,
+    correlationId: record.correlationId,
+    requestId: record.requestId,
+    isSystemCost: record.isSystemCost,
+    systemCostCategory: record.systemCostCategory,
+    enforced: record.enforced,
+    reversesRecordId: record.reversesRecordId,
+    occurredAt: record.occurredAt
+  });
+}
+
+// src/server/utils/hash-chain.ts
+function chainHash(prevHash, record) {
+  return deriveIdempotencyKey({
+    // Stryker disable next-line StringLiteral -- empty-string fallback for null prevHash; tests only verify hash determinism and inequality, not the specific hash value for a genesis block
+    prevHash: prevHash ?? "",
+    id: record.id,
+    content: computePayloadHash(record)
+  });
+}
+
+// src/server/services/ledger-idempotency-conflict.ts
+function isLedgerIdempotencyConflict(error) {
+  if (typeof error !== "object" || error === null) return false;
+  return error.isAiTokensLedgerConflict === true;
+}
+
+// src/server/services/ledger.service.ts
+var BALANCE_STATUSES = ["posted", "reversed"];
+function sumTokens(counts) {
+  return counts.inputTokens + counts.outputTokens + counts.cacheReadTokens + counts.cacheWrite5mTokens + counts.cacheWrite1hTokens + counts.reasoningTokens + counts.audioInTokens + counts.audioOutTokens + counts.imageInTokens + counts.imageOutTokens;
+}
+var LedgerService = class {
+  /**
+   * @param store The append-only ledger store port.
+   * @param options The resolved options carrying the hash-chain flag (§8.6).
+   * @param audit The audit hook for chain verification; wired by the module.
+   */
+  constructor(store, options = { ledger: { hashChain: false } }, audit = () => void 0) {
+    this.store = store;
+    this.options = options;
+    this.audit = audit;
+  }
+  store;
+  options;
+  audit;
+  /** Whether the per-tenant tamper-evident hash chain is enabled (§8.6). */
+  get hashChainEnabled() {
+    return this.options.ledger.hashChain;
+  }
+  /**
+   * Append a record exactly once. The idempotency key is `ctxKey` when supplied
+   * — a content-derived key deduplicates retries (§8.4) — or a random UUID
+   * otherwise, in which case the record is still written once but retries are NOT
+   * deduplicated. A replay with a matching payload hash returns the stored record
+   * unchanged and writes nothing; the same key with a different payload throws
+   * `AI_TOKENS_IDEMPOTENCY_CONFLICT`.
+   *
+   * @param input The record content (without `idempotencyKey`/`totalTokens`).
+   * @param ctxKey The host-supplied idempotency key, when available.
+   * @returns The stored record (new or the existing one on a matching replay).
+   * @throws {AiTokensException} `AI_TOKENS_IDEMPOTENCY_CONFLICT` on a payload mismatch.
+   */
+  async append(input, ctxKey) {
+    const record = {
+      ...input,
+      idempotencyKey: ctxKey ?? randomUUID(),
+      totalTokens: sumTokens(input)
+    };
+    const payloadHash = computePayloadHash(record);
+    try {
+      return await this.store.append(record, payloadHash, this.hashChainEnabled);
+    } catch (error) {
+      if (isLedgerIdempotencyConflict(error)) {
+        throw new AiTokensException("AI_TOKENS_IDEMPOTENCY_CONFLICT", void 0, {
+          tenantId: error.tenantId,
+          idempotencyKey: error.idempotencyKey
+        });
+      }
+      throw error;
+    }
+  }
+  /**
+   * Look up a record by its per-tenant idempotency key.
+   *
+   * @param tenantId The owning tenant.
+   * @param key The idempotency key.
+   * @returns The record, or `null` when none exists.
+   */
+  findByIdempotencyKey(tenantId, key) {
+    return this.store.findByIdempotencyKey(tenantId, key);
+  }
+  /**
+   * Load one record by its global id. The metering lifecycle loads a pending hold
+   * by its id to settle or void it, and the orchestrated reversal loads the
+   * (now-annotated) original to restore its wallet/budget effects (§8.5).
+   *
+   * @param id The record id.
+   * @returns The record, or `null` when none exists.
+   */
+  findById(id) {
+    return this.store.findById(id);
+  }
+  /**
+   * Find pending holds whose TTL has elapsed — the reaper's sweep source (§8.3).
+   * Returns at most `limit` records so the reaper reclaims in bounded batches.
+   *
+   * @param olderThan The cutoff instant (records created at or before are expired).
+   * @param limit The maximum batch size.
+   * @returns The expired pending records.
+   */
+  findExpiredHolds(olderThan, limit) {
+    return this.store.findExpiredHolds(olderThan, limit);
+  }
+  /**
+   * Query records. When the filter omits `status`, it defaults to the
+   * balance-contributing statuses (`posted`, `reversed`) so callers see settled
+   * spend without special-casing (§8.3).
+   *
+   * @param filter The ledger query filter.
+   * @returns The matching records.
+   */
+  query(filter) {
+    return this.store.query(this.withBalanceStatuses(filter));
+  }
+  /**
+   * Aggregate cost/token totals. Defaults to `posted` + `reversed` records, so a
+   * reversed record and its compensating negation net to zero (§8.3).
+   *
+   * @param filter The ledger query filter.
+   * @returns The aggregate cost/token summary.
+   */
+  sumCost(filter) {
+    return this.store.sumCost(this.withBalanceStatuses(filter));
+  }
+  /** Default the status filter to the balance-contributing statuses when unset. */
+  withBalanceStatuses(filter) {
+    return filter.status === void 0 ? { ...filter, status: [...BALANCE_STATUSES] } : filter;
+  }
+  /**
+   * Move a record between lifecycle states (§8.3). Only three transitions are
+   * legal — `pending → posted` (settlement; only the settlement amount/cost fields
+   * may be patched), `pending → released` (void, no amount patch), and
+   * `posted → reversed` (annotation with `reversedByRecordId` only). An illegal
+   * `(from, to)` pair or an out-of-contract patch — including any attempt to mutate
+   * an immutable field such as `id`/`tenantId`/`idempotencyKey` — is a caller bug
+   * and throws `AI_TOKENS_IDEMPOTENCY_CONFLICT`. A legal
+   * transition whose record is NOT currently in `from` returns `null` — the atomic
+   * claim that lets exactly one reaper replica win an expired hold (§8.3).
+   *
+   * @param id The record id.
+   * @param from The required current status.
+   * @param to The target status.
+   * @param patch The fields to set alongside the status flip.
+   * @returns The updated record, or `null` on a from-state mismatch.
+   * @throws {AiTokensException} `AI_TOKENS_IDEMPOTENCY_CONFLICT` on an illegal transition/patch.
+   */
+  async transition(id, from2, to, patch) {
+    this.assertLegalTransition(from2, to, patch);
+    return this.store.transition(id, from2, to, patch, this.hashChainEnabled);
+  }
+  /**
+   * Verify a tenant's tamper-evident hash chain (§8.6). Walks its settled records
+   * (`posted` + `reversed`) in append order and recomputes each record's chain hash
+   * from its stored `prevHash` link, comparing it to the stored `hash`; reports the
+   * first record whose hash does not match (a post-hoc content modification).
+   * Recomputing from each record's own stored link makes verification independent
+   * of walk order and of any `from`/`to` window (the first in-range record keeps
+   * its real predecessor link). Always emits an `ai_tokens.audit` hook.
+   *
+   * @param tenantId The tenant whose chain to verify.
+   * @param from Optional inclusive lower bound on `occurredAt`.
+   * @param to Optional inclusive upper bound on `occurredAt`.
+   * @returns `{ valid: true }`, or `{ valid: false, brokenAtRecordId }`.
+   */
+  async verifyChain(tenantId, from2, to) {
+    const filter = { tenantId, status: ["posted", "reversed"] };
+    if (from2 !== void 0) filter.from = from2;
+    if (to !== void 0) filter.to = to;
+    const settled = await this.store.query(filter);
+    let result = { valid: true };
+    for (const record of settled) {
+      if (record.hash !== chainHash(record.prevHash ?? null, record)) {
+        result = { valid: false, brokenAtRecordId: record.id };
+        break;
+      }
+    }
+    const details = { tenantId, valid: result.valid };
+    if (!result.valid) details.brokenAtRecordId = result.brokenAtRecordId;
+    this.audit("ai_tokens.chain.verified", details);
+    return result;
+  }
+  /**
+   * Reverse a posted record with a compensating record (§8.5, ledger-only steps
+   * 1–2). Appends a `posted` record that exactly negates the original's token
+   * counts and costs (keyed `reverse:<id>`, so a retry is a clean replay), then
+   * annotates the original `posted → reversed`. Reversing a `pending`/`released`
+   * or already-`reversed` record is invalid and throws
+   * `AI_TOKENS_IDEMPOTENCY_CONFLICT`.
+   *
+   * ADMIN PLANE: reversal is a privileged mutation — the host MUST restrict it to
+   * privileged roles (§14.4). This ledger-only primitive does NOT touch wallets,
+   * budgets, counters, or events, and does not persist `reason` (the immutable
+   * record has no reason column); the orchestrating `MeteringService.reverse`
+   * surfaces `reason` on the `ai_tokens.usage.reversed` event.
+   *
+   * @param recordId The id of the posted record to reverse.
+   * @param reason The caller's stated reason (echoed in the conflict details when the record cannot be reversed).
+   * @returns The compensating record.
+   * @throws {AiTokensException} `AI_TOKENS_IDEMPOTENCY_CONFLICT` when the record is missing or not `posted`.
+   */
+  async reverse(recordId, reason) {
+    const original = await this.store.findById(recordId);
+    if (original?.status !== "posted") {
+      throw new AiTokensException("AI_TOKENS_IDEMPOTENCY_CONFLICT", void 0, {
+        // Stryker disable next-line StringLiteral -- error reason text is internal diagnostics
+        reason: original === null ? "record not found" : `cannot reverse a ${original.status} record`,
+        recordId,
+        requestedReason: reason
+      });
+    }
+    const compensating = await this.append(buildCompensatingRecord(original), `reverse:${recordId}`);
+    await this.transition(original.id, "posted", "reversed", { reversedByRecordId: compensating.id });
+    return compensating;
+  }
+  /**
+   * Enforce the legality table and per-transition patch contract (§8.3/§8.5) via
+   * the shared guard the store adapters also consume, so the service layer and the
+   * store boundary can never drift. Store-agnostic: it runs before the store
+   * applies the patch, so even a store that assigns patches broadly can never
+   * mutate an immutable field (`id`/`tenantId`/`idempotencyKey`) or write an
+   * out-of-contract column.
+   */
+  assertLegalTransition(from2, to, patch) {
+    if (!isLegalLedgerTransition(from2, to)) {
+      throw new AiTokensException("AI_TOKENS_IDEMPOTENCY_CONFLICT", void 0, {
+        // Stryker disable next-line StringLiteral -- error reason template is internal diagnostics
+        reason: `illegal transition ${from2} \u2192 ${to}`
+      });
+    }
+    if (patch === void 0) return;
+    for (const key of Object.keys(patch)) {
+      if (!isLegalTransitionPatchKey(from2, to, key)) {
+        throw new AiTokensException("AI_TOKENS_IDEMPOTENCY_CONFLICT", void 0, {
+          // Stryker disable next-line StringLiteral -- error reason template is internal diagnostics
+          reason: `${from2} \u2192 ${to} may not patch "${key}"`
+        });
+      }
+    }
+  }
+};
+LedgerService = __decorateClass([
+  Injectable()
+], LedgerService);
+function negateUnits(units) {
+  const negated = {};
+  for (const [unit, count] of Object.entries(units)) negated[unit] = -count;
+  return negated;
+}
+function buildCompensatingRecord(original) {
+  return {
+    tenantId: original.tenantId,
+    scope: original.scope,
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { beneficiary: undefined } is equivalent to {} because downstream consumers check !== undefined
+    ...original.beneficiary !== void 0 ? { beneficiary: original.beneficiary } : {},
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { requestedBy: undefined } is equivalent to {}
+    ...original.requestedBy !== void 0 ? { requestedBy: original.requestedBy } : {},
+    provider: original.provider,
+    model: original.model,
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { requestedModel: undefined } is equivalent to {}
+    ...original.requestedModel !== void 0 ? { requestedModel: original.requestedModel } : {},
+    operation: original.operation,
+    serviceTier: original.serviceTier,
+    feature: original.feature,
+    tags: original.tags,
+    inputTokens: -original.inputTokens,
+    outputTokens: -original.outputTokens,
+    cacheReadTokens: -original.cacheReadTokens,
+    cacheWrite5mTokens: -original.cacheWrite5mTokens,
+    cacheWrite1hTokens: -original.cacheWrite1hTokens,
+    reasoningTokens: -original.reasoningTokens,
+    audioInTokens: -original.audioInTokens,
+    audioOutTokens: -original.audioOutTokens,
+    imageInTokens: -original.imageInTokens,
+    imageOutTokens: -original.imageOutTokens,
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { extraUnits: undefined } is equivalent to {} because consumers check !== undefined
+    ...original.extraUnits !== void 0 ? { extraUnits: negateUnits(original.extraUnits) } : {},
+    priceVersionId: original.priceVersionId,
+    rawCostNanoUsd: -original.rawCostNanoUsd,
+    surchargeNanoUsd: -original.surchargeNanoUsd,
+    billedCostNanoUsd: -original.billedCostNanoUsd,
+    markupMultiplier: original.markupMultiplier,
+    currency: original.currency,
+    priceMissing: original.priceMissing,
+    status: "posted",
+    reversesRecordId: original.id,
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { correlationId: undefined } is equivalent to {}
+    ...original.correlationId !== void 0 ? { correlationId: original.correlationId } : {},
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { requestId: undefined } is equivalent to {}
+    ...original.requestId !== void 0 ? { requestId: original.requestId } : {},
+    isSystemCost: original.isSystemCost,
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { systemCostCategory: undefined } is equivalent to {}
+    ...original.systemCostCategory !== void 0 ? { systemCostCategory: original.systemCostCategory } : {},
+    enforced: original.enforced,
+    occurredAt: original.occurredAt
+  };
+}
+function buildResolvedMarkup(multiplier) {
+  return { multiplier, apply: (rawCostNanoUsd) => applyMarkup(rawCostNanoUsd, multiplier) };
+}
+var MarkupResolver = class {
+  /**
+   * @param options The resolved options carrying the markup (a 4-dp number or a policy).
+   */
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  /**
+   * Resolve the markup for one call. A static multiplier is returned as-is (it was
+   * validated and rounded to 4 dp at init); a policy is invoked with the full
+   * context, and its result is validated and rounded to 4 dp.
+   *
+   * @param context The scope/provider/model/operation/serviceTier/feature context.
+   * @returns The resolved 4-dp multiplier and a bound applier.
+   * @throws {AiTokensException} `AI_TOKENS_INVALID_CONFIG` when a policy throws or returns an invalid value.
+   */
+  async resolve(context) {
+    const { markup } = this.options;
+    if (typeof markup === "number") return buildResolvedMarkup(markup);
+    return buildResolvedMarkup(this.validate(await this.invokePolicy(markup, context)));
+  }
+  /** Invoke a host policy, wrapping any failure as an invalid-config error. */
+  async invokePolicy(policy, context) {
+    try {
+      return await policy.resolve(context);
+    } catch {
+      throw new AiTokensException("AI_TOKENS_INVALID_CONFIG", void 0, {
+        // Stryker disable next-line StringLiteral -- error reason text is internal diagnostics
+        reason: "markup policy failed to resolve a multiplier"
+      });
+    }
+  }
+  /** Validate + round a policy's multiplier to 4 dp, or fail the call. */
+  validate(raw) {
+    try {
+      return resolveMultiplier4dp(raw);
+    } catch {
+      throw new AiTokensException("AI_TOKENS_INVALID_CONFIG", void 0, {
+        // Stryker disable next-line StringLiteral -- error reason text is internal diagnostics
+        reason: "markup policy returned an invalid multiplier",
+        value: raw
+      });
+    }
+  }
+};
+MarkupResolver = __decorateClass([
+  Injectable()
+], MarkupResolver);
+
+// src/server/utils/scope-wallet.ts
+function scopeOwnsWallet(scope) {
+  return scope.type !== "key";
+}
+function scopeToWalletRef(tenantId, scope) {
+  return { tenantId, ownerType: scope.type, ownerId: scope.id };
+}
+function budgetDelta(delta) {
+  return { nanoUsd: delta.billedNanoUsd, tokens: delta.tokens, count: delta.count };
+}
+function contextOf(record) {
+  return { tenantId: record.tenantId, scope: record.scope, feature: record.feature };
+}
+var MeteringEffects = class _MeteringEffects {
+  /**
+   * @param wallets The wallet service, when the wallet feature is enabled.
+   * @param budgets The budget service, when the budget feature is enabled.
+   */
+  constructor(wallets, budgets) {
+    this.wallets = wallets;
+    this.budgets = budgets;
+  }
+  wallets;
+  budgets;
+  logger = new Logger(_MeteringEffects.name);
+  /**
+   * The wallet leg for a payer scope, or `null` when there is nothing to move:
+   * wallets disabled, a `'key'` scope (spends its owner's wallet), or a
+   * non-billable amount (`≤ 0` for a debit/refund, `= 0` for a signed settlement).
+   */
+  legFor(tenantId, scope, amount, signed) {
+    if (this.wallets === void 0 || !scopeOwnsWallet(scope)) return null;
+    if (signed ? amount === 0n : amount <= 0n) return null;
+    return { wallets: this.wallets, ref: scopeToWalletRef(tenantId, scope) };
+  }
+  /**
+   * Reserve a hold: consume the budget window/counter, then debit the wallet — the
+   * §11.2 ordering (cheapest to roll back first). A wallet shortfall compensates the
+   * budget consumption before rethrowing.
+   *
+   * @param context The metering context (payer scope, feature).
+   * @param delta The estimated reservation.
+   * @param ledgerKey The stable key deriving the wallet debit idempotency key.
+   * @throws {AiTokensException} The dimension's budget/quota/credits error on a shortfall (prior steps compensated).
+   */
+  async reserveHold(context, delta, ledgerKey) {
+    if (this.budgets !== void 0) await this.budgets.consume(context, budgetDelta(delta));
+    const leg = this.legFor(context.tenantId, context.scope, delta.billedNanoUsd, false);
+    if (leg === null) return;
+    try {
+      await leg.wallets.debit(leg.ref, { amountNanoUsd: delta.billedNanoUsd, idempotencyKey: `hold:${ledgerKey}`, reason: "auth-hold reservation" });
+    } catch (error) {
+      if (this.budgets !== void 0) await this.budgets.release(context, budgetDelta(delta));
+      throw error;
+    }
+  }
+  /**
+   * Compensate a hold whose pending ledger insert failed: refund the wallet debit
+   * and release the budget consumption. Best-effort — failures are logged so the
+   * original insert error surfaces unmasked.
+   *
+   * @param context The metering context.
+   * @param delta The reservation to unwind.
+   * @param ledgerKey The stable key deriving the wallet rollback idempotency key.
+   */
+  async compensateHold(context, delta, ledgerKey) {
+    const leg = this.legFor(context.tenantId, context.scope, delta.billedNanoUsd, false);
+    if (leg !== null) {
+      try {
+        await leg.wallets.refund(leg.ref, { amountNanoUsd: delta.billedNanoUsd, idempotencyKey: `hold-rollback:${ledgerKey}`, reason: "hold rollback" });
+      } catch {
+        this.logger.warn("failed to refund a hold debit during rollback");
+      }
+    }
+    if (this.budgets === void 0) return;
+    try {
+      await this.budgets.release(context, budgetDelta(delta));
+    } catch {
+      this.logger.warn("failed to release a budget reservation during rollback");
+    }
+  }
+  /**
+   * Settle a capture: apply the signed ±delta between the actual and the reserved
+   * estimate to the budget window/counter and the wallet — never re-blocking.
+   *
+   * @param record The now-posted record (the payer/feature source).
+   * @param reservedBilledNanoUsd The hold's billed estimate.
+   * @param reservedTokens The hold's estimated tokens.
+   * @param actualBilledNanoUsd The settled billed cost.
+   * @param actualTokens The settled token total.
+   */
+  async settleCapture(record, reservedBilledNanoUsd, reservedTokens, actualBilledNanoUsd, actualTokens) {
+    if (record.isSystemCost) return;
+    if (this.budgets !== void 0) {
+      await this.budgets.adjust(contextOf(record), { nanoUsd: actualBilledNanoUsd - reservedBilledNanoUsd, tokens: actualTokens - reservedTokens, count: 0 });
+    }
+    const walletDelta = reservedBilledNanoUsd - actualBilledNanoUsd;
+    const leg = this.legFor(record.tenantId, record.scope, walletDelta, true);
+    if (leg === null) return;
+    await leg.wallets.settleAdjustment(leg.ref, { amountNanoUsd: walletDelta, usageRecordId: record.id, idempotencyKey: `capture:${record.id}`, reason: "hold capture settlement" });
+  }
+  /**
+   * Restore a hold in full — the shared code path for `release()` and the reaper.
+   * Releases the reserved budget and refunds the reserved wallet debit.
+   *
+   * @param record The pending record being voided (carries the reserved amounts).
+   */
+  async restoreHold(record) {
+    if (record.isSystemCost) return;
+    if (this.budgets !== void 0) {
+      await this.budgets.release(contextOf(record), { nanoUsd: record.billedCostNanoUsd, tokens: record.totalTokens, count: 1 });
+    }
+    const leg = this.legFor(record.tenantId, record.scope, record.billedCostNanoUsd, false);
+    if (leg === null) return;
+    await leg.wallets.refund(leg.ref, { amountNanoUsd: record.billedCostNanoUsd, usageRecordId: record.id, idempotencyKey: `release:${record.id}`, reason: "hold released" });
+  }
+  /**
+   * Compensate a reversed posted record — best-effort across stores (§8.5 step 3;
+   * cross-store 2PC is out of scope, deterministic keys make retries safe).
+   *
+   * @param record The reversed (annotated) original record.
+   * @param reason The caller's stated reason (echoed on the wallet refund).
+   */
+  async reverseEffects(record, reason) {
+    const leg = this.legFor(record.tenantId, record.scope, record.billedCostNanoUsd, false);
+    if (leg !== null) {
+      try {
+        await leg.wallets.refund(leg.ref, { amountNanoUsd: record.billedCostNanoUsd, usageRecordId: record.id, idempotencyKey: `reverse:${record.id}`, reason });
+      } catch {
+        this.logger.warn("failed to refund a wallet debit during reversal");
+      }
+    }
+    if (this.budgets === void 0) return;
+    try {
+      await this.budgets.release(contextOf(record), { nanoUsd: record.billedCostNanoUsd, tokens: record.totalTokens, count: 1 });
+    } catch {
+      this.logger.warn("failed to release a budget consumption during reversal");
+    }
+  }
+  /**
+   * Post-hoc enforcement for `record({ enforce: true })` — consume the budget then
+   * debit the wallet AFTER the ledger write (the §11.2 trade-off; both may throw). A
+   * wallet shortfall rolls the budget consumption back before rethrowing.
+   *
+   * @param record The just-persisted enforced record.
+   * @throws {AiTokensException} A budget/quota/credits error when a limit is exhausted.
+   */
+  async enforceRecord(record) {
+    if (record.isSystemCost) return;
+    const delta = budgetDelta({ billedNanoUsd: record.billedCostNanoUsd, tokens: record.totalTokens, count: 1 });
+    if (this.budgets !== void 0) await this.budgets.consume(contextOf(record), delta);
+    const leg = this.legFor(record.tenantId, record.scope, record.billedCostNanoUsd, false);
+    if (leg === null) return;
+    try {
+      await leg.wallets.debit(leg.ref, { amountNanoUsd: record.billedCostNanoUsd, usageRecordId: record.id, idempotencyKey: `record:${record.id}`, reason: "post-hoc enforcement" });
+    } catch (error) {
+      if (this.budgets !== void 0) await this.budgets.release(contextOf(record), delta);
+      throw error;
+    }
+  }
+};
+
+// src/server/streaming/stream-usage-collector.ts
+function zeroUsage(provider, model, operation) {
+  return {
+    provider,
+    model,
+    operation,
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWrite5mTokens: 0,
+    cacheWrite1hTokens: 0,
+    reasoningTokens: 0,
+    audioInTokens: 0,
+    audioOutTokens: 0,
+    imageInTokens: 0,
+    imageOutTokens: 0
+  };
+}
+function asRecord(value) {
+  return typeof value === "object" && value !== null ? value : null;
+}
+var StreamUsageCollector = class {
+  /** @param opts The provider/model + optional preset/tokenizer/extractor. */
+  constructor(opts) {
+    this.opts = opts;
+    this.operation = opts.operation ?? "chat";
+    this.anthropicModel = opts.model;
+  }
+  opts;
+  operation;
+  outputText = "";
+  /** The provider-final response object to normalize, once seen. */
+  finalResponse = null;
+  /** Anthropic streaming state accumulated across events (seeded from the constructed identity). */
+  anthropicModel;
+  anthropicBaseUsage = {};
+  anthropicOutputTokens = 0;
+  promptTokens;
+  promptText;
+  finalized = false;
+  malformed = 0;
+  /** True after `finalize()` when the tokenizer fallback (not provider-final usage) was used. */
+  usedFallback = false;
+  /** How many chunks were skipped as malformed (debug/observability). */
+  get malformedCount() {
+    return this.malformed;
+  }
+  /** Provide the prompt text so an aborted stream can count input tokens via the tokenizer. */
+  setPromptText(text) {
+    this.promptText = text;
+  }
+  /** Provide a pre-counted prompt token total (takes precedence over `setPromptText`). */
+  setPromptTokens(count) {
+    this.promptTokens = count;
+  }
+  /**
+   * Feed one stream chunk: accumulate output text and watch for the provider-final
+   * usage. Never throws — a malformed chunk is skipped and counted.
+   *
+   * @param chunk One raw provider stream chunk/event.
+   */
+  push(chunk) {
+    try {
+      const record = asRecord(chunk);
+      if (record === null) {
+        this.malformed += 1;
+        return;
+      }
+      if (this.opts.provider === "anthropic") this.pushAnthropic(record);
+      else this.pushOpenAiLike(record);
+    } catch {
+      this.malformed += 1;
+    }
+  }
+  /**
+   * Resolve the final usage: provider-final when seen (normalized), else a tokenizer
+   * count of the accumulated output (input tokens from the prompt count when
+   * provided, else 0 — the hold estimate is applied by `capture()`), else a
+   * missing-usage error. Async to support async tokenizers (§14.2.1). Single-use.
+   *
+   * @returns The finalized normalized usage.
+   * @throws {AiTokensException} `AI_TOKENS_STREAM_USAGE_MISSING` on an abort with no tokenizer; a re-use error on a second call.
+   */
+  async finalize() {
+    if (this.finalized) throw new AiTokensException("AI_TOKENS_STREAM_USAGE_MISSING", void 0, { reason: "the collector was already finalized" });
+    this.finalized = true;
+    const provider = this.opts.provider;
+    if (this.finalResponse !== null) return this.normalizeFinal(this.finalResponse);
+    const tokenizer = this.opts.tokenizer;
+    if (tokenizer !== void 0) return this.fallbackUsage(provider, tokenizer);
+    throw new AiTokensException("AI_TOKENS_STREAM_USAGE_MISSING", void 0, { provider, model: this.opts.model });
+  }
+  /** Accumulate an OpenAI-shaped chunk and capture its trailing usage. */
+  pushOpenAiLike(record) {
+    const text = this.opts.outputText?.(record) ?? openAiDelta(record);
+    if (text !== void 0) this.outputText += text;
+    if (asRecord(record.usage) !== null) this.finalResponse = record;
+  }
+  /** Accumulate an Anthropic-shaped event and reconstruct its final usage at message_stop. */
+  pushAnthropic(record) {
+    const type = record.type;
+    if (type === "message_start") {
+      const message = asRecord(record.message);
+      const usage = asRecord(message?.usage);
+      this.anthropicModel = typeof message?.model === "string" ? message.model : this.opts.model;
+      this.anthropicBaseUsage = usage ?? {};
+      this.anthropicOutputTokens = numberOf(usage?.output_tokens);
+    } else if (type === "content_block_delta") {
+      const delta = asRecord(record.delta);
+      const text = this.opts.outputText?.(record) ?? (typeof delta?.text === "string" ? delta.text : void 0);
+      if (text !== void 0) this.outputText += text;
+    } else if (type === "message_delta") {
+      const usage = asRecord(record.usage);
+      if (usage !== null) this.anthropicOutputTokens = numberOf(usage.output_tokens);
+    } else if (type === "message_stop") {
+      this.finalResponse = {
+        model: this.anthropicModel,
+        usage: { ...this.anthropicBaseUsage, output_tokens: this.anthropicOutputTokens }
+      };
+    }
+  }
+  /** Normalize a captured provider-final response via the preset or the provider default. */
+  normalizeFinal(response) {
+    const normalizer = this.opts.preset?.normalizer ?? (this.opts.provider === "anthropic" ? normalizeAnthropicUsage : normalizeOpenAiChatUsage);
+    return normalizer(response);
+  }
+  /** Build the tokenizer-counted fallback usage for an aborted stream. */
+  async fallbackUsage(provider, tokenizer) {
+    this.usedFallback = true;
+    const outputTokens = await tokenizer.countTokens({ text: this.outputText, model: this.opts.model, provider });
+    const inputTokens = this.promptTokens ?? (this.promptText !== void 0 ? await tokenizer.countTokens({ text: this.promptText, model: this.opts.model, provider }) : 0);
+    return { ...zeroUsage(provider, this.opts.model, this.operation), inputTokens, outputTokens };
+  }
+};
+function openAiDelta(record) {
+  if (!Array.isArray(record.choices)) return void 0;
+  let text = "";
+  for (const choice of record.choices) {
+    const delta = asRecord(asRecord(choice)?.delta);
+    if (typeof delta?.content === "string") text += delta.content;
+  }
+  return text === "" ? void 0 : text;
+}
+function numberOf(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+// src/server/telemetry/no-op-telemetry.ts
+var NO_OP_TELEMETRY = new TelemetryEmitter(null);
+
+// src/server/services/hold-support.ts
+var UNSPECIFIED = "unspecified";
+var PER_MILLION = 1000000n;
+var TOKEN_FIELDS = TOKEN_CATEGORIES.map((category) => `${category}Tokens`);
+function zeroTokenCounts() {
+  return {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWrite5mTokens: 0,
+    cacheWrite1hTokens: 0,
+    reasoningTokens: 0,
+    audioInTokens: 0,
+    audioOutTokens: 0,
+    imageInTokens: 0,
+    imageOutTokens: 0
+  };
+}
+function tokenCountsOf(usage) {
+  return {
+    inputTokens: usage.inputTokens,
+    outputTokens: usage.outputTokens,
+    cacheReadTokens: usage.cacheReadTokens,
+    cacheWrite5mTokens: usage.cacheWrite5mTokens,
+    cacheWrite1hTokens: usage.cacheWrite1hTokens,
+    reasoningTokens: usage.reasoningTokens,
+    audioInTokens: usage.audioInTokens,
+    audioOutTokens: usage.audioOutTokens,
+    imageInTokens: usage.imageInTokens,
+    imageOutTokens: usage.imageOutTokens
+  };
+}
+function sumTokenCounts(counts) {
+  return TOKEN_FIELDS.reduce((total, field) => total + counts[field], 0);
+}
+function isNormalizedUsage(usage) {
+  if (typeof usage !== "object" || usage === null) return false;
+  const candidate = usage;
+  if (typeof candidate.provider !== "string" || typeof candidate.model !== "string") return false;
+  if (typeof candidate.operation !== "string" || !AI_OPERATIONS.includes(candidate.operation)) {
+    return false;
+  }
+  return TOKEN_FIELDS.every((field) => typeof candidate[field] === "number" && Number.isFinite(candidate[field]));
+}
+function isRatedEstimate(estimate) {
+  return "provider" in estimate;
+}
+function isTokenEstimate(estimate) {
+  return "tokens" in estimate;
+}
+function syntheticUsage(estimate, serviceTier) {
+  return {
+    provider: estimate.provider,
+    model: estimate.model,
+    operation: estimate.operation,
+    serviceTier,
+    ...zeroTokenCounts(),
+    inputTokens: estimate.inputTokens,
+    outputTokens: estimate.maxOutputTokens
+  };
+}
+async function resolveHoldEstimate(pricing, context, estimate, at) {
+  const serviceTier = context.serviceTier ?? "standard";
+  if (isRatedEstimate(estimate)) {
+    const tier = estimate.serviceTier ?? serviceTier;
+    const usage = syntheticUsage(estimate, tier);
+    const rate = await pricing.resolveRate({
+      provider: estimate.provider,
+      model: estimate.model,
+      operation: estimate.operation,
+      serviceTier: tier,
+      at,
+      // Stryker disable next-line ConditionalExpression -- CE true: spreading { baseModel: undefined } is equivalent to {} because resolveRate reads input.baseModel (undefined either way) — same cache key and same `baseModel !== undefined` resolution branch
+      ...context.baseModel !== void 0 ? { baseModel: context.baseModel } : {}
+    });
+    const rawEstimateNanoUsd = rate === null ? 0n : computeCostNanoUsd(usage, rate).totalNanoUsd;
+    const tokenCounts2 = { ...zeroTokenCounts(), inputTokens: estimate.inputTokens, outputTokens: estimate.maxOutputTokens };
+    return { provider: estimate.provider, model: estimate.model, operation: estimate.operation, serviceTier: tier, rawEstimateNanoUsd, estimatedTokens: sumTokenCounts(tokenCounts2), tokenCounts: tokenCounts2 };
+  }
+  if (isTokenEstimate(estimate)) {
+    return resolveTokenEstimate(pricing, context, estimate.tokens, serviceTier, at);
+  }
+  const tokenCounts = zeroTokenCounts();
+  return {
+    provider: context.preset?.provider ?? UNSPECIFIED,
+    model: context.baseModel ?? UNSPECIFIED,
+    operation: "chat",
+    serviceTier,
+    rawEstimateNanoUsd: estimate.amountNanoUsd,
+    estimatedTokens: 0,
+    tokenCounts
+  };
+}
+async function resolveTokenEstimate(pricing, context, tokens, serviceTier, at) {
+  if (context.preset === void 0) {
+    throw new AiTokensException("AI_TOKENS_INVALID_CONFIG", void 0, {
+      // Stryker disable next-line StringLiteral -- error reason text is internal diagnostics
+      reason: "a { tokens } hold estimate requires context.preset to identify the provider"
+    });
+  }
+  const provider = context.preset.provider;
+  const model = context.baseModel ?? UNSPECIFIED;
+  let rawEstimateNanoUsd = 0n;
+  if (context.baseModel !== void 0) {
+    const rate = await pricing.resolveRate({ provider, model, operation: "chat", serviceTier, at });
+    if (rate !== null) rawEstimateNanoUsd = BigInt(tokens) * rate.inputNanoUsdPerMillion / PER_MILLION;
+  }
+  const tokenCounts = { ...zeroTokenCounts(), inputTokens: tokens };
+  return { provider, model, operation: "chat", serviceTier, rawEstimateNanoUsd, estimatedTokens: tokens, tokenCounts };
+}
+function normalizeCaptureUsage(usage, normalizer) {
+  if (isNormalizedUsage(usage)) return usage;
+  if (normalizer !== void 0) {
+    try {
+      return normalizer(usage);
+    } catch (error) {
+      if (error instanceof AiTokensException) throw error;
+      throw new AiTokensException("AI_TOKENS_USAGE_MALFORMED", void 0, { reason: "the normalizer could not read the usage token fields" });
+    }
+  }
+  throw new AiTokensException("AI_TOKENS_USAGE_MALFORMED", void 0, {
+    // Stryker disable next-line StringLiteral -- error reason text is internal diagnostics
+    reason: "capture requires an already-normalized usage or a preset normalizer"
+  });
+}
+
+// src/server/services/metering.service.ts
+var NOOP_EVENT_HOOKS = {
+  usageRecorded: () => Promise.resolve(),
+  priceMissing: () => Promise.resolve(),
+  holdReleased: () => Promise.resolve(),
+  usageReversed: () => Promise.resolve(),
+  audit: () => Promise.resolve()
+};
+var ESTIMATE_SCOPE = { type: "tenant", id: "" };
+var DEFAULT_HOLDS = { ttlSeconds: 3600};
+function buildAppendInput(args) {
+  const { normalized, context, serviceTier, occurredAt, rating, markup, ratedUnits, enforced } = args;
+  return {
+    ...baseColumns(normalized, context, serviceTier),
+    inputTokens: normalized.inputTokens,
+    outputTokens: normalized.outputTokens,
+    cacheReadTokens: normalized.cacheReadTokens,
+    cacheWrite5mTokens: normalized.cacheWrite5mTokens,
+    cacheWrite1hTokens: normalized.cacheWrite1hTokens,
+    reasoningTokens: normalized.reasoningTokens,
+    audioInTokens: normalized.audioInTokens,
+    audioOutTokens: normalized.audioOutTokens,
+    imageInTokens: normalized.imageInTokens,
+    imageOutTokens: normalized.imageOutTokens,
+    // Stryker disable next-line ConditionalExpression,EqualityOperator -- CE/EQ: when ratedUnits is empty, spreading { extraUnits: {} } vs omitting the key; downstream consumers check record.extraUnits !== undefined (absent vs present {}); unit tests don't use server tool use, so ratedUnits={} always → no observable difference
+    ...Object.keys(ratedUnits).length > 0 ? { extraUnits: ratedUnits } : {},
+    priceVersionId: rating.priceVersionId,
+    rawCostNanoUsd: rating.rawCostNanoUsd,
+    surchargeNanoUsd: rating.surchargeNanoUsd,
+    billedCostNanoUsd: markup.apply(rating.rawCostNanoUsd),
+    markupMultiplier: markup.multiplier,
+    currency: "USD",
+    priceMissing: rating.priceMissing,
+    status: "posted",
+    isSystemCost: context.isSystemCost ?? false,
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { systemCostCategory: undefined } is equivalent to {} because JS property access treats absent and undefined the same
+    ...context.systemCostCategory !== void 0 ? { systemCostCategory: context.systemCostCategory } : {},
+    enforced,
+    occurredAt
+  };
+}
+function baseColumns(usage, context, serviceTier) {
+  return {
+    tenantId: context.tenantId,
+    scope: context.scope,
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { beneficiary: undefined } is equivalent to {} for property access and truthiness-based filters
+    ...context.beneficiary !== void 0 ? { beneficiary: context.beneficiary } : {},
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { requestedBy: undefined } is equivalent to {}
+    ...context.requestedBy !== void 0 ? { requestedBy: context.requestedBy } : {},
+    provider: usage.provider,
+    model: usage.model,
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { requestedModel: undefined } is equivalent to {} for downstream consumers
+    ...context.baseModel !== void 0 ? { requestedModel: context.baseModel } : {},
+    operation: usage.operation,
+    serviceTier,
+    feature: context.feature,
+    tags: context.tags ?? [],
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { correlationId: undefined } is equivalent to {} because it's only read via record.correlationId
+    ...context.correlationId !== void 0 ? { correlationId: context.correlationId } : {}
+  };
+}
+var MeteringService = class {
+  /**
+   * @param ledger The append-only ledger service.
+   * @param pricing The pricing service (rate resolution).
+   * @param markup The per-call markup resolver.
+   * @param options The resolved options (rating mode, hold TTL, wallet overdraft).
+   * @param events The event hooks; the module wires them to the dispatcher.
+   * @param wallets The wallet service, when the wallet feature is enabled.
+   * @param budgets The budget service, when the budget feature is enabled.
+   * @param now The injected clock (hold expiry).
+   * @param telemetry The GenAI telemetry emitter (no-op by default).
+   */
+  constructor(ledger, pricing, markup, options, events = NOOP_EVENT_HOOKS, wallets, budgets, now = () => /* @__PURE__ */ new Date(), telemetry = NO_OP_TELEMETRY, content = NO_OP_CONTENT_CAPTURE) {
+    this.ledger = ledger;
+    this.pricing = pricing;
+    this.markup = markup;
+    this.options = options;
+    this.events = events;
+    this.now = now;
+    this.telemetry = telemetry;
+    this.content = content;
+    this.wallets = wallets ?? void 0;
+    this.budgets = budgets ?? void 0;
+    this.effects = new MeteringEffects(this.wallets, this.budgets);
+    this.overdraftNanoUsd = options.wallets?.enabled === true ? options.wallets.overdraftNanoUsd : 0n;
+  }
+  ledger;
+  pricing;
+  markup;
+  options;
+  events;
+  now;
+  telemetry;
+  content;
+  logger = new Logger(MeteringService.name);
+  effects;
+  /** The wallet service, or `undefined` when the wallet feature is disabled. */
+  wallets;
+  /** The budget service, or `undefined` when the budget feature is disabled. */
+  budgets;
+  /** The wallet overdraft headroom (0 when wallets are disabled). */
+  overdraftNanoUsd;
+  /**
+   * Post-hoc metering: normalize, rate, apply markup, append a `posted` record, and
+   * emit `ai_tokens.usage.recorded`. Observe-only by default; `enforce: true` also
+   * consumes budgets and debits the wallet AFTER the ledger write (§11.2 trade-off:
+   * a call that already ran can still exceed a limit) — it requires the wallet or
+   * budget feature.
+   *
+   * @param input The usage, its preset/normalizer, and the metering context.
+   * @returns The posted usage record.
+   * @throws {AiTokensException} `AI_TOKENS_INVALID_CONFIG` when `enforce: true` without wallets/budgets; normalize/rate errors; post-hoc budget/quota/credits errors.
+   */
+  async record(input) {
+    const { context } = input;
+    const enforcing = context.enforce === true;
+    if (enforcing && this.wallets === void 0 && this.budgets === void 0) {
+      throw new AiTokensException("AI_TOKENS_INVALID_CONFIG", void 0, {
+        // Stryker disable next-line StringLiteral -- error reason text is internal diagnostics
+        reason: "enforce requires the wallets or budgets feature to be enabled"
+      });
+    }
+    const normalized = this.resolveNormalizedUsage(input);
+    const serviceTier = context.serviceTier ?? normalized.serviceTier ?? "standard";
+    const occurredAt = input.occurredAt ?? this.now();
+    const mode = context.ratingMode ?? input.preset?.ratingMode ?? this.options.ratingMode;
+    const ratedUnits = { ...normalized.serverToolUse, ...context.extraUnits };
+    const usageForRating = { ...normalized, serverToolUse: ratedUnits };
+    const rating = await this.rate(usageForRating, serviceTier, occurredAt, mode, context.baseModel);
+    const markup = await this.resolveMarkup(context, normalized, serviceTier);
+    const record = await this.ledger.append(
+      buildAppendInput({ normalized, context, serviceTier, occurredAt, rating, markup, ratedUnits, enforced: enforcing }),
+      context.idempotencyKey
+    );
+    if (rating.priceMissing) await this.events.priceMissing(record);
+    await this.events.usageRecorded(record);
+    this.telemetry.recordUsage(record);
+    await this.captureContent(record.id, context.tenantId, input.content);
+    if (enforcing) await this.effects.enforceRecord(record);
+    return record;
+  }
+  /**
+   * Pure pre-flight cost estimate — no ledger or event side effects.
+   *
+   * @param input The hypothetical call.
+   * @returns The raw and billed nano-USD estimate.
+   */
+  async estimateCost(input) {
+    const serviceTier = input.serviceTier ?? "standard";
+    const at = input.at ?? this.now();
+    const usage = {
+      provider: input.provider,
+      model: input.model,
+      operation: input.operation,
+      inputTokens: input.inputTokens,
+      outputTokens: input.maxOutputTokens,
+      cacheReadTokens: 0,
+      cacheWrite5mTokens: 0,
+      cacheWrite1hTokens: 0,
+      reasoningTokens: 0,
+      audioInTokens: 0,
+      audioOutTokens: 0,
+      imageInTokens: 0,
+      imageOutTokens: 0
+    };
+    const rate = await this.pricing.resolveRate({ provider: input.provider, model: input.model, operation: input.operation, serviceTier, at });
+    const rawCostNanoUsd = rate === null ? 0n : computeCostNanoUsd(usage, rate).totalNanoUsd;
+    const markup = await this.markup.resolve({
+      scope: input.scope ?? ESTIMATE_SCOPE,
+      provider: input.provider,
+      model: input.model,
+      operation: input.operation,
+      serviceTier,
+      // Stryker disable next-line ConditionalExpression -- CE true: spreading { feature: undefined } is equivalent to {} because markup.resolve treats absent and undefined feature the same
+      ...input.feature !== void 0 ? { feature: input.feature } : {}
+    });
+    return { rawCostNanoUsd, billedCostNanoUsd: markup.apply(rawCostNanoUsd) };
+  }
+  /**
+   * Place an auth-hold: rate the estimate, apply markup, reserve budget + wallet
+   * headroom (compensated on any step's failure), and write a `pending` ledger
+   * record with a TTL (§2.2 step 1). A repeat with the same `idempotencyKey`
+   * returns the EXISTING hold without re-reserving — this prioritizes not
+   * double-consuming budget/wallet over parameter-conflict detection, so a replay
+   * with a CHANGED estimate silently keeps the original reservation (unlike
+   * `record()`, whose payload hash rejects a changed payload with 409); settlement
+   * still corrects to actuals at capture. Concurrent holds sharing one key can both
+   * pass the pre-check and reserve; the losing ledger insert compensates its
+   * reservation (a brief over-reserve window under high contention).
+   *
+   * @param context The metering context (payer scope, feature).
+   * @param estimate One of the three {@link HoldEstimate} variants.
+   * @returns The plain, serializable {@link Hold}.
+   * @throws {AiTokensException} `AI_TOKENS_BUDGET_EXCEEDED` / `_QUOTA_EXCEEDED` / `_INSUFFICIENT_CREDITS` on a shortfall (prior steps compensated).
+   */
+  async hold(context, estimate) {
+    if (context.idempotencyKey !== void 0) {
+      const existing = await this.ledger.findByIdempotencyKey(context.tenantId, context.idempotencyKey);
+      if (existing !== null) return this.holdOf(existing);
+    }
+    const occurredAt = this.now();
+    const resolved = await resolveHoldEstimate(this.pricing, context, estimate, occurredAt);
+    const markup = await this.markup.resolve({ scope: context.scope, provider: resolved.provider, model: resolved.model, operation: resolved.operation, serviceTier: resolved.serviceTier, feature: context.feature });
+    const billedEstimate = markup.apply(resolved.rawEstimateNanoUsd);
+    const isSystemCost = context.isSystemCost ?? false;
+    const ledgerKey = context.idempotencyKey ?? `hold:${randomUUID()}`;
+    const delta = { billedNanoUsd: billedEstimate, tokens: resolved.estimatedTokens, count: 1 };
+    if (!isSystemCost) await this.effects.reserveHold(context, delta, ledgerKey);
+    const record = await this.appendPending(context, resolved, billedEstimate, markup.multiplier, occurredAt, ledgerKey, isSystemCost, delta);
+    return this.holdOf(record);
+  }
+  /**
+   * Settle a hold with provider-reported actuals (§2.2 step 3). IDEMPOTENT: a repeat
+   * on an already-settled hold returns the posted record unchanged. Applies the
+   * ±delta between the actual and the reserved estimate to wallet/budget/counter.
+   *
+   * @param hold The hold to settle (revalidated against the store + caller tenant).
+   * @param usage The raw provider usage or an already-normalized usage.
+   * @param preset The preset normalizing the usage (or provider-reported mode).
+   * @param content Optional prompt/completion text for the sidecar (§14.2) — the ONLY text path.
+   * @returns The posted usage record.
+   * @throws {AiTokensException} `AI_TOKENS_HOLD_NOT_FOUND` (cross-tenant/missing), `_HOLD_EXPIRED` (reaped), `_HOLD_ALREADY_SETTLED` (released).
+   */
+  async capture(hold, usage, preset2, content) {
+    const record = await this.loadHoldRecord(hold);
+    if (record.status !== "pending") return this.settledOrConflict(record);
+    const normalized = await this.finalizeCaptureUsage(usage, hold, preset2);
+    const usageForRating = {
+      ...normalized,
+      provider: record.provider,
+      model: record.model,
+      operation: record.operation,
+      serviceTier: record.serviceTier,
+      serverToolUse: record.extraUnits ?? {}
+    };
+    const mode = preset2?.ratingMode ?? this.options.ratingMode;
+    const rating = await this.rate(usageForRating, record.serviceTier, record.occurredAt, mode, record.requestedModel);
+    const markup = await this.markup.resolve({ scope: record.scope, provider: record.provider, model: record.model, operation: record.operation, serviceTier: record.serviceTier, feature: record.feature });
+    const counts = tokenCountsOf(usageForRating);
+    const patch = this.settlementPatch(counts, rating, markup);
+    const reservedBilled = record.billedCostNanoUsd;
+    const reservedTokens = record.totalTokens;
+    const settled = await this.ledger.transition(record.id, "pending", "posted", patch);
+    if (settled === null) return this.settledOrConflict(await this.reload(record.id));
+    await this.events.usageRecorded(settled);
+    this.telemetry.recordUsage(settled);
+    await this.captureContent(settled.id, settled.tenantId, content);
+    await this.effects.settleCapture(settled, reservedBilled, reservedTokens, settled.billedCostNanoUsd, settled.totalTokens);
+    return settled;
+  }
+  /**
+   * Void a hold: `pending → released`, restoring wallet/budget in full (§2.2 step
+   * 4). NEVER bills. A no-op (with a warning) on an already-captured hold; a no-op
+   * on an already-released hold. Multi-caller safe via the atomic transition claim.
+   *
+   * @param hold The hold to void (revalidated against the store + caller tenant).
+   * @param reason The caller's stated reason (surfaced on `ai_tokens.hold.released`).
+   * @throws {AiTokensException} `AI_TOKENS_HOLD_NOT_FOUND` on a cross-tenant/missing hold.
+   */
+  async release(hold, reason) {
+    const record = await this.loadHoldRecord(hold);
+    if (record.status === "posted") {
+      this.logger.warn(`release() called on an already-captured hold ${record.id}; ignoring (release never bills)`);
+      return;
+    }
+    if (record.status !== "pending") return;
+    const claimed = await this.ledger.transition(record.id, "pending", "released");
+    if (claimed === null) return;
+    await this.restoreReleasedHold(claimed, reason, false);
+  }
+  /**
+   * The most common entry point: hold → run `fn` → capture (release on error). With
+   * no estimate it skips the hold and runs `record({ enforce: true })` post-hoc.
+   *
+   * @param fn The metered async function (the LLM call).
+   * @param context The metering context (payer scope, feature, preset).
+   * @param extract Pull the raw usage out of `fn`'s result.
+   * @param estimate The optional hold estimate; omit for the post-hoc enforce path.
+   * @returns The function result and its settled usage record.
+   */
+  async meter(fn, context, extract, estimate) {
+    const startedAt = this.now().getTime();
+    if (estimate === void 0) {
+      const result2 = await fn();
+      const usage = await this.record({ usage: extract(result2), ...context.preset !== void 0 ? { preset: context.preset } : {}, context: { ...context, enforce: true } });
+      this.telemetry.recordDuration(usage, this.now().getTime() - startedAt);
+      return { result: result2, usage };
+    }
+    const hold = await this.hold(context, estimate);
+    let result;
+    try {
+      result = await fn();
+    } catch (error) {
+      await this.release(hold, "metered function threw");
+      throw error;
+    }
+    try {
+      const usage = await this.capture(hold, extract(result), context.preset);
+      this.telemetry.recordDuration(usage, this.now().getTime() - startedAt);
+      return { result, usage };
+    } catch (error) {
+      await this.release(hold, "capture failed").catch(() => void 0);
+      throw error;
+    }
+  }
+  /**
+   * Orchestrated compensation (§8.5 step 3): reverse the ledger record, then — for
+   * an enforced, non-system record — refund the wallet and release the budget
+   * (cost, tokens, and count). ADMIN PLANE (§14.4): the host MUST restrict this to
+   * privileged roles; it emits `ai_tokens.usage.reversed` and `ai_tokens.audit`.
+   * Cross-store effects are best-effort sequential with logged partial failures;
+   * deterministic keys make retries safe.
+   *
+   * @param usageRecordId The posted record to reverse.
+   * @param reason The caller's stated reason.
+   * @returns The compensating record.
+   * @throws {AiTokensException} `AI_TOKENS_IDEMPOTENCY_CONFLICT` when the record is missing or not `posted`.
+   */
+  async reverse(usageRecordId, reason) {
+    const compensating = await this.ledger.reverse(usageRecordId, reason);
+    const original = await this.ledger.findById(usageRecordId);
+    if (original !== null && original.enforced && !original.isSystemCost) {
+      await this.effects.reverseEffects(original, reason);
+    }
+    await this.events.usageReversed(original ?? compensating, compensating.id, reason);
+    await this.events.audit("ai_tokens.usage.reversed", { tenantId: compensating.tenantId, usageRecordId, reversalRecordId: compensating.id, reason });
+    return compensating;
+  }
+  /**
+   * Combined wallet + budget status (§10.6) — the usage-meter data source. No side
+   * effects. The wallet section is absent when wallets are disabled or the scope is
+   * a `'key'` (keys spend their owner's wallet). `hasAccess` is false with
+   * `blockedBy` set when the wallet or a hard budget is exhausted.
+   *
+   * @param tenantId The owning tenant.
+   * @param scope The scope to report for.
+   * @returns The combined access status.
+   */
+  async getStatus(tenantId, scope) {
+    const budgets = this.budgets !== void 0 ? await this.budgets.status(tenantId, scope) : [];
+    const wallet = await this.walletSection(tenantId, scope);
+    const budgetBlocked = budgets.some((status) => isHardExhausted(status));
+    const walletBlocked = wallet !== void 0 && wallet.balanceNanoUsd + wallet.overdraftRemainingNanoUsd <= 0n;
+    const blockedBy = walletBlocked ? "wallet" : budgetBlocked ? "budget" : void 0;
+    return { hasAccess: blockedBy === void 0, ...blockedBy !== void 0 ? { blockedBy } : {}, ...wallet !== void 0 ? { wallet } : {}, budgets };
+  }
+  /**
+   * Restore a reclaimed hold and announce it — the shared code path for `release()`
+   * and the hold reaper (§8.3). The caller has already won the `pending → released`
+   * transition claim.
+   *
+   * @param record The just-released record (carries the reserved amounts).
+   * @param reason The stated reason.
+   * @param expired True when reclaimed by the reaper (vs an explicit release).
+   */
+  async restoreReleasedHold(record, reason, expired) {
+    await this.effects.restoreHold(record);
+    await this.events.holdReleased(record, reason, expired);
+  }
+  /** Reserve the pending ledger row, compensating the reservation if the insert fails. */
+  async appendPending(context, resolved, billedEstimate, markupMultiplier, occurredAt, ledgerKey, isSystemCost, delta) {
+    try {
+      return await this.ledger.append(
+        {
+          ...baseColumns(resolved, context, resolved.serviceTier),
+          ...resolved.tokenCounts,
+          priceVersionId: null,
+          rawCostNanoUsd: resolved.rawEstimateNanoUsd,
+          surchargeNanoUsd: 0n,
+          billedCostNanoUsd: billedEstimate,
+          markupMultiplier,
+          currency: "USD",
+          priceMissing: false,
+          status: "pending",
+          isSystemCost,
+          // Stryker disable next-line ConditionalExpression -- CE true: spreading { systemCostCategory: undefined } is equivalent to {}
+          ...context.systemCostCategory !== void 0 ? { systemCostCategory: context.systemCostCategory } : {},
+          enforced: !isSystemCost,
+          occurredAt
+        },
+        ledgerKey
+      );
+    } catch (error) {
+      if (!isSystemCost) await this.effects.compensateHold(context, delta, ledgerKey);
+      throw error;
+    }
+  }
+  /** Forward host-supplied prompt/completion text to the opt-in content sidecar (§14.2). */
+  captureContent(usageRecordId, tenantId, content) {
+    if (content === void 0) return Promise.resolve();
+    return this.content.capture({ usageRecordId, tenantId, prompt: content.prompt, completion: content.completion });
+  }
+  /** Build the {@link Hold} view of a pending (or replayed) ledger record. */
+  holdOf(record) {
+    const ttlSeconds = (this.options.holds ?? DEFAULT_HOLDS).ttlSeconds;
+    return {
+      id: record.id,
+      tenantId: record.tenantId,
+      scope: record.scope,
+      estimatedTokens: record.totalTokens,
+      estimatedCostNanoUsd: record.billedCostNanoUsd,
+      expiresAt: new Date(record.createdAt.getTime() + ttlSeconds * 1e3)
+    };
+  }
+  /** Load a hold's record and reject a cross-tenant/scope or missing hold as HOLD_NOT_FOUND (§14.4). */
+  async loadHoldRecord(hold) {
+    const record = await this.ledger.findById(hold.id);
+    if (record === null) throw new AiTokensException("AI_TOKENS_HOLD_NOT_FOUND", void 0, { holdId: hold.id });
+    if (record.tenantId !== hold.tenantId || !sameScope(record.scope, hold.scope)) {
+      throw new AiTokensException("AI_TOKENS_HOLD_NOT_FOUND", void 0, { holdId: hold.id });
+    }
+    return record;
+  }
+  /** Dispatch a non-pending hold record: posted → idempotent return; released → expired/settled. */
+  settledOrConflict(record) {
+    if (record.status === "posted") return record;
+    if (record.status === "released") {
+      const ttlSeconds = (this.options.holds ?? DEFAULT_HOLDS).ttlSeconds;
+      const expiredAt = record.createdAt.getTime() + ttlSeconds * 1e3;
+      if (this.now().getTime() >= expiredAt) {
+        throw new AiTokensException("AI_TOKENS_HOLD_EXPIRED", void 0, { holdId: record.id });
+      }
+    }
+    throw new AiTokensException("AI_TOKENS_HOLD_ALREADY_SETTLED", void 0, { holdId: record.id });
+  }
+  /** Reload a record by id, or fail HOLD_NOT_FOUND when it vanished mid-capture. */
+  async reload(id) {
+    const record = await this.ledger.findById(id);
+    if (record === null) throw new AiTokensException("AI_TOKENS_HOLD_NOT_FOUND", void 0, { holdId: id });
+    return record;
+  }
+  /**
+   * Normalize the usage handed to `capture()`. A {@link StreamUsageCollector} is
+   * finalized here; when it fell back to a tokenizer count with no prompt tokens
+   * (input `0`), the hold's estimated tokens supply the aborted-stream input
+   * fallback (spec §5.6 order: collector prompt count → hold estimate → 0).
+   */
+  async finalizeCaptureUsage(usage, hold, preset2) {
+    if (usage instanceof StreamUsageCollector) {
+      const finalized = await usage.finalize();
+      if (usage.usedFallback && finalized.inputTokens === 0 && hold.estimatedTokens > 0) {
+        return { ...finalized, inputTokens: hold.estimatedTokens };
+      }
+      return finalized;
+    }
+    return normalizeCaptureUsage(usage, preset2?.normalizer);
+  }
+  /** Build the settlement patch for a `pending → posted` transition. */
+  settlementPatch(counts, rating, markup) {
+    return {
+      ...counts,
+      totalTokens: sumTokenCounts(counts),
+      rawCostNanoUsd: rating.rawCostNanoUsd,
+      surchargeNanoUsd: rating.surchargeNanoUsd,
+      billedCostNanoUsd: markup.apply(rating.rawCostNanoUsd),
+      markupMultiplier: markup.multiplier,
+      priceVersionId: rating.priceVersionId,
+      priceMissing: rating.priceMissing
+    };
+  }
+  /** Build the wallet section of an {@link AccessStatus}, or `undefined` when wallets are off / scope is a key. */
+  async walletSection(tenantId, scope) {
+    if (this.wallets === void 0 || !scopeOwnsWallet(scope)) return void 0;
+    const balance = await this.wallets.getBalance(scopeToWalletRef(tenantId, scope));
+    const overdraftRemainingNanoUsd = this.overdraftNanoUsd + (balance.nanoUsd < 0n ? balance.nanoUsd : 0n);
+    return { balanceNanoUsd: balance.nanoUsd, credits: balance.credits, overdraftRemainingNanoUsd: overdraftRemainingNanoUsd < 0n ? 0n : overdraftRemainingNanoUsd };
+  }
+  /** Resolve the normalizer chain and produce the normalized usage. */
+  resolveNormalizedUsage(input) {
+    const normalizer = input.normalizer ?? input.preset?.normalizer;
+    if (normalizer !== void 0) return this.normalize(normalizer, input.usage);
+    if (isNormalizedUsage(input.usage)) return input.usage;
+    throw new AiTokensException("AI_TOKENS_UNKNOWN_PROVIDER", void 0, {
+      // Stryker disable next-line StringLiteral -- error reason text is internal diagnostics
+      reason: "raw usage requires a preset or normalizer, or an already-normalized usage"
+    });
+  }
+  /** Resolve markup for a settled/pending call from the normalized identity. */
+  resolveMarkup(context, normalized, serviceTier) {
+    return this.markup.resolve({ scope: context.scope, provider: normalized.provider, model: normalized.model, operation: normalized.operation, serviceTier, feature: context.feature });
+  }
+  /** Run a normalizer, wrapping a plain failure as a malformed-usage error. */
+  normalize(normalizer, usage) {
+    try {
+      return normalizer(usage);
+    } catch (error) {
+      if (error instanceof AiTokensException) throw error;
+      throw new AiTokensException("AI_TOKENS_USAGE_MALFORMED", void 0, { reason: "the normalizer could not read the usage token fields" });
+    }
+  }
+  /** Rate a call in the resolved mode; a non-strict rate miss yields zero cost + `priceMissing`. */
+  async rate(usage, serviceTier, occurredAt, mode, baseModel) {
+    if (mode === "provider-reported") {
+      const cost = usage.providerReportedCostNanoUsd;
+      if (cost === void 0) {
+        throw new AiTokensException("AI_TOKENS_USAGE_MALFORMED", void 0, { reason: "provider-reported rating requires providerReportedCostNanoUsd" });
+      }
+      return { rawCostNanoUsd: cost, surchargeNanoUsd: 0n, priceVersionId: null, priceMissing: false };
+    }
+    const rate = await this.pricing.resolveRate({
+      provider: usage.provider,
+      model: usage.model,
+      operation: usage.operation,
+      serviceTier,
+      at: occurredAt,
+      ...baseModel !== void 0 ? { baseModel } : {}
+    });
+    if (rate === null) return { rawCostNanoUsd: 0n, surchargeNanoUsd: 0n, priceVersionId: null, priceMissing: true };
+    const breakdown = computeCostNanoUsd(usage, rate);
+    return { rawCostNanoUsd: breakdown.totalNanoUsd, surchargeNanoUsd: breakdown.surchargeNanoUsd, priceVersionId: rate.id, priceMissing: false };
+  }
+};
+MeteringService = __decorateClass([
+  Injectable()
+], MeteringService);
+function sameScope(a, b) {
+  return a.type === b.type && a.id === b.id;
+}
+function isHardExhausted(status) {
+  if (status.policy !== "block") return false;
+  if (status.limit.nanoUsd !== void 0 && status.spent.nanoUsd >= status.limit.nanoUsd) return true;
+  if (status.limit.tokens !== void 0 && status.spent.tokens >= status.limit.tokens) return true;
+  return status.limit.count !== void 0 && status.spent.count >= status.limit.count;
+}
+var NOOP_WALLET_HOOKS = {
+  granted: () => void 0,
+  depleted: () => void 0,
+  audit: () => void 0
+};
+var WalletService = class {
+  /**
+   * @param store The wallet persistence port.
+   * @param options The resolved wallet settings (credit rate, overdraft).
+   * @param events The event hooks; the module wires them to the dispatcher.
+   */
+  constructor(store, options, events = NOOP_WALLET_HOOKS) {
+    this.store = store;
+    this.options = options;
+    this.events = events;
+  }
+  store;
+  options;
+  events;
+  /**
+   * The current balance, excluding not-yet-effective and expired grants (§9.2).
+   * Reads the materialized balance; expiry is applied lazily on debit, so a grant
+   * that lapses purely with the passage of time is reflected at the next debit or
+   * `reconcile` (the documented §9.3 lazy-materialization trade-off).
+   *
+   * @param ref The wallet owner (a `'tenant' | 'team' | 'user'`, never `'key'`).
+   * @returns The nano-USD balance and its presentation credits.
+   */
+  async getBalance(ref) {
+    this.assertOwner(ref);
+    const wallet = await this.store.getWallet(ref);
+    const nanoUsd = wallet?.balanceNanoUsd ?? 0n;
+    return { nanoUsd, credits: this.toCredits(nanoUsd) };
+  }
+  /**
+   * Grant credits (allowance, purchase, promo). Auto-creates the wallet on the
+   * first grant. ADMIN PLANE (§14.4): the host MUST restrict this to privileged
+   * roles. Emits `ai_tokens.wallet.granted` and `ai_tokens.audit`.
+   *
+   * @param ref The wallet owner.
+   * @param input The grant amount (`> 0`), optional schedule, key, and reason.
+   * @returns The appended grant entry.
+   * @throws {AiTokensException} `AI_TOKENS_INVALID_CONFIG` on a non-positive amount / `'key'` owner; `AI_TOKENS_IDEMPOTENCY_CONFLICT` on a key reuse with a different payload.
+   */
+  async grant(ref, input) {
+    this.assertOwner(ref);
+    if (input.amountNanoUsd <= 0n) throw this.invalid("grant amount must be greater than 0");
+    const entry = await this.append(ref, {
+      type: "grant",
+      amountNanoUsd: input.amountNanoUsd,
+      priority: input.priority ?? 0,
+      effectiveAt: input.effectiveAt ?? /* @__PURE__ */ new Date(),
+      // Stryker disable next-line ConditionalExpression -- CE true: spreading { expiresAt: undefined } is equivalent to {} because InMemoryWalletStore and consumers check expiresAt !== undefined
+      ...input.expiresAt !== void 0 ? { expiresAt: input.expiresAt } : {},
+      idempotencyKey: input.idempotencyKey,
+      reason: input.reason
+    });
+    const granted = {
+      walletId: entry.walletId,
+      entryId: entry.id,
+      amountNanoUsd: entry.amountNanoUsd,
+      // Stryker disable next-line ConditionalExpression -- CE true: spreading { expiresAt: undefined } is equivalent to {} because event consumers check expiresAt !== undefined
+      ...entry.expiresAt !== void 0 ? { expiresAt: entry.expiresAt } : {}
+    };
+    await this.events.granted(ref, granted);
+    await this.events.audit("ai_tokens.wallet.granted", {
+      tenantId: ref.tenantId,
+      walletId: entry.walletId,
+      entryId: entry.id,
+      amountNanoUsd: entry.amountNanoUsd.toString(),
+      reason: input.reason
+    });
+    return entry;
+  }
+  /**
+   * Atomic conditional debit (§9.4). `usageRecordId` links usage-driven debits;
+   * a non-usage debit (e.g. a voucher reservation) omits it and MUST carry a
+   * `reason`. The store reserves against the materialized balance and records the
+   * grant burn-down allocation in one atomic step — never a check-then-write.
+   *
+   * @param ref The wallet owner.
+   * @param input The debit amount (`> 0`), optional `usageRecordId`, key, and reason.
+   * @returns The appended debit entry.
+   * @throws {AiTokensException} `AI_TOKENS_INSUFFICIENT_CREDITS` (402) when the balance would fall below `-overdraft`; `AI_TOKENS_INVALID_CONFIG` when neither `usageRecordId` nor `reason` is present, or the amount is not positive.
+   */
+  async debit(ref, input) {
+    this.assertOwner(ref);
+    if (input.amountNanoUsd <= 0n) throw this.invalid("debit amount must be greater than 0");
+    if (input.usageRecordId === void 0 && input.reason === void 0) {
+      throw this.invalid("a debit without a usageRecordId must carry a reason");
+    }
+    const entry = {
+      // Stryker disable next-line StringLiteral -- placeholder walletId; the store's insert always assigns the real wallet id and never reads this sentinel, so any string here is equivalent
+      walletId: "",
+      type: "debit",
+      amountNanoUsd: -input.amountNanoUsd,
+      priority: 0,
+      effectiveAt: /* @__PURE__ */ new Date(),
+      // Stryker disable next-line ConditionalExpression -- CE true: spreading { usageRecordId: undefined } is equivalent to {} because store and consumers check usageRecordId !== undefined
+      ...input.usageRecordId !== void 0 ? { usageRecordId: input.usageRecordId } : {},
+      idempotencyKey: input.idempotencyKey,
+      // Stryker disable next-line ConditionalExpression -- CE true: spreading { reason: undefined } is equivalent to {} because store and consumers check reason !== undefined
+      ...input.reason !== void 0 ? { reason: input.reason } : {}
+    };
+    const debited = await this.conditionalDebit(ref, entry, input.amountNanoUsd);
+    const balance = await this.store.getWallet(ref);
+    if (balance !== null && balance.balanceNanoUsd <= 0n) {
+      await this.events.depleted(ref, { walletId: debited.walletId, balanceNanoUsd: balance.balanceNanoUsd });
+    }
+    return debited;
+  }
+  /**
+   * Refund a previous debit (a plain `refund` credit entry). Never resurrects an
+   * expired grant — the credit is unallocated balance (§9.3). Refunds are always
+   * allowed (they can restore a negative balance).
+   *
+   * @param ref The wallet owner.
+   * @param input The refund amount (`> 0`), optional `usageRecordId`, key, and reason.
+   * @returns The appended refund entry.
+   */
+  async refund(ref, input) {
+    this.assertOwner(ref);
+    if (input.amountNanoUsd <= 0n) throw this.invalid("refund amount must be greater than 0");
+    return this.append(ref, {
+      type: "refund",
+      amountNanoUsd: input.amountNanoUsd,
+      priority: 0,
+      effectiveAt: /* @__PURE__ */ new Date(),
+      // Stryker disable next-line ConditionalExpression,ObjectLiteral -- CE true / OL {}: spreading { usageRecordId: undefined } is equivalent to {} because store and consumers check usageRecordId !== undefined
+      ...input.usageRecordId !== void 0 ? { usageRecordId: input.usageRecordId } : {},
+      idempotencyKey: input.idempotencyKey,
+      reason: input.reason
+    });
+  }
+  /**
+   * Signed manual correction (ADMIN PLANE — §14.4; the host MUST restrict this to
+   * privileged roles). A positive adjustment auto-creates the wallet. Emits
+   * `ai_tokens.audit`.
+   *
+   * @param ref The wallet owner.
+   * @param input The signed amount (`!= 0`), key, and reason.
+   * @returns The appended adjustment entry.
+   * @throws {AiTokensException} `AI_TOKENS_INVALID_CONFIG` on a zero amount / `'key'` owner.
+   */
+  async adjust(ref, input) {
+    this.assertOwner(ref);
+    if (input.amountNanoUsd === 0n) throw this.invalid("adjustment amount must not be 0");
+    const entry = await this.append(ref, {
+      type: "adjustment",
+      amountNanoUsd: input.amountNanoUsd,
+      priority: 0,
+      effectiveAt: /* @__PURE__ */ new Date(),
+      idempotencyKey: input.idempotencyKey,
+      reason: input.reason
+    });
+    await this.events.audit("ai_tokens.wallet.adjusted", {
+      tenantId: ref.tenantId,
+      walletId: entry.walletId,
+      entryId: entry.id,
+      amountNanoUsd: entry.amountNanoUsd.toString(),
+      reason: input.reason
+    });
+    return entry;
+  }
+  /**
+   * Apply an unconditional signed settlement adjustment — the capture ±delta vs a
+   * hold (§11.2). Unlike {@link debit} it NEVER blocks on the balance (capture must
+   * settle actuals even into overdraft) and unlike {@link adjust} it emits NO admin
+   * audit (it is a system settlement, not a manual correction). Appends an
+   * `adjustment` entry; a positive amount credits (refund of an over-reservation), a
+   * negative amount debits (top-up when actuals exceeded the estimate).
+   *
+   * @param ref The wallet owner.
+   * @param input The signed amount (`!= 0`), optional `usageRecordId`, key, and reason.
+   * @returns The appended adjustment entry.
+   * @throws {AiTokensException} `AI_TOKENS_INVALID_CONFIG` on a zero amount / `'key'` owner.
+   */
+  async settleAdjustment(ref, input) {
+    this.assertOwner(ref);
+    if (input.amountNanoUsd === 0n) throw this.invalid("settlement adjustment amount must not be 0");
+    return this.append(ref, {
+      type: "adjustment",
+      amountNanoUsd: input.amountNanoUsd,
+      priority: 0,
+      effectiveAt: /* @__PURE__ */ new Date(),
+      // Stryker disable next-line ConditionalExpression -- CE true: spreading { usageRecordId: undefined } is equivalent to {} because store and consumers check usageRecordId !== undefined
+      // Stryker disable next-line ConditionalExpression -- CE true: spreading { usageRecordId: undefined } is equivalent to {} because store and consumers check usageRecordId !== undefined
+      ...input.usageRecordId !== void 0 ? { usageRecordId: input.usageRecordId } : {},
+      idempotencyKey: input.idempotencyKey,
+      reason: input.reason
+    });
+  }
+  /**
+   * Paginated entry history with type/date filters — the transaction listing a
+   * usage meter renders.
+   *
+   * @param ref The wallet owner.
+   * @param filter Optional type/date filters and pagination.
+   * @returns A page of entries and the total match count.
+   */
+  async getEntries(ref, filter) {
+    this.assertOwner(ref);
+    return this.store.listEntries(ref, filter);
+  }
+  /**
+   * Recompute and repair the materialized balance from the entry ledger (§9.4).
+   * ADMIN PLANE (§14.4): the host MUST restrict this to privileged roles. Emits
+   * `ai_tokens.audit`.
+   *
+   * @param ref The wallet owner.
+   * @returns The reconciled wallet.
+   */
+  async reconcile(ref) {
+    this.assertOwner(ref);
+    const wallet = await this.store.reconcile(ref);
+    await this.events.audit("ai_tokens.wallet.reconciled", {
+      tenantId: ref.tenantId,
+      walletId: wallet.id,
+      balanceNanoUsd: wallet.balanceNanoUsd.toString()
+    });
+    return { nanoUsd: wallet.balanceNanoUsd, credits: this.toCredits(wallet.balanceNanoUsd) };
+  }
+  /** Append a non-debit entry, mapping a store idempotency/missing-wallet signal to the catalog. */
+  async append(ref, entry) {
+    try {
+      return await this.store.appendEntry(ref, { walletId: "", ...entry });
+    } catch (error) {
+      throw this.mapStoreError(error, ref, entry.idempotencyKey);
+    }
+  }
+  /** Run the atomic conditional debit, mapping `null` to insufficient credits (§9.4). */
+  async conditionalDebit(ref, entry, requested) {
+    let result;
+    try {
+      result = await this.store.conditionalDebit(ref, entry, this.options.overdraftNanoUsd);
+    } catch (error) {
+      throw this.mapStoreError(error, ref, entry.idempotencyKey);
+    }
+    if (result === null) {
+      const wallet = await this.store.getWallet(ref);
+      throw new AiTokensException("AI_TOKENS_INSUFFICIENT_CREDITS", void 0, {
+        balanceNanoUsd: (wallet?.balanceNanoUsd ?? 0n).toString(),
+        requestedNanoUsd: requested.toString()
+      });
+    }
+    return result;
+  }
+  /** Map a store idempotency conflict / missing-wallet signal to the typed catalog error. */
+  mapStoreError(error, ref, idempotencyKey) {
+    if (isLedgerIdempotencyConflict(error)) {
+      return new AiTokensException("AI_TOKENS_IDEMPOTENCY_CONFLICT", void 0, {
+        tenantId: ref.tenantId,
+        idempotencyKey
+      });
+    }
+    if (isWalletMissing(error)) {
+      return new AiTokensException("AI_TOKENS_INSUFFICIENT_CREDITS", void 0, { reason: "wallet does not exist" });
+    }
+    return error instanceof AiTokensException ? error : new AiTokensException("AI_TOKENS_STORE_ERROR", void 0, {});
+  }
+  /** Reject a `'key'` owner at runtime (`'key'` scopes cannot own money, §9.1). */
+  assertOwner(ref) {
+    if (ref.ownerType === "key") throw this.invalid("'key' scopes cannot own a wallet");
+  }
+  /** Present a nano-USD balance as credits (presentation-only division). */
+  toCredits(nanoUsd) {
+    return Number(nanoUsd) / Number(this.options.creditRateNanoUsd);
+  }
+  /** Build the invalid-config exception with an actionable reason. */
+  invalid(reason) {
+    return new AiTokensException("AI_TOKENS_INVALID_CONFIG", void 0, { reason });
+  }
+};
+WalletService = __decorateClass([
+  Injectable()
+], WalletService);
+function isWalletMissing(error) {
+  if (typeof error !== "object" || error === null) return false;
+  return error.isWalletMissing === true;
+}
+
+// src/server/services/budget-predicate.ts
+function recordConsumesBudget(record, budget, windowStart, windowEnd) {
+  if (!record.enforced) return false;
+  if (record.isSystemCost) return false;
+  if (!featureMatches2(budget.features, record.feature)) return false;
+  if (record.status !== "posted" && record.status !== "reversed") return false;
+  return record.occurredAt >= windowStart && (windowEnd === null || record.occurredAt < windowEnd);
+}
+function featureMatches2(features, feature) {
+  return features === void 0 || features.length === 0 || features.includes(feature);
+}
+
+// src/server/utils/window-anchor.ts
+var DAY_MS = 864e5;
+var WEEK_MS = DAY_MS * 7;
+function startOfUtcDay(at) {
+  return new Date(Date.UTC(at.getUTCFullYear(), at.getUTCMonth(), at.getUTCDate()));
+}
+function startOfUtcWeek(at) {
+  const day = startOfUtcDay(at);
+  return new Date(day.getTime() - day.getUTCDay() * DAY_MS);
+}
+function startOfUtcMonth(at) {
+  return new Date(Date.UTC(at.getUTCFullYear(), at.getUTCMonth(), 1));
+}
+function daysInUtcMonth(year, month) {
+  return new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+}
+function addMonthsClamped(anchor, months) {
+  const targetIndex = anchor.getUTCMonth() + months;
+  const year = anchor.getUTCFullYear() + Math.floor(targetIndex / 12);
+  const month = (targetIndex % 12 + 12) % 12;
+  const day = Math.min(anchor.getUTCDate(), daysInUtcMonth(year, month));
+  return new Date(
+    Date.UTC(year, month, day, anchor.getUTCHours(), anchor.getUTCMinutes(), anchor.getUTCSeconds(), anchor.getUTCMilliseconds())
+  );
+}
+function monthsBetween(anchor, windowStart) {
+  return (windowStart.getUTCFullYear() - anchor.getUTCFullYear()) * 12 + (windowStart.getUTCMonth() - anchor.getUTCMonth());
+}
+function anchoredMonthIndex(anchor, at) {
+  const estimate = monthsBetween(anchor, at);
+  return addMonthsClamped(anchor, estimate).getTime() <= at.getTime() ? estimate : estimate - 1;
+}
+function periodMsOf(window) {
+  if (window === "day") return DAY_MS;
+  if (window === "week") return WEEK_MS;
+  return window.customSeconds * 1e3;
+}
+function fixedWindowStart(anchor, periodMs, at) {
+  const k = Math.floor((at.getTime() - anchor.getTime()) / periodMs);
+  return new Date(anchor.getTime() + k * periodMs);
+}
+function windowStartFor(budget, at) {
+  if (budget.window === "total") return new Date((budget.anchorAt ?? budget.createdAt).getTime());
+  if (budget.window === "month") {
+    if (budget.anchorAt === void 0) return startOfUtcMonth(at);
+    return addMonthsClamped(budget.anchorAt, anchoredMonthIndex(budget.anchorAt, at));
+  }
+  if (budget.anchorAt !== void 0) return fixedWindowStart(budget.anchorAt, periodMsOf(budget.window), at);
+  if (budget.window === "day") return startOfUtcDay(at);
+  if (budget.window === "week") return startOfUtcWeek(at);
+  return fixedWindowStart(budget.createdAt, periodMsOf(budget.window), at);
+}
+function resetsAtFor(budget, windowStart) {
+  if (budget.window === "total") return null;
+  if (budget.window === "month") {
+    if (budget.anchorAt === void 0) {
+      return new Date(Date.UTC(windowStart.getUTCFullYear(), windowStart.getUTCMonth() + 1, 1));
+    }
+    return addMonthsClamped(budget.anchorAt, monthsBetween(budget.anchorAt, windowStart) + 1);
+  }
+  return new Date(windowStart.getTime() + periodMsOf(budget.window));
+}
+
+// src/server/services/budget.service.ts
+var ZERO_SPEND = { spentNanoUsd: 0n, spentTokens: 0, spentCount: 0 };
+var NOOP_BUDGET_HOOKS = {
+  thresholdCrossed: () => void 0,
+  exceeded: () => void 0,
+  projectedExceeded: () => void 0,
+  audit: () => void 0
+};
+var COUNTER_GRACE_SECONDS = 3600;
+var TOTAL_WINDOW_TTL_SECONDS = 60 * 60 * 24 * 400;
+var UNBOUNDED_COUNTER_LIMIT = 9223372036854775807n;
+var BudgetService = class {
+  /**
+   * @param store The budget persistence port.
+   * @param ledger The ledger service (reconcileWindow reads the source of truth).
+   * @param options The resolved budget settings (policy, thresholds, throttle callback).
+   * @param now The injected clock.
+   * @param events The event hooks; the module wires them to the dispatcher.
+   */
+  constructor(store, ledger, options, now = () => /* @__PURE__ */ new Date(), events = NOOP_BUDGET_HOOKS) {
+    this.store = store;
+    this.ledger = ledger;
+    this.options = options;
+    this.now = now;
+    this.events = events;
+  }
+  store;
+  ledger;
+  options;
+  now;
+  events;
+  logger = new Logger(BudgetService.name);
+  /** Highest soft-threshold emitted per `(budgetId, windowStartISO)` — per-instance dedupe (§20). */
+  notifiedThreshold = /* @__PURE__ */ new Map();
+  /** Windows that have already emitted a projected-exceeded event, per instance. */
+  projected = /* @__PURE__ */ new Set();
+  /**
+   * Create or replace a budget (ADMIN PLANE — §14.4; restrict to privileged roles).
+   * Applies the §10.2 normative validation and emits `ai_tokens.audit`.
+   *
+   * @param input The budget definition (`softThresholds`/`policy` default from options).
+   * @returns The stored budget.
+   * @throws {AiTokensException} `AI_TOKENS_INVALID_CONFIG` on a negative limit, no limit dimension, or a threshold outside `(0, 1]`.
+   */
+  async upsertBudget(input) {
+    this.assertLimits(input);
+    const softThresholds = input.softThresholds ?? [...this.options.alertThresholds];
+    for (const threshold of softThresholds) {
+      if (!(threshold > 0 && threshold <= 1)) throw invalid(`softThresholds must be within (0, 1], received ${String(threshold)}`);
+    }
+    const budget = await this.store.upsert({ ...input, softThresholds, policy: input.policy ?? this.options.defaultPolicy });
+    await this.events.audit("ai_tokens.budget.upserted", { tenantId: budget.tenantId, budgetId: budget.id });
+    return budget;
+  }
+  /**
+   * Delete a budget (ADMIN PLANE — §14.4). Emits `ai_tokens.audit`.
+   *
+   * @param budgetId The budget id.
+   * @param tenantId The owning tenant (audit context).
+   */
+  async removeBudget(budgetId, tenantId) {
+    await this.store.remove(budgetId);
+    await this.events.audit("ai_tokens.budget.removed", { tenantId, budgetId });
+  }
+  /**
+   * List budgets applicable to a scope (the exact scope plus tenant-wide budgets).
+   * Defaults to the tenant scope when no scope is supplied.
+   *
+   * @param tenantId The owning tenant.
+   * @param scope The scope to list for; defaults to tenant-wide.
+   * @returns The applicable budgets.
+   */
+  list(tenantId, scope) {
+    return this.store.findMatching(tenantId, scope ?? { type: "tenant", id: tenantId });
+  }
+  /**
+   * Force a fresh window now (or at `newWindowStart`) and re-anchor the budget so
+   * subsequent windows follow the new cycle (ADMIN PLANE — §14.4). Emits
+   * `ai_tokens.audit`.
+   *
+   * @param budgetId The budget id.
+   * @param newWindowStart The new window start; defaults to now.
+   * @throws {AiTokensException} `AI_TOKENS_INVALID_CONFIG` when the budget does not exist.
+   */
+  async rotateWindow(budgetId, newWindowStart) {
+    const budget = await this.requireBudget(budgetId);
+    const start = newWindowStart ?? this.now();
+    const windowStart = windowStartFor({ ...budget, anchorAt: start }, start);
+    await this.store.upsert({ ...budget, anchorAt: start });
+    await this.store.setWindowStart(budgetId, windowStart);
+    const counter = this.options.counter;
+    if (counter !== void 0) {
+      for (const dimension of counterDimensions({ nanoUsd: 1n, tokens: 1, count: 1 }, limitsOf(budget))) {
+        try {
+          await counter.reset(counterKey(budgetId, windowStart, dimension.name));
+        } catch {
+          this.logger.warn(`failed to reset budget counter for ${budgetId}`);
+        }
+      }
+    }
+    await this.events.audit("ai_tokens.budget.rotated", { tenantId: budget.tenantId, budgetId, windowStart: start.toISOString() });
+  }
+  /**
+   * Consume every matching budget for a metered call (§10.3/§10.8). `'block'`
+   * budgets use the atomic conditional consume and roll back all prior consumption
+   * on a shortfall (throwing the dimension's typed error); `'allow'`/`'throttle'`
+   * budgets record the spend and signal. Called by the hold/record enforcement paths.
+   *
+   * @param context The metering context (payer scope, feature — trusted input).
+   * @param delta The spend to consume across the three dimensions.
+   * @throws {AiTokensException} `AI_TOKENS_BUDGET_EXCEEDED` (402, cost) or `AI_TOKENS_QUOTA_EXCEEDED` (429, tokens/count) when a `'block'` budget is exhausted.
+   */
+  async consume(context, delta) {
+    const windows = await this.matchingWindows(context.tenantId, context.scope, context.feature);
+    const consumed = [];
+    for (const located of windows) {
+      const before = await this.store.getWindow(located.budget.id, located.windowStart) ?? ZERO_SPEND;
+      await this.applyConsumption(context, located, delta, before, consumed);
+    }
+  }
+  /**
+   * Release a previously-consumed delta across every matching budget (capture
+   * delta, hold release, reversal). Best-effort signed subtraction.
+   *
+   * @param context The metering context.
+   * @param delta The spend to release.
+   */
+  async release(context, delta) {
+    const windows = await this.matchingWindows(context.tenantId, context.scope, context.feature);
+    const counter = this.options.counter;
+    for (const located of windows) {
+      await this.store.adjustWindow(located.budget.id, located.windowStart, negate(delta));
+      if (counter !== void 0) {
+        for (const dimension of counterDimensions(delta, located.limits)) {
+          await this.decrCounters(counter, [{ key: counterKey(located.budget.id, located.windowStart, dimension.name), amount: dimension.amount }]);
+        }
+      }
+    }
+  }
+  /**
+   * Apply a SIGNED spend delta to every matching budget window WITHOUT enforcement
+   * — the capture settlement ±delta (§11.2). A positive delta records extra spend
+   * (actual above the hold estimate), a negative delta releases (actual below);
+   * capture NEVER re-blocks, so this never throws a budget/quota error. Keeps the
+   * live counter in sync (increment/decrement per dimension sign).
+   *
+   * @param context The metering context (payer scope, feature).
+   * @param delta The signed spend delta across the three dimensions.
+   */
+  async adjust(context, delta) {
+    const windows = await this.matchingWindows(context.tenantId, context.scope, context.feature);
+    const counter = this.options.counter;
+    for (const located of windows) {
+      const before = await this.store.getWindow(located.budget.id, located.windowStart) ?? ZERO_SPEND;
+      await this.store.adjustWindow(located.budget.id, located.windowStart, delta);
+      if (counter === void 0) continue;
+      const spends = dimensionSpends(addSpend(before, delta));
+      const ttl = counterTtlSeconds(located.windowStart, located.windowEnd);
+      for (const dimension of counterDimensions(delta, located.limits)) {
+        const key = counterKey(located.budget.id, located.windowStart, dimension.name);
+        await this.adjustCounter(counter, key, dimension.amount, spends[dimension.name], ttl);
+      }
+    }
+  }
+  /**
+   * Unconditionally move a live counter by a signed capture ±delta (never re-blocks).
+   * A positive move uses `incrIfBelow` against the int64 ceiling; a `false` result
+   * means the increment would overflow int64 (or the backend treats the ceiling as a
+   * hard cap), so the counter has DIVERGED from the authoritative DB window — it is
+   * then resynced to `authoritative` (the post-adjust window spend) rather than left
+   * holding a stale value the fast path would trust. A negative move decrements.
+   */
+  async adjustCounter(counter, key, amount, authoritative, ttl) {
+    try {
+      if (amount < 0n) {
+        await counter.decr(key, -amount);
+        return;
+      }
+      if (await counter.incrIfBelow(key, amount, UNBOUNDED_COUNTER_LIMIT, ttl)) return;
+      await this.resyncCounter(counter, key, authoritative, ttl);
+    } catch {
+      this.logger.warn(`failed to adjust budget counter ${key}`);
+    }
+  }
+  /** Discard a diverged counter and reseed it to the authoritative DB window spend (§10.8). */
+  async resyncCounter(counter, key, authoritative, ttl) {
+    await counter.reset(key);
+    await counter.incrIfBelow(key, authoritative, UNBOUNDED_COUNTER_LIMIT, ttl);
+    this.logger.warn(`budget counter ${key} overflowed the int64 ceiling; resynced to the database window spend`);
+  }
+  /**
+   * Recompute a window's counters from the ledger using the §10.7 predicate — the
+   * ledger is the reconcilable source of truth; the window row is a cache.
+   *
+   * @param budgetId The budget id.
+   * @param windowStart A window start for the budget.
+   */
+  async reconcileWindow(budgetId, windowStart) {
+    const budget = await this.requireBudget(budgetId);
+    const windowEnd = resetsAtFor(budget, windowStart);
+    const filter = { tenantId: budget.tenantId, from: windowStart, ...windowEnd !== null ? { to: windowEnd } : {} };
+    const records = await this.ledger.query(filter);
+    const computed = { spentNanoUsd: 0n, spentTokens: 0, spentCount: 0 };
+    for (const record of records) {
+      if (!recordConsumesBudget(record, budget, windowStart, windowEnd)) continue;
+      computed.spentNanoUsd += record.billedCostNanoUsd;
+      computed.spentTokens += record.totalTokens;
+      computed.spentCount += 1;
+    }
+    const current = await this.store.getWindow(budgetId, windowStart) ?? ZERO_SPEND;
+    await this.store.adjustWindow(budgetId, windowStart, {
+      nanoUsd: computed.spentNanoUsd - current.spentNanoUsd,
+      tokens: computed.spentTokens - current.spentTokens,
+      count: computed.spentCount - current.spentCount
+    });
+  }
+  /**
+   * The read-side "how much is left" query across every matching budget (§10.6) —
+   * the usage-meter data source. Reads live window rows (documented freshness
+   * trade-off; no counter read).
+   *
+   * @param tenantId The owning tenant.
+   * @param scope The scope to report for.
+   * @returns One {@link BudgetStatus} per matching budget.
+   * @example
+   * const budgets = await budgetService.status(tenantId, scope)
+   * res.json(toJsonSafe(budgets)) // bigint fields become decimal strings (§15.5)
+   */
+  async status(tenantId, scope) {
+    const budgets = await this.store.findMatching(tenantId, scope);
+    const statuses = [];
+    for (const budget of budgets) {
+      const windowStart = windowStartFor(budget, this.now());
+      const spend = await this.store.getWindow(budget.id, windowStart) ?? ZERO_SPEND;
+      statuses.push(buildStatus(budget, windowStart, resetsAtFor(budget, windowStart), spend));
+    }
+    return statuses;
+  }
+  /** Apply consumption for one located window (throws through {@link blockExceeded} on a hard shortfall). */
+  async applyConsumption(context, located, delta, before, consumed) {
+    let increments = [];
+    if (located.budget.policy === "block") {
+      const result = await this.guardedConsume(located, delta);
+      if (!result.ok) {
+        await this.rollback(consumed);
+        await this.blockExceeded(context, located, before, delta, result.failing);
+      }
+      increments = result.increments;
+    } else {
+      await this.store.adjustWindow(located.budget.id, located.windowStart, delta);
+      await this.softOverLimit(context, located, before, delta);
+    }
+    consumed.push({ budgetId: located.budget.id, windowStart: located.windowStart, delta, increments });
+    await this.signalThresholds(context, located, before, addSpend(before, delta));
+  }
+  /**
+   * The atomic §10.8 consume with the optional live-counter fast path and
+   * fail-closed fallback. With a counter bound, each limited dimension is checked
+   * cheaply via `incrIfBelow` FIRST (a reject touches no DB); on pass the DB
+   * conditional consume remains authoritative and rolls the counter back on a DB
+   * shortfall. A counter that is UNAVAILABLE falls back to the DB alone; if the DB
+   * is also down, `failClosed` blocks (else it allows with a warning). Without a
+   * counter it is the plain DB conditional consume.
+   */
+  async guardedConsume(located, delta) {
+    const counter = this.options.counter;
+    if (counter === void 0) {
+      return { ok: await this.store.conditionalConsume(located.budget.id, located.windowStart, delta, located.limits), increments: [] };
+    }
+    const fast = await this.counterFastPath(counter, located, delta);
+    if (fast.rejected) return { ok: false, increments: [], failing: fast.failing };
+    return this.databaseConsume(counter, located, delta, fast.increments, fast.available);
+  }
+  /**
+   * Try the live-counter fast path. On a hard reject it reports the FAILING dimension
+   * (whose `incrIfBelow` returned `false`) so the block raises the correct §16 code
+   * — a count/token quota is a 429, not the spend 402 the DB-window default would
+   * infer when the counter is ahead of the window row. Otherwise it reports the
+   * increments made and whether the counter was available (an outage falls back to DB).
+   */
+  async counterFastPath(counter, located, delta) {
+    const ttl = counterTtlSeconds(located.windowStart, located.windowEnd);
+    const increments = [];
+    try {
+      for (const dimension of counterDimensions(delta, located.limits)) {
+        const key = counterKey(located.budget.id, located.windowStart, dimension.name);
+        if (await counter.incrIfBelow(key, dimension.amount, dimension.limit, ttl)) {
+          increments.push({ key, amount: dimension.amount });
+          continue;
+        }
+        await this.decrCounters(counter, increments);
+        return { rejected: true, failing: dimensionCode(dimension.name) };
+      }
+      return { rejected: false, increments, available: true };
+    } catch {
+      await this.decrCounters(counter, increments);
+      this.logger.warn(`budget counter unavailable for ${located.budget.id}; falling back to the database`);
+      return { rejected: false, increments: [], available: false };
+    }
+  }
+  /** Run the authoritative DB consume, rolling the counter back on a shortfall and failing closed on an outage. */
+  async databaseConsume(counter, located, delta, increments, counterAvailable) {
+    try {
+      const ok = await this.store.conditionalConsume(located.budget.id, located.windowStart, delta, located.limits);
+      if (!ok) {
+        if (counterAvailable) await this.decrCounters(counter, increments);
+        return { ok: false, increments: [] };
+      }
+      return { ok: true, increments: counterAvailable ? increments : [] };
+    } catch {
+      if (counterAvailable) await this.decrCounters(counter, increments);
+      if (this.options.failClosed) throw new AiTokensException("AI_TOKENS_STORE_ERROR", void 0, {});
+      this.logger.warn(`budget store unavailable for ${located.budget.id}; allowing (failClosed disabled)`);
+      return { ok: true, increments: [] };
+    }
+  }
+  /** Best-effort counter decrement (rollback); failures are logged, never thrown. */
+  async decrCounters(counter, increments) {
+    for (const increment of increments) {
+      try {
+        await counter.decr(increment.key, increment.amount);
+      } catch {
+        this.logger.warn(`failed to roll back budget counter ${increment.key}`);
+      }
+    }
+  }
+  /**
+   * Emit `exceeded` and throw the dimension's typed error for a blocked budget. The
+   * failing dimension is threaded from the counter fast-path reject when it decided
+   * the block; the DB conditional-consume path passes none, so it defaults to the
+   * over-limit dimension of the DB window spend — both routes map to the same §16 code.
+   */
+  async blockExceeded(context, located, before, delta, failing = failingDimension(addSpend(before, delta), located.limits)) {
+    await this.events.exceeded(context.tenantId, located.budget.scope, {
+      budgetId: located.budget.id,
+      policy: "block",
+      dimension: failing.dimension,
+      limit: limitSnapshot(located.limits),
+      spent: spendSnapshot(before),
+      resetsAt: located.windowEnd
+    });
+    throw new AiTokensException(failing.code, void 0, { budgetId: located.budget.id, dimension: failing.dimension });
+  }
+  /** Signal an over-limit `'allow'`/`'throttle'` budget (records spend, never throws). */
+  async softOverLimit(context, located, before, delta) {
+    const failing = failingDimensionOrNull(addSpend(before, delta), located.limits);
+    if (failing === null) return;
+    if (located.budget.policy === "throttle") {
+      await this.throttle(context, located, before);
+      return;
+    }
+    await this.events.exceeded(context.tenantId, located.budget.scope, {
+      budgetId: located.budget.id,
+      policy: "allow",
+      dimension: failing.dimension,
+      limit: limitSnapshot(located.limits),
+      spent: spendSnapshot(before),
+      resetsAt: located.windowEnd
+    });
+  }
+  /** Invoke the host throttle callback (or warn + allow when none is configured). */
+  async throttle(context, located, before) {
+    const status = buildStatus(located.budget, located.windowStart, located.windowEnd, before);
+    if (this.options.onThrottle === void 0) {
+      this.logger.warn(`budget ${located.budget.id} exceeded with policy 'throttle' but no onThrottle callback is configured`);
+      return;
+    }
+    await this.options.onThrottle({ context, budget: located.budget, status });
+  }
+  /** Emit each soft threshold crossed by this delta, once per window (per-instance dedupe). */
+  async signalThresholds(context, located, before, after) {
+    const key = windowKey(located.budget.id, located.windowStart);
+    const fractionBefore = usedFraction(before, located.limits);
+    const fractionAfter = usedFraction(after, located.limits);
+    const emitted = this.notifiedThreshold.get(key) ?? 0;
+    let highest = emitted;
+    for (const threshold of [...located.budget.softThresholds].sort((a, b) => a - b)) {
+      if (threshold > emitted && threshold > fractionBefore && threshold <= fractionAfter) {
+        await this.emitThreshold(context, located, threshold, fractionAfter, after);
+        highest = threshold;
+      }
+    }
+    if (highest > emitted) this.notifiedThreshold.set(key, highest);
+    await this.signalProjection(context, located, fractionAfter);
+  }
+  /** Emit one `threshold_crossed` event. */
+  emitThreshold(context, located, threshold, fraction, after) {
+    return this.events.thresholdCrossed(context.tenantId, located.budget.scope, {
+      budgetId: located.budget.id,
+      threshold,
+      usedFraction: fraction,
+      limit: limitSnapshot(located.limits),
+      spent: spendSnapshot(after),
+      remaining: remainingSnapshot(located.limits, after),
+      resetsAt: located.windowEnd
+    });
+  }
+  /** Emit `projected_exceeded` once per window when the burn rate projects crossing before reset. */
+  async signalProjection(context, located, fraction) {
+    if (located.windowEnd === null || fraction <= 0 || fraction >= 1) return;
+    const key = windowKey(located.budget.id, located.windowStart);
+    if (this.projected.has(key)) return;
+    const elapsedMs = this.now().getTime() - located.windowStart.getTime();
+    if (elapsedMs <= 0) return;
+    const projectedAt = new Date(located.windowStart.getTime() + elapsedMs / fraction);
+    if (projectedAt >= located.windowEnd) return;
+    this.projected.add(key);
+    await this.events.projectedExceeded(context.tenantId, located.budget.scope, {
+      budgetId: located.budget.id,
+      projectedAt,
+      usedFraction: fraction,
+      resetsAt: located.windowEnd
+    });
+  }
+  /** The matching, feature-relevant budgets located in the current window. */
+  async matchingWindows(tenantId, scope, feature) {
+    const budgets = await this.store.findMatching(tenantId, scope);
+    const now = this.now();
+    return budgets.filter((budget) => featureMatches3(budget.features, feature)).map((budget) => {
+      const windowStart = windowStartFor(budget, now);
+      return { budget, windowStart, windowEnd: resetsAtFor(budget, windowStart), limits: limitsOf(budget) };
+    });
+  }
+  /** Undo every recorded consumption (signed DB subtraction + live-counter decrement). */
+  async rollback(consumed) {
+    const counter = this.options.counter;
+    for (const entry of consumed) {
+      await this.store.adjustWindow(entry.budgetId, entry.windowStart, negate(entry.delta));
+      if (counter !== void 0) await this.decrCounters(counter, entry.increments);
+    }
+  }
+  /** Load a budget by id or throw an invalid-config error. */
+  async requireBudget(budgetId) {
+    const budget = await this.store.findBudgetById(budgetId);
+    if (budget === null) throw invalid(`budget ${budgetId} does not exist`);
+    return budget;
+  }
+  /** Validate the §10.2 limit rules: no negatives and at least one limit dimension. */
+  assertLimits(input) {
+    for (const [name, value] of [
+      ["limitNanoUsd", input.limitNanoUsd],
+      ["limitTokens", input.limitTokens],
+      ["limitCount", input.limitCount]
+    ]) {
+      if (value !== void 0 && value < 0) throw invalid(`${name} must not be negative (\xA710.2)`);
+    }
+    if (input.limitNanoUsd === void 0 && input.limitTokens === void 0 && input.limitCount === void 0) {
+      throw invalid("a budget must define at least one limit dimension");
+    }
+  }
+};
+BudgetService = __decorateClass([
+  Injectable()
+], BudgetService);
+function invalid(reason) {
+  return new AiTokensException("AI_TOKENS_INVALID_CONFIG", void 0, { reason });
+}
+function featureMatches3(features, feature) {
+  return features === void 0 || features.length === 0 || features.includes(feature);
+}
+function limitsOf(budget) {
+  return {
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { nanoUsd: undefined } is equivalent to {} because all consumers check limits.nanoUsd !== undefined
+    ...budget.limitNanoUsd !== void 0 ? { nanoUsd: budget.limitNanoUsd } : {},
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { tokens: undefined } is equivalent to {} because all consumers check limits.tokens !== undefined
+    ...budget.limitTokens !== void 0 ? { tokens: budget.limitTokens } : {},
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { count: undefined } is equivalent to {} because all consumers check limits.count !== undefined
+    ...budget.limitCount !== void 0 ? { count: budget.limitCount } : {}
+  };
+}
+function negate(delta) {
+  return { nanoUsd: -delta.nanoUsd, tokens: -delta.tokens, count: -delta.count };
+}
+function addSpend(spend, delta) {
+  return {
+    spentNanoUsd: spend.spentNanoUsd + delta.nanoUsd,
+    spentTokens: spend.spentTokens + delta.tokens,
+    spentCount: spend.spentCount + delta.count
+  };
+}
+function dimensionCode(name) {
+  return name === "cost" ? { dimension: "cost", code: "AI_TOKENS_BUDGET_EXCEEDED" } : { dimension: name, code: "AI_TOKENS_QUOTA_EXCEEDED" };
+}
+function failingDimension(spend, limits) {
+  return failingDimensionOrNull(spend, limits) ?? dimensionCode("cost");
+}
+function failingDimensionOrNull(spend, limits) {
+  if (limits.nanoUsd !== void 0 && spend.spentNanoUsd > limits.nanoUsd) return dimensionCode("cost");
+  if (limits.tokens !== void 0 && spend.spentTokens > limits.tokens) return dimensionCode("tokens");
+  if (limits.count !== void 0 && spend.spentCount > limits.count) return dimensionCode("count");
+  return null;
+}
+var USED_FRACTION_SCALE = 1000000n;
+function usedFraction(spend, limits) {
+  const fractions = [];
+  if (limits.nanoUsd !== void 0) fractions.push(ratio(spend.spentNanoUsd, limits.nanoUsd));
+  if (limits.tokens !== void 0) fractions.push(ratio(BigInt(spend.spentTokens), BigInt(limits.tokens)));
+  if (limits.count !== void 0) fractions.push(ratio(BigInt(spend.spentCount), BigInt(limits.count)));
+  return fractions.length === 0 ? 0 : Math.max(...fractions);
+}
+function ratio(spent, limit) {
+  if (limit === 0n) return spent > 0n ? Number.POSITIVE_INFINITY : 1;
+  return Number(spent * USED_FRACTION_SCALE / limit) / Number(USED_FRACTION_SCALE);
+}
+function limitSnapshot(limits) {
+  return {
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { nanoUsd: undefined } is equivalent to {} for event consumers who check field !== undefined
+    ...limits.nanoUsd !== void 0 ? { nanoUsd: limits.nanoUsd } : {},
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { tokens: undefined } is equivalent to {} for event consumers who check field !== undefined
+    ...limits.tokens !== void 0 ? { tokens: limits.tokens } : {},
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { count: undefined } is equivalent to {} for event consumers who check field !== undefined
+    ...limits.count !== void 0 ? { count: limits.count } : {}
+  };
+}
+function spendSnapshot(spend) {
+  return { nanoUsd: spend.spentNanoUsd, tokens: spend.spentTokens, count: spend.spentCount };
+}
+function remainingSnapshot(limits, spend) {
+  return {
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { nanoUsd: undefined } is equivalent to {} for event consumers who check field !== undefined
+    ...limits.nanoUsd !== void 0 ? { nanoUsd: max0(limits.nanoUsd - spend.spentNanoUsd) } : {},
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { tokens: undefined } is equivalent to {} for event consumers who check field !== undefined
+    ...limits.tokens !== void 0 ? { tokens: Math.max(0, limits.tokens - spend.spentTokens) } : {},
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { count: undefined } is equivalent to {} for event consumers who check field !== undefined
+    ...limits.count !== void 0 ? { count: Math.max(0, limits.count - spend.spentCount) } : {}
+  };
+}
+function buildStatus(budget, windowStart, resetsAt, spend) {
+  const limits = limitsOf(budget);
+  return {
+    budgetId: budget.id,
+    // Stryker disable next-line ConditionalExpression -- CE true: spreading { features: undefined } is equivalent to {} because status consumers check features !== undefined
+    ...budget.features !== void 0 ? { features: budget.features } : {},
+    window: budget.window,
+    windowStart,
+    resetsAt,
+    policy: budget.policy,
+    limit: limitSnapshot(limits),
+    spent: spendSnapshot(spend),
+    remaining: remainingSnapshot(limits, spend),
+    usedFraction: usedFraction(spend, limits)
+  };
+}
+function windowKey(budgetId, windowStart) {
+  return `${budgetId}|${windowStart.toISOString()}`;
+}
+function counterKey(budgetId, windowStart, dimension) {
+  return `ai_tokens:budget:${budgetId}:${windowStart.toISOString()}:${dimension}`;
+}
+function counterTtlSeconds(windowStart, windowEnd) {
+  if (windowEnd === null) return TOTAL_WINDOW_TTL_SECONDS;
+  return Math.ceil((windowEnd.getTime() - windowStart.getTime()) / 1e3) + COUNTER_GRACE_SECONDS;
+}
+function dimensionSpends(spend) {
+  return { cost: spend.spentNanoUsd, tokens: BigInt(spend.spentTokens), count: BigInt(spend.spentCount) };
+}
+function counterDimensions(delta, limits) {
+  const dimensions = [];
+  if (limits.nanoUsd !== void 0 && delta.nanoUsd !== 0n) {
+    dimensions.push({ name: "cost", amount: delta.nanoUsd, limit: limits.nanoUsd });
+  }
+  if (limits.tokens !== void 0 && delta.tokens !== 0) {
+    dimensions.push({ name: "tokens", amount: BigInt(delta.tokens), limit: BigInt(limits.tokens) });
+  }
+  if (limits.count !== void 0 && delta.count !== 0) {
+    dimensions.push({ name: "count", amount: BigInt(delta.count), limit: BigInt(limits.count) });
+  }
+  return dimensions;
+}
+function max0(value) {
+  return value < 0n ? 0n : value;
+}
+var BALANCE_STATUSES2 = ["posted", "reversed"];
+var PER_MILLION2 = 1000000n;
+var NANO_PER_USD2 = 1000000000n;
+var UsageReportService = class {
+  /**
+   * @param store The ledger store port (query + optional SQL summarize).
+   * @param pricing The pricing store port (effective rate for cache savings).
+   * @param options The resolved currency/fx/reporting settings.
+   * @param audit The audit hook; the module wires it to the dispatcher.
+   */
+  constructor(store, pricing, options, audit = () => void 0) {
+    this.store = store;
+    this.pricing = pricing;
+    this.options = options;
+    this.audit = audit;
+  }
+  store;
+  pricing;
+  options;
+  audit;
+  /**
+   * Aggregate `SUM … GROUP BY` across the report dimensions. Delegates to the
+   * store's SQL `summarize` when present, else aggregates in memory. The in-memory
+   * fallback REFUSES to emit partial totals: like `export()` it throws when the
+   * filter matches more than `reporting.maxExportRows` rows (paginate instead) — a
+   * silent truncation would hand callers incorrect aggregates. An empty `groupBy`
+   * yields one grand-total row.
+   *
+   * @param input The report filter plus the group-by dimensions.
+   * @returns One {@link UsageSummary} per group.
+   * @throws {AiTokensException} `AI_TOKENS_INVALID_CONFIG` when the matched rows exceed `reporting.maxExportRows`.
+   */
+  async summarize(input) {
+    const { groupBy, ...filter } = input;
+    const max = this.options.reporting.maxExportRows;
+    if (this.store.summarize !== void 0) return this.store.summarize(toLedgerFilter(filter, max), groupBy);
+    const records = await this.store.query(toLedgerFilter(filter, max + 1));
+    this.assertWithinMaxRows(records.length, "summarize");
+    const groups = /* @__PURE__ */ new Map();
+    for (const record of records) {
+      const savings = await this.cacheSavings(record);
+      for (const group of expandGroups(record, groupBy)) {
+        const key = JSON.stringify(group);
+        const summary = groups.get(key) ?? emptySummary(group);
+        accumulate(summary, record, savings);
+        groups.set(key, summary);
+      }
+    }
+    return [...groups.values()];
+  }
+  /**
+   * Stream the §13.2 export field set as CSV or line-delimited JSON, bigints as
+   * decimal strings, plus fx-converted columns for a non-USD currency. Emits an
+   * `ai_tokens.audit` event. ADMIN PLANE (§14.4): restrict to privileged roles.
+   *
+   * @param filter The report filter.
+   * @param format `'csv'` or `'json'` (ndjson).
+   * @returns A readable stream of the export.
+   * @throws {AiTokensException} `AI_TOKENS_INVALID_CONFIG` when the result exceeds `reporting.maxExportRows`.
+   */
+  async export(filter, format) {
+    const max = this.options.reporting.maxExportRows;
+    const records = await this.store.query(toLedgerFilter(filter, max + 1));
+    this.assertWithinMaxRows(records.length, "export");
+    this.audit("ai_tokens.audit", { action: "export", tenantId: filter.tenantId, format, rows: records.length });
+    return Readable.from(this.serialize(records, format));
+  }
+  /**
+   * Refuse a partial result: throw when a `maxExportRows + 1`-bounded query matched
+   * more rows than `reporting.maxExportRows`, signaling the caller to paginate. Both
+   * `summarize()` and `export()` share this guard so neither ever silently truncates.
+   *
+   * @param rowCount The number of rows the `(max + 1)`-bounded query returned.
+   * @param operation The operation name for the error reason (`summarize`/`export`).
+   * @throws {AiTokensException} `AI_TOKENS_INVALID_CONFIG` when `rowCount` exceeds the limit.
+   */
+  assertWithinMaxRows(rowCount, operation) {
+    const max = this.options.reporting.maxExportRows;
+    if (rowCount > max) {
+      throw new AiTokensException("AI_TOKENS_INVALID_CONFIG", void 0, { reason: `${operation} exceeds reporting.maxExportRows (${String(max)}); paginate the filter` });
+    }
+  }
+  /** Yield the serialized rows (CSV header + rows, or ndjson lines). */
+  async *serialize(records, format) {
+    const converting = this.options.currency !== "USD" && this.options.fx !== void 0;
+    if (format === "csv") yield `${csvLine(this.headers(converting))}
+`;
+    for (const record of records) {
+      const row = await this.rowOf(record, converting);
+      yield format === "csv" ? `${csvLine(row.map((cell) => cell[1]))}
+` : `${JSON.stringify(Object.fromEntries(row))}
+`;
+    }
+  }
+  /** The ordered header names for the export (with fx columns when converting). */
+  headers(converting) {
+    const base = baseCells(exampleRecord).map((cell) => cell[0]);
+    return converting ? [...base, "presentationCurrency", "rawCostConverted", "surchargeConverted", "billedCostConverted"] : base;
+  }
+  /** Build one export row as ordered `[header, cell]` pairs (all cells strings). */
+  async rowOf(record, converting) {
+    const cells = baseCells(record);
+    if (!converting || this.options.fx === void 0) return cells;
+    const rate = await this.options.fx(record.occurredAt, this.options.currency);
+    return [
+      ...cells,
+      ["presentationCurrency", this.options.currency],
+      ["rawCostConverted", convert2(record.rawCostNanoUsd, rate).toString()],
+      ["surchargeConverted", convert2(record.surchargeNanoUsd, rate).toString()],
+      ["billedCostConverted", convert2(record.billedCostNanoUsd, rate).toString()]
+    ];
+  }
+  /** The nano-USD cache savings for a record: `cacheReadTokens × (inputRate − cacheReadRate)`. */
+  async cacheSavings(record) {
+    if (record.priceVersionId === null) return 0n;
+    const rate = await this.pricing.resolveRate(record.provider, record.model, record.operation, record.serviceTier, record.occurredAt);
+    if (rate === null) return 0n;
+    return BigInt(record.cacheReadTokens) * (rate.inputNanoUsdPerMillion - rate.cacheReadNanoUsdPerMillion) / PER_MILLION2;
+  }
+};
+UsageReportService = __decorateClass([
+  Injectable()
+], UsageReportService);
+function toLedgerFilter(filter, limit) {
+  return {
+    tenantId: filter.tenantId,
+    // Stryker disable next-line ConditionalExpression -- spreading { scope: undefined } is equivalent to {} because InMemoryLedgerStore uses truthiness; the 'false' variant is covered by the scope isolation test
+    ...filter.scope !== void 0 ? { scope: filter.scope } : {},
+    // Stryker disable next-line ConditionalExpression -- spreading { beneficiary: undefined } is equivalent to {} for the same reason
+    ...filter.beneficiary !== void 0 ? { beneficiary: filter.beneficiary } : {},
+    // Stryker disable next-line ConditionalExpression -- spreading { feature: undefined } does not change the !== undefined check in matches()
+    ...filter.feature !== void 0 ? { feature: filter.feature } : {},
+    // Stryker disable next-line ConditionalExpression -- spreading { features: undefined } does not change the truthiness check in matches()
+    ...filter.features !== void 0 ? { features: filter.features } : {},
+    // Stryker disable next-line ConditionalExpression -- spreading { provider: undefined } does not change the !== undefined check in matches()
+    ...filter.provider !== void 0 ? { provider: filter.provider } : {},
+    // Stryker disable next-line ConditionalExpression -- spreading { model: undefined } does not change the !== undefined check in matches()
+    ...filter.model !== void 0 ? { model: filter.model } : {},
+    // Stryker disable next-line ConditionalExpression -- spreading { operation: undefined } does not change the !== undefined check in matches()
+    ...filter.operation !== void 0 ? { operation: filter.operation } : {},
+    // Stryker disable next-line ConditionalExpression -- spreading { serviceTier: undefined } does not change the !== undefined check in matches()
+    ...filter.serviceTier !== void 0 ? { serviceTier: filter.serviceTier } : {},
+    // Stryker disable next-line ConditionalExpression -- spreading { tags: undefined } does not change the truthiness check in matches()
+    ...filter.tags !== void 0 ? { tags: filter.tags } : {},
+    // Stryker disable next-line ConditionalExpression -- spreading { isSystemCost: undefined } does not change the !== undefined check in matches()
+    ...filter.isSystemCost !== void 0 ? { isSystemCost: filter.isSystemCost } : {},
+    // Stryker disable next-line ConditionalExpression -- spreading { systemCostCategory: undefined } does not change the !== undefined check in matches()
+    ...filter.systemCostCategory !== void 0 ? { systemCostCategory: filter.systemCostCategory } : {},
+    // Stryker disable next-line ConditionalExpression -- spreading { enforcedOnly: undefined } does not change the === true check in matches()
+    ...filter.enforcedOnly !== void 0 ? { enforcedOnly: filter.enforcedOnly } : {},
+    status: filter.status ?? [...BALANCE_STATUSES2],
+    from: filter.from,
+    to: filter.to,
+    limit
+  };
+}
+function expandGroups(record, groupBy) {
+  const base = {};
+  for (const dim of groupBy) {
+    if (dim !== "tag") base[dim] = dimensionValue(record, dim);
+  }
+  if (!groupBy.includes("tag")) return [base];
+  return record.tags.map((tag) => ({ ...base, tag }));
+}
+function dimensionValue(record, dim) {
+  switch (dim) {
+    case "day":
+      return record.occurredAt.toISOString().slice(0, 10);
+    case "week":
+      return weekStartUtc(record.occurredAt);
+    case "month":
+      return record.occurredAt.toISOString().slice(0, 7);
+    case "feature":
+      return record.feature;
+    case "provider":
+      return record.provider;
+    case "model":
+      return record.model;
+    case "operation":
+      return record.operation;
+    case "serviceTier":
+      return record.serviceTier;
+    case "scope":
+      return `${record.scope.type}:${record.scope.id}`;
+    case "beneficiary":
+      return record.beneficiary === void 0 ? "" : `${record.beneficiary.type}:${record.beneficiary.id}`;
+    default:
+      return record.systemCostCategory ?? "";
+  }
+}
+function weekStartUtc(date) {
+  const utc = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+  const isoDay = (utc.getUTCDay() + 6) % 7;
+  utc.setUTCDate(utc.getUTCDate() - isoDay);
+  return utc.toISOString().slice(0, 10);
+}
+function emptySummary(group) {
+  const tokens = Object.fromEntries(TOKEN_CATEGORIES.map((category) => [category, 0]));
+  return { group, records: 0, totalTokens: 0, tokens, rawCostNanoUsd: 0n, surchargeNanoUsd: 0n, billedCostNanoUsd: 0n, cacheSavingsNanoUsd: 0n };
+}
+function accumulate(summary, record, savings) {
+  summary.records += 1;
+  summary.totalTokens += record.totalTokens;
+  for (const category of TOKEN_CATEGORIES) summary.tokens[category] += record[`${category}Tokens`];
+  summary.rawCostNanoUsd += record.rawCostNanoUsd;
+  summary.surchargeNanoUsd += record.surchargeNanoUsd;
+  summary.billedCostNanoUsd += record.billedCostNanoUsd;
+  summary.cacheSavingsNanoUsd += savings;
+}
+function convert2(nanoUsd, fxRate) {
+  return nanoUsd * fxRate / NANO_PER_USD2;
+}
+function csvLine(cells) {
+  return cells.map((cell) => /[",\n]/.test(cell) ? `"${cell.replace(/"/g, '""')}"` : cell).join(",");
+}
+function baseCells(record) {
+  return [
+    ["tenantId", record.tenantId],
+    ["scopeType", record.scope.type],
+    ["scopeId", record.scope.id],
+    ["beneficiaryType", record.beneficiary?.type ?? ""],
+    ["beneficiaryId", record.beneficiary?.id ?? ""],
+    ["requestedBy", record.requestedBy ?? ""],
+    ["feature", record.feature],
+    ["tags", record.tags.join(";")],
+    ["provider", record.provider],
+    ["model", record.model],
+    ["requestedModel", record.requestedModel ?? ""],
+    ["operation", record.operation],
+    ["serviceTier", record.serviceTier],
+    ...TOKEN_CATEGORIES.map((category) => [`${category}Tokens`, String(record[`${category}Tokens`])]),
+    ["totalTokens", String(record.totalTokens)],
+    ["extraUnits", record.extraUnits === void 0 ? "" : JSON.stringify(record.extraUnits)],
+    ["rawCostNanoUsd", record.rawCostNanoUsd.toString()],
+    ["surchargeNanoUsd", record.surchargeNanoUsd.toString()],
+    ["billedCostNanoUsd", record.billedCostNanoUsd.toString()],
+    ["markupMultiplier", String(record.markupMultiplier)],
+    ["currency", record.currency],
+    ["priceMissing", String(record.priceMissing)],
+    ["occurredAt", record.occurredAt.toISOString()],
+    ["idempotencyKey", record.idempotencyKey],
+    ["correlationId", record.correlationId ?? ""],
+    ["requestId", record.requestId ?? ""],
+    ["isSystemCost", String(record.isSystemCost)],
+    ["systemCostCategory", record.systemCostCategory ?? ""],
+    ["enforced", String(record.enforced)],
+    ["status", record.status]
+  ];
+}
+var exampleRecord = {
+  id: "",
+  tenantId: "",
+  scope: { type: "tenant", id: "" },
+  provider: "",
+  model: "",
+  operation: "chat",
+  serviceTier: "standard",
+  feature: "",
+  tags: [],
+  inputTokens: 0,
+  outputTokens: 0,
+  cacheReadTokens: 0,
+  cacheWrite5mTokens: 0,
+  cacheWrite1hTokens: 0,
+  reasoningTokens: 0,
+  audioInTokens: 0,
+  audioOutTokens: 0,
+  imageInTokens: 0,
+  imageOutTokens: 0,
+  totalTokens: 0,
+  priceVersionId: null,
+  rawCostNanoUsd: 0n,
+  surchargeNanoUsd: 0n,
+  billedCostNanoUsd: 0n,
+  markupMultiplier: 1,
+  currency: "USD",
+  priceMissing: false,
+  status: "posted",
+  idempotencyKey: "",
+  isSystemCost: false,
+  enforced: false,
+  occurredAt: /* @__PURE__ */ new Date(0),
+  createdAt: /* @__PURE__ */ new Date(0),
+  updatedAt: /* @__PURE__ */ new Date(0)
+};
+
+// src/server/bymax-ai-tokens.module.ts
+var CORE_TOKENS = [
+  BYMAX_AI_TOKENS_OPTIONS,
+  BYMAX_AI_TOKENS_LEDGER_STORE,
+  BYMAX_AI_TOKENS_PRICING_STORE,
+  BYMAX_AI_TOKENS_TOKENIZER,
+  BYMAX_AI_TOKENS_EVENT_SINK,
+  BYMAX_AI_TOKENS_TELEMETRY,
+  BYMAX_AI_TOKENS_CONTENT_STORE,
+  BYMAX_AI_TOKENS_LOGGER
+];
+var CORE_SERVICE_EXPORTS = [PricingService, LedgerService, MeteringService, MeteringInterceptor, UsageReportService];
+var FEATURE_EXPORTS = [BYMAX_AI_TOKENS_WALLET_STORE, BYMAX_AI_TOKENS_BUDGET_STORE, BYMAX_AI_TOKENS_BUDGET_COUNTER, WalletService, BudgetService, BudgetGuard];
+function fromOptions(token, factory) {
+  return { provide: token, useFactory: factory, inject: [BYMAX_AI_TOKENS_OPTIONS] };
+}
+function buildCoreProviders() {
+  return [...buildInfraProviders(), ...buildServiceProviders()];
+}
+function buildInfraProviders() {
+  return [
+    fromOptions(BYMAX_AI_TOKENS_LEDGER_STORE, (o) => o.store),
+    fromOptions(BYMAX_AI_TOKENS_PRICING_STORE, (o) => o.store),
+    fromOptions(BYMAX_AI_TOKENS_TOKENIZER, (o) => o.tokenizer ?? null),
+    fromOptions(BYMAX_AI_TOKENS_EVENT_SINK, (o) => o.events.sink ?? null),
+    fromOptions(BYMAX_AI_TOKENS_TELEMETRY, (o) => o.telemetry.enabled ? o.telemetry.sink : null),
+    fromOptions(BYMAX_AI_TOKENS_CONTENT_STORE, (o) => o.content.enabled ? o.content.store : null),
+    { provide: BYMAX_AI_TOKENS_LOGGER, useValue: null },
+    {
+      provide: PricingService,
+      useFactory: (options, store) => new PricingService(options, store),
+      inject: [BYMAX_AI_TOKENS_OPTIONS, BYMAX_AI_TOKENS_PRICING_STORE]
+    },
+    {
+      provide: EventDispatcher,
+      useFactory: (moduleRef, options) => new EventDispatcher(moduleRef, options),
+      inject: [ModuleRef, BYMAX_AI_TOKENS_OPTIONS]
+    },
+    {
+      provide: LedgerService,
+      useFactory: (options, store, dispatcher) => new LedgerService(store, options, createLedgerAuditHook(dispatcher)),
+      inject: [BYMAX_AI_TOKENS_OPTIONS, BYMAX_AI_TOKENS_LEDGER_STORE, EventDispatcher]
+    },
+    {
+      provide: MarkupResolver,
+      useFactory: (options) => new MarkupResolver(options),
+      inject: [BYMAX_AI_TOKENS_OPTIONS]
+    }
+  ];
+}
+function buildServiceProviders() {
+  return [
+    {
+      provide: MeteringService,
+      useFactory: (ledger, pricing, markup, options, dispatcher, telemetrySink, wallets, budgets) => new MeteringService(ledger, pricing, markup, options, createMeteringEventHooks(dispatcher), wallets, budgets, void 0, new TelemetryEmitter(telemetrySink), new ContentCapture(options.content)),
+      inject: [
+        LedgerService,
+        PricingService,
+        MarkupResolver,
+        BYMAX_AI_TOKENS_OPTIONS,
+        EventDispatcher,
+        BYMAX_AI_TOKENS_TELEMETRY,
+        { token: WalletService, optional: true },
+        { token: BudgetService, optional: true }
+      ]
+    },
+    {
+      // Registered unconditionally: hold() writes pending rows whenever it is used,
+      // even without wallets/budgets, and a stranded hold must still be reclaimed.
+      provide: HoldReaper,
+      useFactory: (ledger, metering, options) => new HoldReaper(ledger, metering, options),
+      inject: [LedgerService, MeteringService, BYMAX_AI_TOKENS_OPTIONS]
+    },
+    {
+      provide: UsageReportService,
+      useFactory: (options, ledgerStore, pricingStore, dispatcher) => new UsageReportService(ledgerStore, pricingStore, options, (action, details) => void dispatcher.audit(action, details)),
+      inject: [BYMAX_AI_TOKENS_OPTIONS, BYMAX_AI_TOKENS_LEDGER_STORE, BYMAX_AI_TOKENS_PRICING_STORE, EventDispatcher]
+    },
+    MeteringInterceptor
+  ];
+}
+function walletServiceProvider() {
+  return {
+    provide: WalletService,
+    useFactory: (options, store, dispatcher) => options.wallets.enabled ? new WalletService(store, options.wallets, createWalletEventHooks(dispatcher)) : null,
+    inject: [BYMAX_AI_TOKENS_OPTIONS, BYMAX_AI_TOKENS_WALLET_STORE, EventDispatcher]
+  };
+}
+function budgetServiceProvider() {
+  return {
+    provide: BudgetService,
+    useFactory: (options, store, ledger, dispatcher) => options.budgets.enabled ? new BudgetService(store, ledger, options.budgets, void 0, createBudgetEventHooks(dispatcher)) : null,
+    inject: [BYMAX_AI_TOKENS_OPTIONS, BYMAX_AI_TOKENS_BUDGET_STORE, LedgerService, EventDispatcher]
+  };
+}
+function budgetGuardProvider() {
+  return {
+    provide: BudgetGuard,
+    useFactory: (options, budgets, metering, reflector) => options.budgets.enabled ? new BudgetGuard(budgets, metering, reflector, options) : null,
+    inject: [BYMAX_AI_TOKENS_OPTIONS, BudgetService, MeteringService, Reflector]
+  };
+}
+function buildSyncFeatureProviders(resolved) {
+  const providers = [];
+  if (resolved.wallets.enabled) {
+    providers.push({ provide: BYMAX_AI_TOKENS_WALLET_STORE, useValue: resolved.store }, walletServiceProvider());
+  }
+  if (resolved.budgets.enabled) {
+    providers.push(
+      { provide: BYMAX_AI_TOKENS_BUDGET_STORE, useValue: resolved.store },
+      { provide: BYMAX_AI_TOKENS_BUDGET_COUNTER, useValue: resolved.budgets.counter ?? null },
+      budgetServiceProvider(),
+      budgetGuardProvider()
+    );
+  }
+  return providers;
+}
+function buildAsyncFeatureProviders() {
+  return [
+    fromOptions(BYMAX_AI_TOKENS_WALLET_STORE, (o) => o.wallets.enabled ? o.store : null),
+    fromOptions(BYMAX_AI_TOKENS_BUDGET_STORE, (o) => o.budgets.enabled ? o.store : null),
+    fromOptions(BYMAX_AI_TOKENS_BUDGET_COUNTER, (o) => o.budgets.enabled ? o.budgets.counter ?? null : null),
+    walletServiceProvider(),
+    budgetServiceProvider(),
+    budgetGuardProvider()
+  ];
+}
+function buildSyncFeatureExports(resolved) {
+  const tokens = [];
+  if (resolved.wallets.enabled) tokens.push(BYMAX_AI_TOKENS_WALLET_STORE, WalletService);
+  if (resolved.budgets.enabled) tokens.push(BYMAX_AI_TOKENS_BUDGET_STORE, BYMAX_AI_TOKENS_BUDGET_COUNTER, BudgetService, BudgetGuard);
+  return tokens;
+}
+async function safeResolve(load) {
+  try {
+    const raw = await load;
+    validateOptions(raw);
+    return applyDefaults(raw);
+  } catch (error) {
+    if (error instanceof AiTokensException) throw error;
+    throw new AiTokensException("AI_TOKENS_INVALID_CONFIG", void 0, { reason: "the async options factory rejected or produced invalid options" });
+  }
+}
+function buildAsyncOptionsProviders(descriptor) {
+  if (descriptor.useFactory !== void 0) {
+    const factory = descriptor.useFactory;
+    return [
+      {
+        provide: BYMAX_AI_TOKENS_OPTIONS,
+        useFactory: (...args) => safeResolve(Promise.resolve(factory(...args))),
+        inject: [...descriptor.inject ?? []]
+      }
+    ];
+  }
+  const factoryToken = descriptor.useClass ?? descriptor.useExisting;
+  if (factoryToken === void 0) {
+    throw new AiTokensException("AI_TOKENS_INVALID_CONFIG", void 0, { reason: "forRootAsync requires useFactory, useClass, or useExisting" });
+  }
+  const optionsProvider = {
+    provide: BYMAX_AI_TOKENS_OPTIONS,
+    useFactory: (factory) => safeResolve(Promise.resolve(factory.createAiTokensOptions())),
+    inject: [factoryToken]
+  };
+  return descriptor.useClass !== void 0 ? [optionsProvider, { provide: descriptor.useClass, useClass: descriptor.useClass }] : [optionsProvider];
+}
+var BymaxAiTokensModule = class {
+  /**
+   * Configure the module synchronously. Validates and resolves the options, then
+   * returns the wired dynamic module. `PricingService.onModuleInit` seeds the price
+   * registry when `pricing.seedFromSnapshot` is enabled.
+   *
+   * @param options The module options.
+   * @returns The configured dynamic module.
+   * @throws {AiTokensException} `AI_TOKENS_INVALID_CONFIG` / `AI_TOKENS_FX_REQUIRED` on invalid options.
+   */
+  static forRoot(options) {
+    validateOptions(options);
+    const resolved = applyDefaults(options);
+    return {
+      module: BymaxAiTokensModule,
+      providers: [{ provide: BYMAX_AI_TOKENS_OPTIONS, useValue: resolved }, ...buildCoreProviders(), ...buildSyncFeatureProviders(resolved)],
+      exports: [...CORE_TOKENS, ...CORE_SERVICE_EXPORTS, ...buildSyncFeatureExports(resolved)]
+    };
+  }
+  /**
+   * Configure the module asynchronously, resolving the options from injected
+   * dependencies via `useFactory`/`useClass`/`useExisting` — the family pattern.
+   * The resolved options feed the SAME core providers as {@link forRoot}; the
+   * wallet/budget providers are registered unconditionally and resolve to `null`
+   * when their feature is disabled.
+   *
+   * @param asyncOptions The async options descriptor.
+   * @returns The configured dynamic module.
+   * @throws {AiTokensException} `AI_TOKENS_INVALID_CONFIG` when no async style is supplied or the factory rejects/produces invalid options.
+   */
+  static forRootAsync(asyncOptions) {
+    return {
+      module: BymaxAiTokensModule,
+      imports: [...asyncOptions.imports ?? []],
+      providers: [...buildAsyncOptionsProviders(asyncOptions), ...buildCoreProviders(), ...buildAsyncFeatureProviders()],
+      exports: [...CORE_TOKENS, ...CORE_SERVICE_EXPORTS, ...FEATURE_EXPORTS]
+    };
+  }
+};
+BymaxAiTokensModule = __decorateClass([
+  Global(),
+  Module({})
+], BymaxAiTokensModule);
+
+// src/server/config/provider-presets.ts
+function preset(provider, normalizer, ratingMode) {
+  return { provider, normalizer, ratingMode };
+}
+var providerPresets = {
+  // Stryker disable next-line StringLiteral -- provider ID; only observable via integration tests that exercise the full preset→MeteringService→UsageRecord path
+  openaiChat: preset("openai", normalizeOpenAiChatUsage, "rate-table"),
+  // Stryker disable next-line StringLiteral -- provider ID; only observable via integration tests
+  openaiResponses: preset("openai", normalizeOpenAiResponsesUsage, "rate-table"),
+  // Stryker disable next-line StringLiteral -- provider ID; only observable via integration tests
+  azureOpenai: preset("azure-openai", normalizeOpenAiChatUsage, "rate-table"),
+  // Stryker disable next-line StringLiteral -- provider ID; only observable via integration tests
+  anthropic: preset("anthropic", normalizeAnthropicUsage, "rate-table"),
+  // Stryker disable next-line StringLiteral -- provider ID; only observable via integration tests
+  gemini: preset("gemini", normalizeGeminiUsage, "rate-table"),
+  // Stryker disable next-line StringLiteral -- provider ID; only observable via integration tests
+  vertex: preset("vertex", normalizeGeminiUsage, "rate-table"),
+  // Stryker disable next-line StringLiteral -- provider ID; only observable via integration tests
+  bedrock: preset("bedrock", normalizeBedrockConverseUsage, "rate-table"),
+  // Stryker disable next-line StringLiteral -- provider ID; only observable via integration tests
+  mistral: preset("mistral", normalizeMistralUsage, "rate-table"),
+  vercelAiSdk: preset("openai", normalizeVercelAiSdkUsage, "rate-table"),
+  // Stryker disable next-line StringLiteral -- provider ID and rating mode; only observable via integration tests
+  openrouter: preset("openrouter", normalizeOpenRouterUsage, "provider-reported"),
+  /** A custom OpenAI-compatible provider (DeepSeek, xAI, Groq, …). */
+  openaiCompatible: (id) => preset(id, normalizeOpenAiCompatibleUsage, "rate-table")
+};
+
+export { AI_FEATURE_METADATA, AI_OPERATIONS, AI_TOKENS_ERROR_CODES, AMOUNT_FIELDS, AiFeature, AiTokensException, BYMAX_AI_TOKENS_BUDGET_COUNTER, BYMAX_AI_TOKENS_BUDGET_STORE, BYMAX_AI_TOKENS_CONTENT_STORE, BYMAX_AI_TOKENS_EVENT_SINK, BYMAX_AI_TOKENS_LEDGER_STORE, BYMAX_AI_TOKENS_LOGGER, BYMAX_AI_TOKENS_OPTIONS, BYMAX_AI_TOKENS_PRICING_STORE, BYMAX_AI_TOKENS_TELEMETRY, BYMAX_AI_TOKENS_TOKENIZER, BYMAX_AI_TOKENS_WALLET_STORE, BudgetGuard, BudgetService, BymaxAiTokensModule, LedgerService, METER_METADATA, Meter, MeteringInterceptor, MeteringService, PROVIDER_IDS, PricingService, RELEASE_FIELDS, REQUIRE_BUDGET_METADATA, REVERSAL_LINKAGE_FIELD, RequireBudget, SERVICE_TIERS, SETTLEMENT_FIELDS, SETTLEMENT_PATCH_KEYS, StreamUsageCollector, TOKEN_CATEGORIES, UsageReportService, WALLET_ENTRY_TYPES, WalletService, applyMarkup, computeCostNanoUsd, deriveIdempotencyKey, floatUsdToNanoUsd, formatNanoUsd, isLegalLedgerTransition, isLegalTransitionPatchKey, normalizeAnthropicUsage, normalizeBedrockConverseUsage, normalizeGeminiUsage, normalizeMistralUsage, normalizeOpenAiChatUsage, normalizeOpenAiCompatibleUsage, normalizeOpenAiResponsesUsage, normalizeOpenRouterUsage, normalizeVercelAiSdkUsage, perMillion, providerPresets, resolveMultiplier4dp, toJsonSafe };