@bymax-one/nest-ai-tokens 1.0.0

package/dist/server/index.d.ts

@@ -0,0 +1,3202 @@
+import { ExecutionContext, ModuleMetadata, Type, DynamicModule, OnModuleInit, CanActivate, NestInterceptor, CallHandler, CustomDecorator, HttpException, HttpStatus } from '@nestjs/common';
+import { Readable } from 'node:stream';
+import { Reflector } from '@nestjs/core';
+import { Observable } from 'rxjs';
+
+/**
+ * @fileoverview Catalog of the AI providers this library recognizes out of the
+ * box. Custom OpenAI-compatible providers register their own id at runtime via
+ * `providerPresets.openaiCompatible(id)`, so the public {@link ProviderId} type
+ * (see `types/catalogs.ts`) widens this closed list with `(string & {})`.
+ * @layer shared
+ */
+/**
+ * The provider identifiers shipped with the library. Frozen tuple so the derived
+ * {@link KnownProviderId} union stays in sync with the runtime values.
+ */
+declare const PROVIDER_IDS: readonly ["openai", "azure-openai", "anthropic", "gemini", "vertex", "mistral", "bedrock", "openrouter", "deepseek", "xai", "groq"];
+/** A provider id known to the library at build time (excludes custom ids). */
+type KnownProviderId = (typeof PROVIDER_IDS)[number];
+
+/**
+ * @fileoverview Catalog of AI operation kinds a usage record can describe. The
+ * operation is part of the price-resolution key; `'responses'` bills identically
+ * to `'chat'` and shares its price rows (see spec §5.1).
+ * @layer shared
+ */
+/** Every operation kind the library can meter and price. */
+declare const AI_OPERATIONS: readonly ["chat", "responses", "embeddings", "image", "video", "audio", "rerank", "moderation"];
+/** A logical AI operation kind. */
+type AiOperation = (typeof AI_OPERATIONS)[number];
+
+/**
+ * @fileoverview Catalog of response service tiers. Providers may silently
+ * downgrade a request (OpenAI returns `service_tier: "default"` when priority
+ * capacity is exhausted), so pricing keys off the tier reported in the RESPONSE,
+ * which is what the normalizers read (see spec §5.1).
+ * @layer shared
+ */
+/**
+ * Service tier of the actual response. `'batch'` is the Batch API (~50% discount);
+ * `'flex'` is OpenAI flex processing (batch rates, synchronous); `'priority'` is
+ * paid premium; `'standard'` is the default.
+ */
+declare const SERVICE_TIERS: readonly ["standard", "batch", "flex", "priority"];
+/** A response service tier. */
+type ServiceTier = (typeof SERVICE_TIERS)[number];
+
+/**
+ * @fileoverview Catalog of the token categories that are rated independently.
+ * Cache reads/writes are first-class because a naive input/output-only model
+ * over-bills cached traffic by up to 10× (see spec §5.4).
+ * @layer shared
+ */
+/** Every token category that carries its own per-million rate. */
+declare const TOKEN_CATEGORIES: readonly ["input", "output", "cacheRead", "cacheWrite5m", "cacheWrite1h", "reasoning", "audioIn", "audioOut", "imageIn", "imageOut"];
+/** A single rated token category. */
+type TokenCategory = (typeof TOKEN_CATEGORIES)[number];
+
+/**
+ * @fileoverview Catalog of wallet entry kinds. Balances are the signed sum of
+ * these append-only entries (see spec §9.1).
+ * @layer shared
+ */
+/** Every kind of entry that can appear in a wallet's append-only ledger. */
+declare const WALLET_ENTRY_TYPES: readonly ["grant", "debit", "refund", "adjustment", "expiry"];
+/** A wallet entry kind. */
+type WalletEntryType = (typeof WALLET_ENTRY_TYPES)[number];
+
+/**
+ * @fileoverview The exhaustive catalog of error codes the library raises. Keys
+ * and values are identical strings so `keyof typeof AI_TOKENS_ERROR_CODES` is the
+ * canonical code union that the message/status maps (server layer) are typed
+ * against — the compiler then enforces exhaustive coverage (see spec §16).
+ * @layer shared
+ */
+/** Every error code the library can raise, mapped to itself for value access. */
+declare const AI_TOKENS_ERROR_CODES: {
+    readonly AI_TOKENS_NOT_CONFIGURED: "AI_TOKENS_NOT_CONFIGURED";
+    readonly AI_TOKENS_INVALID_CONFIG: "AI_TOKENS_INVALID_CONFIG";
+    readonly AI_TOKENS_UNKNOWN_PROVIDER: "AI_TOKENS_UNKNOWN_PROVIDER";
+    readonly AI_TOKENS_USAGE_MALFORMED: "AI_TOKENS_USAGE_MALFORMED";
+    readonly AI_TOKENS_PRICE_NOT_FOUND: "AI_TOKENS_PRICE_NOT_FOUND";
+    readonly AI_TOKENS_FX_REQUIRED: "AI_TOKENS_FX_REQUIRED";
+    readonly AI_TOKENS_BUDGET_EXCEEDED: "AI_TOKENS_BUDGET_EXCEEDED";
+    readonly AI_TOKENS_QUOTA_EXCEEDED: "AI_TOKENS_QUOTA_EXCEEDED";
+    readonly AI_TOKENS_INSUFFICIENT_CREDITS: "AI_TOKENS_INSUFFICIENT_CREDITS";
+    readonly AI_TOKENS_HOLD_NOT_FOUND: "AI_TOKENS_HOLD_NOT_FOUND";
+    readonly AI_TOKENS_HOLD_EXPIRED: "AI_TOKENS_HOLD_EXPIRED";
+    readonly AI_TOKENS_HOLD_ALREADY_SETTLED: "AI_TOKENS_HOLD_ALREADY_SETTLED";
+    readonly AI_TOKENS_IDEMPOTENCY_CONFLICT: "AI_TOKENS_IDEMPOTENCY_CONFLICT";
+    readonly AI_TOKENS_STREAM_USAGE_MISSING: "AI_TOKENS_STREAM_USAGE_MISSING";
+    readonly AI_TOKENS_STORE_ERROR: "AI_TOKENS_STORE_ERROR";
+};
+/** A library error code. */
+type AiTokensErrorCode = keyof typeof AI_TOKENS_ERROR_CODES;
+
+/**
+ * @fileoverview The canonical usage shape every provider normalizer produces.
+ * Downstream pricing, ledger, and budget logic is generic over this type, so it
+ * never sees a provider-specific payload.
+ * @layer shared
+ */
+
+/**
+ * Provider-agnostic, per-call token and cost usage. All token counts are plain
+ * `number` (well under 2^53 per record); money is `bigint` nano-USD.
+ */
+interface NormalizedUsage {
+    provider: ProviderId;
+    /** Model id as reported by the RESPONSE (may be a dated snapshot — see spec §6.6). */
+    model: string;
+    operation: AiOperation;
+    /** Tier reported by the response; absent → `'standard'`. */
+    serviceTier?: ServiceTier;
+    /** Uncached, non-reasoning input tokens (after the last cache breakpoint). */
+    inputTokens: number;
+    /**
+     * Output/completion tokens EXCLUDING reasoning tokens (§5.5 invariant).
+     * Anthropic folds thinking into output with no sub-field, so its adapter leaves
+     * `reasoningTokens` at 0 and keeps everything here.
+     */
+    outputTokens: number;
+    /** Tokens served from a cache hit (billed at a fraction of input). */
+    cacheReadTokens: number;
+    /** Tokens written to a 5-minute cache (Anthropic 1.25× input; Bedrock cacheWrite). */
+    cacheWrite5mTokens: number;
+    /** Tokens written to a 1-hour cache (Anthropic 2× input). */
+    cacheWrite1hTokens: number;
+    /** Reasoning/thinking tokens reported separately (OpenAI, Gemini). */
+    reasoningTokens: number;
+    /** Audio input tokens (multimodal). */
+    audioInTokens: number;
+    /** Audio output tokens (multimodal). */
+    audioOutTokens: number;
+    /** Image input tokens (multimodal). */
+    imageInTokens: number;
+    /** Image output tokens (multimodal). */
+    imageOutTokens: number;
+    /**
+     * Server-side tool usage counts — NON-token line items rated via
+     * `PriceVersion.unitRates` (§6.2), e.g. `{ web_search_requests: 2 }`. Anthropic
+     * reports these in `usage.server_tool_use`; for OpenAI/Gemini the host passes
+     * counts via `MeteringContext.extraUnits`.
+     */
+    serverToolUse?: Record<string, number>;
+    /** Provider-reported cost in nano-USD when available (OpenRouter `usage.cost`). */
+    providerReportedCostNanoUsd?: bigint;
+    /** Unclassified fields preserved verbatim for audit. */
+    raw?: Record<string, unknown>;
+}
+
+/**
+ * @fileoverview Canonical catalog types that the rest of the library is generic
+ * over: provider/operation/tier unions, the metering scope, the rating mode, and
+ * the pure normalizer/preset contracts. Framework-free.
+ * @layer shared
+ */
+
+/**
+ * A provider identifier. Widened with `(string & {})` so custom
+ * OpenAI-compatible providers can register their own id while known ids keep
+ * editor autocomplete.
+ */
+type ProviderId = KnownProviderId | (string & {});
+/**
+ * How a call is rated. `'rate-table'` computes cost from the price registry;
+ * `'provider-reported'` trusts `NormalizedUsage.providerReportedCostNanoUsd`.
+ */
+type RatingMode = 'rate-table' | 'provider-reported';
+/** The payer subject whose wallet/budget a call consumes. */
+interface MeteringScope {
+    /** `'key'` scopes spend their owner's wallet — they cannot own money. */
+    type: 'tenant' | 'team' | 'user' | 'key';
+    id: string;
+}
+/** The discriminant of {@link MeteringScope}. */
+type ScopeType = MeteringScope['type'];
+/**
+ * A pure function mapping one provider's raw `usage` object into the canonical
+ * {@link NormalizedUsage} shape. Consumes plain objects — never a provider SDK.
+ */
+type UsageNormalizer = (raw: unknown) => NormalizedUsage;
+/**
+ * Pairs a normalizer with the right provider id and rating mode. Passed in
+ * `MeteringContext.preset` and consumed by `meter()`, the interceptor, and
+ * `record()`.
+ */
+interface ProviderPreset {
+    provider: ProviderId;
+    normalizer: UsageNormalizer;
+    ratingMode: RatingMode;
+}
+
+/**
+ * @fileoverview The immutable ledger row for one AI call (or its hold), its
+ * lifecycle status, the ledger query filter, and the append insert type.
+ * @layer shared
+ */
+
+/** Lifecycle status of a usage record (see spec §8.3). */
+type UsageStatus = 'pending' | 'posted' | 'reversed' | 'released';
+/**
+ * One append-only ledger entry for a single AI call (or its hold). All money is
+ * integer nano-USD; token counts are plain `number`.
+ */
+interface UsageRecord {
+    id: string;
+    tenantId: string;
+    /** The PAYER — the subject whose wallet/budget is consumed. */
+    scope: MeteringScope;
+    /** Optional distinct beneficiary (reporting dimension only). */
+    beneficiary?: MeteringScope;
+    /** Optional actor who triggered the call (audit). */
+    requestedBy?: string;
+    provider: ProviderId;
+    /** Model reported by the response (pricing follows this). */
+    model: string;
+    /** Model the host requested, when supplied (drift audit; §6.6). */
+    requestedModel?: string;
+    operation: AiOperation;
+    serviceTier: ServiceTier;
+    /** Caller-supplied logical operation, e.g. `'workout.generate'`. */
+    feature: string;
+    /** Free-form cost-attribution labels (≤ 10), e.g. `['team:research']`. */
+    tags: string[];
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWrite5mTokens: number;
+    cacheWrite1hTokens: number;
+    reasoningTokens: number;
+    audioInTokens: number;
+    audioOutTokens: number;
+    imageInTokens: number;
+    imageOutTokens: number;
+    totalTokens: number;
+    /** Non-token line items actually rated, e.g. `{ web_search_requests: 2 }`. */
+    extraUnits?: Record<string, number>;
+    /** `null` for provider-reported mode or a priceMissing record. */
+    priceVersionId: string | null;
+    /** Provider cost (tokens + surcharges). */
+    rawCostNanoUsd: bigint;
+    /** The non-token share of `rawCostNanoUsd`. */
+    surchargeNanoUsd: bigint;
+    /** After markup — what the customer pays. */
+    billedCostNanoUsd: bigint;
+    /** The resolved 4-dp markup value actually applied. */
+    markupMultiplier: number;
+    /** `'USD'` in v0.1 (§7.4). */
+    currency: string;
+    /** Rated at 0 in non-strict mode; a backfill target. */
+    priceMissing: boolean;
+    status: UsageStatus;
+    /** Set on a posted record when a compensating record reversed it (§8.5). */
+    reversedByRecordId?: string;
+    /** Set on a compensating record, pointing back at the record it negates. */
+    reversesRecordId?: string;
+    /** Unique per `(tenantId, idempotencyKey)`. */
+    idempotencyKey: string;
+    /** Ties an invoice line back to app logs. */
+    correlationId?: string;
+    /** Provider request id. */
+    requestId?: string;
+    /** Platform-absorbed — never consumes wallet/budget. */
+    isSystemCost: boolean;
+    /** e.g. `'workout_generation_retry'`. */
+    systemCostCategory?: string;
+    /** True when this record consumed wallet/budget (reconciliation predicate §10.7). */
+    enforced: boolean;
+    /** Previous chain hash (optional per-tenant hash chain, §8.6). */
+    prevHash?: string;
+    /** This record's chain hash (optional per-tenant hash chain, §8.6). */
+    hash?: string;
+    /** When the LLM call happened. */
+    occurredAt: Date;
+    createdAt: Date;
+    /** Pending-row settlements only. */
+    updatedAt: Date;
+}
+/**
+ * Caller-supplied fields for `ILedgerStore.append`. The store computes
+ * `id`/`hash`/`prevHash`/`createdAt`/`updatedAt`.
+ */
+type NewUsageRecord = Omit<UsageRecord, 'id' | 'prevHash' | 'hash' | 'createdAt' | 'updatedAt'>;
+/** Query filter for the ledger store. */
+interface LedgerFilter {
+    tenantId: string;
+    scope?: MeteringScope;
+    beneficiary?: MeteringScope;
+    feature?: string;
+    features?: string[];
+    provider?: ProviderId;
+    model?: string;
+    operation?: AiOperation;
+    serviceTier?: ServiceTier;
+    tags?: string[];
+    isSystemCost?: boolean;
+    systemCostCategory?: string;
+    status?: UsageStatus[];
+    enforcedOnly?: boolean;
+    from?: Date;
+    to?: Date;
+    limit?: number;
+    offset?: number;
+}
+
+/**
+ * @fileoverview Append-only ledger field whitelists and the transition guard — the
+ * single source of truth shared by the ledger service and the store adapters so the
+ * two layers can never drift. `AMOUNT_FIELDS` are the money/token amounts that stay
+ * immutable after a record posts; `SETTLEMENT_FIELDS` are everything a settlement
+ * (`pending → posted`) may replace with actuals; `RELEASE_FIELDS` are the audit
+ * annotations a void (`pending → released`) may set; `REVERSAL_LINKAGE_FIELD` is the
+ * sole annotation a `posted → reversed` flip may set. `isLegalLedgerTransition` and
+ * `isLegalTransitionPatchKey` encode the state machine and its per-transition patch
+ * contract so every layer accepts exactly the same patches (see spec §8.3/§8.5).
+ * @layer shared
+ */
+
+/**
+ * The money/token amount columns that are append-only once a record posts — a
+ * void (`pending → released`) or a reversal annotation may never patch them.
+ */
+declare const AMOUNT_FIELDS: readonly ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWrite5mTokens", "cacheWrite1hTokens", "reasoningTokens", "audioInTokens", "audioOutTokens", "imageInTokens", "imageOutTokens", "totalTokens", "rawCostNanoUsd", "surchargeNanoUsd", "billedCostNanoUsd"];
+/**
+ * Every field a settlement (`pending → posted`) may replace with actuals: the
+ * append-only amounts plus the pricing metadata resolved at settlement time.
+ */
+declare const SETTLEMENT_FIELDS: readonly ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWrite5mTokens", "cacheWrite1hTokens", "reasoningTokens", "audioInTokens", "audioOutTokens", "imageInTokens", "imageOutTokens", "totalTokens", "rawCostNanoUsd", "surchargeNanoUsd", "billedCostNanoUsd", "priceVersionId", "priceMissing", "markupMultiplier"];
+/**
+ * The audit-annotation columns a void (`pending → released`) may patch. A release
+ * never bills, so it may only annotate the voided hold with request/correlation
+ * linkage — never an append-only amount, the settlement pricing metadata, or an
+ * immutable identity column. Kept as an explicit column whitelist so the store
+ * boundary never interpolates an unknown identifier into raw SQL.
+ */
+declare const RELEASE_FIELDS: readonly ["correlationId", "requestId"];
+/** The sole field a `posted → reversed` annotation may set — the reversal linkage. */
+declare const REVERSAL_LINKAGE_FIELD: "reversedByRecordId";
+/**
+ * The only patch keys a settlement (`pending → posted`) may set — the settlement
+ * amount/cost/pricing columns plus the reversal-linkage field. An immutable
+ * identity column (`id`/`tenantId`/`idempotencyKey`) is never a member.
+ */
+declare const SETTLEMENT_PATCH_KEYS: ReadonlySet<string>;
+/**
+ * Whether `from → to` is a legal ledger state transition (§8.3): a hold settles
+ * (`pending → posted`) or is voided (`pending → released`), and a posted record may
+ * be annotated as reversed (`posted → reversed`). Every other pair is a caller bug.
+ *
+ * @param from The record's current lifecycle status.
+ * @param to The requested target status.
+ * @returns `true` when the transition is permitted by the state machine.
+ */
+declare function isLegalLedgerTransition(from: UsageStatus, to: UsageStatus): boolean;
+/**
+ * Whether `key` is a legal patch field for the `from → to` transition (§8.3/§8.5) —
+ * the single source of truth shared by the ledger service guard and every store
+ * adapter so the two layers can never drift:
+ * - `pending → posted` (settle): only the settlement fields (+ the reversal linkage).
+ * - `pending → released` (void): only the audit-annotation fields.
+ * - `posted → reversed` (annotate): only the reversal linkage.
+ * Any other (illegal) transition patches nothing. The result set is always drawn
+ * from the fixed column whitelists above, so a store may interpolate a passing key
+ * as a raw SQL identifier without risk of injection.
+ *
+ * @param from The record's current lifecycle status.
+ * @param to The requested target status.
+ * @param key The patch column a caller wishes to set.
+ * @returns `true` when the column may legally be patched on this transition.
+ */
+declare function isLegalTransitionPatchKey(from: UsageStatus, to: UsageStatus, key: string): boolean;
+
+/**
+ * @fileoverview Normalizer for the OpenAI Chat Completions `usage` shape. The
+ * critical rule (spec §5.3/§5.5): `completion_tokens` INCLUDES reasoning tokens,
+ * so `outputTokens = completion_tokens − reasoning_tokens` — double-billing that
+ * detail is the audit's #1 billing bug. Cached and audio prompt tokens are a
+ * subset of `prompt_tokens` and are split into their own categories.
+ * @layer shared
+ */
+
+/**
+ * Normalize an OpenAI Chat Completions response into {@link NormalizedUsage}.
+ *
+ * @param raw The provider response object (with a nested `usage`).
+ * @returns The canonical usage.
+ * @throws {Error} When the `usage` object or its required token fields are absent.
+ * @example
+ * normalizeOpenAiChatUsage({ model: 'gpt-5.2', usage: { prompt_tokens: 100, completion_tokens: 40 } })
+ */
+declare function normalizeOpenAiChatUsage(raw: unknown): NormalizedUsage;
+
+/**
+ * @fileoverview Normalizer for the OpenAI Responses API `usage` shape. Same
+ * reasoning-subtraction rule as Chat Completions, but the fields are renamed
+ * `input_tokens` / `output_tokens` with `input_tokens_details` /
+ * `output_tokens_details` (spec §5.3).
+ * @layer shared
+ */
+
+/**
+ * Normalize an OpenAI Responses API response into {@link NormalizedUsage}.
+ *
+ * @param raw The provider response object (with a nested `usage`).
+ * @returns The canonical usage.
+ * @throws {Error} When the `usage` object or its required token fields are absent.
+ * @example
+ * normalizeOpenAiResponsesUsage({ model: 'gpt-5.2', usage: { input_tokens: 100, output_tokens: 40 } })
+ */
+declare function normalizeOpenAiResponsesUsage(raw: unknown): NormalizedUsage;
+
+/**
+ * @fileoverview Normalizer for OpenAI-compatible gateways (DeepSeek, xAI, Groq, …)
+ * that reuse the Chat Completions `prompt_tokens` / `completion_tokens` shape
+ * without OpenAI-specific detail guarantees. DeepSeek's `prompt_cache_hit_tokens`
+ * maps to `cacheReadTokens` when present. The provider id is left empty for the
+ * preset (`providerPresets.openaiCompatible(id)`) or context to supply (spec §5.3).
+ * @layer shared
+ */
+
+/**
+ * Normalize an OpenAI-compatible chat response into {@link NormalizedUsage}.
+ *
+ * @param raw The provider response object (with a nested `usage`).
+ * @returns The canonical usage; `provider` is `''` unless the preset overrides it.
+ * @throws {Error} When the `usage` object or its required token fields are absent.
+ * @example
+ * normalizeOpenAiCompatibleUsage({ model: 'deepseek-chat', usage: { prompt_tokens: 100, completion_tokens: 40 } })
+ */
+declare function normalizeOpenAiCompatibleUsage(raw: unknown): NormalizedUsage;
+
+/**
+ * @fileoverview Normalizer for the Anthropic Messages `usage` shape. Anthropic
+ * folds thinking into `output_tokens` with no sub-field, so `reasoningTokens`
+ * stays `0` (spec §5.3/§5.5). Cache writes split into 5-minute and 1-hour
+ * categories via `cache_creation`; an unsplit `cache_creation_input_tokens`
+ * total defaults to the 5-minute category. Server tool use maps to `serverToolUse`.
+ * @layer shared
+ */
+
+/**
+ * Normalize an Anthropic Messages response into {@link NormalizedUsage}.
+ *
+ * @param raw The provider response object (with a nested `usage`).
+ * @returns The canonical usage.
+ * @throws {Error} When the `usage` object or its required token fields are absent.
+ * @example
+ * normalizeAnthropicUsage({ model: 'claude-opus', usage: { input_tokens: 100, output_tokens: 40 } })
+ */
+declare function normalizeAnthropicUsage(raw: unknown): NormalizedUsage;
+
+/**
+ * @fileoverview Normalizer for the Google Gemini / Vertex `usageMetadata` shape.
+ * `candidatesTokenCount` EXCLUDES thoughts, so it maps directly to `outputTokens`
+ * with no subtraction; `thoughtsTokenCount` maps to `reasoningTokens`;
+ * `toolUsePromptTokenCount` folds into `inputTokens` (billed at the input rate);
+ * `cachedContentTokenCount` is the cache-read portion of the prompt (spec §5.3).
+ * @layer shared
+ */
+
+/**
+ * Normalize a Gemini / Vertex response into {@link NormalizedUsage}.
+ *
+ * @param raw The provider response object (with a nested `usageMetadata`).
+ * @returns The canonical usage.
+ * @throws {Error} When `usageMetadata` or its required token field is absent.
+ * @example
+ * normalizeGeminiUsage({ modelVersion: 'gemini-2.5-flash', usageMetadata: { promptTokenCount: 100, candidatesTokenCount: 40 } })
+ */
+declare function normalizeGeminiUsage(raw: unknown): NormalizedUsage;
+
+/**
+ * @fileoverview Normalizer for the AWS Bedrock Converse `usage` shape. Cache
+ * writes come either as a single `cacheWriteInputTokens` total (defaulting to the
+ * 5-minute category) or split across `cacheDetails[]` TTL entries (spec §5.3).
+ * Model ids like `us.anthropic.claude-…-v1:0` are region-prefixed and are
+ * resolved downstream (spec §6.6).
+ * @layer shared
+ */
+
+/**
+ * Normalize a Bedrock Converse response into {@link NormalizedUsage}.
+ *
+ * @param raw The provider response object (with a nested `usage`).
+ * @returns The canonical usage.
+ * @throws {Error} When the `usage` object or its required token fields are absent.
+ * @example
+ * normalizeBedrockConverseUsage({ model: 'us.anthropic.claude', usage: { inputTokens: 100, outputTokens: 40 } })
+ */
+declare function normalizeBedrockConverseUsage(raw: unknown): NormalizedUsage;
+
+/**
+ * @fileoverview Normalizer for the Mistral `usage` shape. v0.1 maps
+ * `prompt_tokens` / `completion_tokens` only; any additional audio/cache detail
+ * fields are version-dependent and preserved verbatim in `raw` (spec §5.3/§20.3).
+ * @layer shared
+ */
+
+/**
+ * Normalize a Mistral response into {@link NormalizedUsage}.
+ *
+ * @param raw The provider response object (with a nested `usage`).
+ * @returns The canonical usage.
+ * @throws {Error} When the `usage` object or its required token fields are absent.
+ * @example
+ * normalizeMistralUsage({ model: 'mistral-large', usage: { prompt_tokens: 100, completion_tokens: 40 } })
+ */
+declare function normalizeMistralUsage(raw: unknown): NormalizedUsage;
+
+/**
+ * @fileoverview Normalizer for the OpenRouter `usage` shape. `usage.cost` is the
+ * real charged amount in USD (1 credit = 1 USD) and converts to
+ * `providerReportedCostNanoUsd`, enabling `'provider-reported'` rating with no
+ * price row. `completion_tokens` includes reasoning, so it is subtracted like
+ * OpenAI (spec §5.3/§5.5/§6.5). `cost_details` is preserved in `raw`.
+ * @layer shared
+ */
+
+/**
+ * Normalize an OpenRouter response into {@link NormalizedUsage}.
+ *
+ * @param raw The provider response object (with a nested `usage`).
+ * @returns The canonical usage, including `providerReportedCostNanoUsd` when `usage.cost` is present.
+ * @throws {Error} When the `usage` object or its required token fields are absent.
+ * @example
+ * normalizeOpenRouterUsage({ model: 'gpt-5.2', usage: { prompt_tokens: 100, completion_tokens: 40, cost: 0.0123 } })
+ */
+declare function normalizeOpenRouterUsage(raw: unknown): NormalizedUsage;
+
+/**
+ * @fileoverview Normalizer for the Vercel AI SDK `usage` shape. It reads BOTH the
+ * v5 shape (`usage.{inputTokens, outputTokens, cachedInputTokens, reasoningTokens}`)
+ * and the v6 shape (`inputTokenDetails.{cacheReadTokens, cacheWriteTokens}`,
+ * `outputTokenDetails.reasoningTokens`). `outputTokens` includes reasoning tokens,
+ * so they are subtracted. The provider id and model are supplied by the caller's
+ * preset/context and default to empty here (spec §5.3).
+ * @layer shared
+ */
+
+/**
+ * Normalize a Vercel AI SDK response into {@link NormalizedUsage}.
+ *
+ * @param raw The provider response object (with a nested `usage`).
+ * @returns The canonical usage; `provider` is `''` unless the context overrides it.
+ * @throws {Error} When the `usage` object or its required token fields are absent.
+ * @example
+ * normalizeVercelAiSdkUsage({ usage: { inputTokens: 100, outputTokens: 40 } })
+ */
+declare function normalizeVercelAiSdkUsage(raw: unknown): NormalizedUsage;
+
+/**
+ * @fileoverview Exact nano-USD money helpers. Every persisted monetary value is
+ * an integer number of nano-USD (`1e-9` USD) held as a `bigint`, so all
+ * arithmetic is exact integer math. Floating point appears only at the two
+ * documented boundaries: the OpenRouter `usage.cost` entry conversion
+ * ({@link floatUsdToNanoUsd}) and presentation ({@link formatNanoUsd}).
+ * @layer shared
+ */
+/**
+ * The building block for token pricing: cost of `tokens` at a rate expressed as
+ * nano-USD per 1,000,000 tokens, as exact integer math (spec §7.1).
+ *
+ * @param tokens Integer token count.
+ * @param ratePerMillionNano Rate in nano-USD per 1,000,000 tokens.
+ * @returns Cost in nano-USD, truncated toward zero on the division.
+ * @example
+ * perMillion(1000, 5_000_000_000n) // 5_000_000n  ($0.005 for 1k tokens at $5/M)
+ */
+declare function perMillion(tokens: number, ratePerMillionNano: bigint): bigint;
+/**
+ * Convert a floating-point USD amount (e.g. OpenRouter `usage.cost`) into
+ * nano-USD, rounding half away from zero at nano precision. The dollar and
+ * fractional parts are handled separately so no product overflows the 2^53
+ * exact-integer range: the result is exact for `|usd| < $1,000` (and for any
+ * value whose fractional dollars round cleanly). This is the only float→bigint
+ * entry point on a money path.
+ *
+ * @param usd The amount in USD.
+ * @returns The amount in nano-USD.
+ * @throws {RangeError} When `usd` is not finite.
+ * @example
+ * floatUsdToNanoUsd(0.005) // 5_000_000n
+ */
+declare function floatUsdToNanoUsd(usd: number): bigint;
+/** Options controlling how {@link formatNanoUsd} renders a value. */
+interface FormatNanoUsdOptions {
+    /** ISO currency code; `'USD'` renders a `$` prefix, others append the code. Default `'USD'`. */
+    currency?: string;
+    /** Presentation FX rate as target-currency nano-units per 1 USD; converts at read time. */
+    fxRateNano?: bigint;
+    /** Fractional digits to render, in the range `[0, 9]`. Default `6`. */
+    decimals?: number;
+}
+/**
+ * Render a nano-USD value as a human-readable currency string. Presentation
+ * only — rounding to the displayed precision is round-half-up computed in
+ * `bigint`, never floating point (spec §7.4).
+ *
+ * @param nanoUsd The value in nano-USD.
+ * @param opts Currency, FX, and precision options.
+ * @returns The formatted string, e.g. `"$0.005000"`.
+ * @throws {RangeError} When `opts.decimals` is not an integer in `[0, 9]`.
+ * @example
+ * formatNanoUsd(5_000_000n)                               // '$0.005000'
+ * formatNanoUsd(5_000_000n, { currency: 'BRL', fxRateNano: 5_000_000_000n }) // '0.025000 BRL'
+ */
+declare function formatNanoUsd(nanoUsd: bigint, opts?: FormatNanoUsdOptions): string;
+
+/**
+ * @fileoverview The effective-dated price row and its insert type. Rates are
+ * integer nano-USD per 1,000,000 tokens (or per unit for non-token line items),
+ * so every cost computation is exact integer math.
+ * @layer shared
+ */
+
+/**
+ * One immutable, effective-dated price version for a (provider, model, operation,
+ * serviceTier) tuple. A call is rated at the row in effect at its timestamp.
+ */
+interface PriceVersion {
+    id: string;
+    provider: ProviderId;
+    model: string;
+    operation: AiOperation;
+    /** Part of the resolution key; `'standard'` is the default. */
+    serviceTier: ServiceTier;
+    /** Rates as integer nano-USD per 1,000,000 tokens. */
+    inputNanoUsdPerMillion: bigint;
+    outputNanoUsdPerMillion: bigint;
+    cacheReadNanoUsdPerMillion: bigint;
+    cacheWrite5mNanoUsdPerMillion: bigint;
+    cacheWrite1hNanoUsdPerMillion: bigint;
+    /** Usually equals output; kept separate for models that price reasoning differently. */
+    reasoningNanoUsdPerMillion: bigint;
+    audioInNanoUsdPerMillion: bigint;
+    audioOutNanoUsdPerMillion: bigint;
+    imageInNanoUsdPerMillion: bigint;
+    imageOutNanoUsdPerMillion: bigint;
+    /**
+     * Long-context tier threshold: when total input (all input-side categories)
+     * exceeds this, the tier rates replace the base input/output rates for the
+     * WHOLE call (all-or-nothing, matching Gemini's billing).
+     */
+    tierThresholdTokens?: number;
+    tierInputNanoUsdPerMillion?: bigint;
+    tierOutputNanoUsdPerMillion?: bigint;
+    /**
+     * Non-token line items in nano-USD PER UNIT, matched against
+     * `NormalizedUsage.serverToolUse` / `MeteringContext.extraUnits` by EXACT key —
+     * so the key must equal the count key the normalizer emits (e.g. Anthropic's
+     * `usage.server_tool_use.web_search_requests`) — e.g.
+     * `{ web_search_requests: 10_000_000n }` ($0.01 per web-search call).
+     */
+    unitRates?: Record<string, bigint>;
+    currency: 'USD';
+    effectiveFrom: Date;
+    /** `null` = current; set when a newer row supersedes it. */
+    effectiveTo: Date | null;
+    /** Provenance: `'snapshot' | 'manual' | 'import'`. */
+    source: string;
+}
+/**
+ * Caller-supplied fields for `upsertPrice`. Rates default to `0n` and
+ * `serviceTier` to `'standard'`; the store assigns `id` and closes the previous
+ * open row's `effectiveTo`.
+ */
+type NewPriceVersion = Partial<Omit<PriceVersion, 'id' | 'effectiveTo'>> & Pick<PriceVersion, 'provider' | 'model' | 'operation'>;
+
+/**
+ * @fileoverview The pure cost engine (spec §7.1). Computes the provider cost of a
+ * {@link NormalizedUsage} against a {@link PriceVersion} in exact bigint nano-USD.
+ * The long-context tier is all-or-nothing: when total input crosses the
+ * threshold, the tier rates replace the base input/output rates for the WHOLE
+ * call. Non-token line items are rated via `unitRates`. The token and surcharge
+ * parts are returned separately so reports can distinguish them.
+ * @layer shared
+ */
+
+/** The separable parts of a computed provider cost, all in nano-USD. */
+interface CostBreakdown {
+    /** Token cost plus surcharges. */
+    totalNanoUsd: bigint;
+    /** The token-only share. */
+    tokenNanoUsd: bigint;
+    /** The non-token (server tool use) share. */
+    surchargeNanoUsd: bigint;
+}
+/**
+ * Compute the provider cost of a normalized usage against a price version.
+ *
+ * @param usage The normalized usage.
+ * @param rate The effective-dated price version.
+ * @returns The exact cost broken into token and surcharge parts.
+ * @example
+ * // 1,000 Opus input tokens at $5/M → 5_000_000n nano-USD ($0.005).
+ * computeCostNanoUsd(usage, rate).totalNanoUsd
+ */
+declare function computeCostNanoUsd(usage: NormalizedUsage, rate: PriceVersion): CostBreakdown;
+
+/**
+ * @fileoverview Markup / margin math (spec §7.2). The multiplier is validated
+ * (finite, > 0) and rounded to 4 decimal places to match the persisted
+ * `Decimal(10,4)`; the billed amount is exact bigint with truncation toward zero
+ * on the final division. Markup applies in BOTH rating modes.
+ * @layer shared
+ */
+/**
+ * Validate and round a markup multiplier to 4 decimal places — the value that is
+ * persisted on each usage record.
+ *
+ * @param multiplier The raw multiplier.
+ * @returns The multiplier rounded to 4 decimal places.
+ * @throws {RangeError} When the multiplier is not finite or not > 0.
+ * @example
+ * resolveMultiplier4dp(1.23456) // 1.2346
+ */
+declare function resolveMultiplier4dp(multiplier: number): number;
+/**
+ * Apply a markup multiplier to a raw provider cost, in exact bigint nano-USD.
+ *
+ * @param rawCostNanoUsd The provider cost in nano-USD.
+ * @param multiplier The markup multiplier (e.g. `4.0` for 4× resale).
+ * @returns The billed cost in nano-USD (division truncates toward zero).
+ * @throws {RangeError} When the multiplier is not finite or not > 0.
+ * @example
+ * applyMarkup(5_000_000n, 4.0) // 20_000_000n
+ */
+declare function applyMarkup(rawCostNanoUsd: bigint, multiplier: number): bigint;
+
+/**
+ * @fileoverview Host-side derivation of a stable idempotency key from request
+ * content (spec §8.4). The payload is serialized to canonical JSON — object keys
+ * sorted recursively, array order preserved, `undefined` dropped, `bigint`
+ * encoded as a QUOTED, type-tagged string (e.g. `42n` → `"42n"`), `Date` as its
+ * ISO string — then hashed with a pure synchronous SHA-256. The `n`-suffixed
+ * quoted form makes a `bigint` unambiguous: it can never serialize to the same
+ * text as the number `42` (`42`) or a numeric string `"42"` (`"42"`), so
+ * `deriveIdempotencyKey(42)` and `deriveIdempotencyKey(42n)` never collide.
+ * Deriving the key from content means a retry after a 429/network failure reuses
+ * the same key and is deduplicated.
+ * @layer shared
+ */
+/**
+ * Derive a stable idempotency key from a request payload. Equal payloads (up to
+ * object-key order) yield the same key; distinct payloads yield distinct keys.
+ * Pure, synchronous, and edge-safe.
+ *
+ * @param payload Any JSON-like request content.
+ * @returns A 64-character lowercase hex SHA-256 digest.
+ * @example
+ * deriveIdempotencyKey({ a: 1, b: 2 }) === deriveIdempotencyKey({ b: 2, a: 1 }) // true
+ */
+declare function deriveIdempotencyKey(payload: unknown): string;
+
+/**
+ * @fileoverview Wallet types: the owner reference, the materialized wallet, and
+ * the append-only entry ledger whose signed sum is the balance (see spec §9.1).
+ * @layer shared
+ */
+
+/**
+ * Identifies the owner of a wallet. `'key'` scopes deliberately cannot own money
+ * — API keys spend their owner's wallet.
+ */
+interface WalletRef {
+    tenantId: string;
+    ownerType: 'tenant' | 'team' | 'user';
+    ownerId: string;
+}
+/** A prepaid credit wallet with a materialized nano-USD balance. */
+interface Wallet {
+    id: string;
+    tenantId: string;
+    ownerType: WalletRef['ownerType'];
+    ownerId: string;
+    /** Materialized, kept transactionally consistent with Σ entries. */
+    balanceNanoUsd: bigint;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** One append-only entry in a wallet's ledger. */
+interface WalletEntry {
+    id: string;
+    walletId: string;
+    type: WalletEntryType;
+    /** `+` = credit, `−` = debit. */
+    amountNanoUsd: bigint;
+    /** Grant burn priority (lower first). */
+    priority: number;
+    effectiveAt: Date;
+    /** Grants only. */
+    expiresAt?: Date;
+    /** Present on usage-driven debits/refunds. */
+    usageRecordId?: string;
+    /** Unique per wallet. */
+    idempotencyKey: string;
+    reason?: string;
+    createdAt: Date;
+}
+/** Caller-supplied fields for `IWalletStore.appendEntry`. The store assigns `id`/`createdAt`. */
+type NewWalletEntry = Omit<WalletEntry, 'id' | 'createdAt'>;
+
+/**
+ * @fileoverview Budget types: the budget definition, its window/policy unions,
+ * and the read-side status DTOs a usage meter renders (see spec §10).
+ * @layer shared
+ */
+
+/** How a budget's window repeats. `{ customSeconds }` is a fixed-length rolling window. */
+type BudgetWindowKind = 'day' | 'week' | 'month' | 'total' | {
+    customSeconds: number;
+};
+/** What happens when a budget is exceeded. */
+type BudgetPolicy = 'block' | 'throttle' | 'allow';
+/** A spend/token/count cap for a scope over a window. */
+interface Budget {
+    id: string;
+    tenantId: string;
+    scope: MeteringScope;
+    /** Restrict which usage counts; empty/absent = all features. */
+    features?: string[];
+    /** Billed-spend cap. */
+    limitNanoUsd?: bigint;
+    /** Total-token cap. */
+    limitTokens?: number;
+    /** Operation-count cap (posted, enforced, non-reversed records). */
+    limitCount?: number;
+    window: BudgetWindowKind;
+    /**
+     * Per-budget window anchor. Absent → calendar UTC anchoring. Month windows
+     * clamp short months (a Jan 31 anchor yields Feb 28/29, Mar 31, …).
+     */
+    anchorAt?: Date;
+    /** Optional budget lifetime: enforcement ignores the budget after this instant. */
+    expiresAt?: Date;
+    /** Fractions of the limit that trigger soft alert events. */
+    softThresholds: number[];
+    policy: BudgetPolicy;
+    createdAt: Date;
+}
+/** The read-side status of one budget window — powers a usage meter. */
+interface BudgetStatus {
+    budgetId: string;
+    features?: string[];
+    window: BudgetWindowKind;
+    windowStart: Date;
+    /** `null` for `'total'`. */
+    resetsAt: Date | null;
+    policy: BudgetPolicy;
+    limit: {
+        nanoUsd?: bigint;
+        tokens?: number;
+        count?: number;
+    };
+    spent: {
+        nanoUsd: bigint;
+        tokens: number;
+        count: number;
+    };
+    /** Absent dimension = unlimited. */
+    remaining: {
+        nanoUsd?: bigint;
+        tokens?: number;
+        count?: number;
+    };
+    /** Max across limited dimensions. */
+    usedFraction: number;
+}
+/** Aggregate access status for a scope (wallet + all matching budgets). */
+interface AccessStatus {
+    hasAccess: boolean;
+    blockedBy?: 'wallet' | 'budget';
+    wallet?: {
+        balanceNanoUsd: bigint;
+        credits: number;
+        overdraftRemainingNanoUsd: bigint;
+    };
+    budgets: BudgetStatus[];
+}
+
+/**
+ * @fileoverview Reporting types: the query filter and the aggregated usage
+ * summary (including the cache-savings figure) produced by `UsageReportService`.
+ * @layer shared
+ */
+
+/** Filter for a usage report query. */
+interface ReportFilter {
+    tenantId: string;
+    scope?: MeteringScope;
+    beneficiary?: MeteringScope;
+    feature?: string;
+    features?: string[];
+    provider?: ProviderId;
+    model?: string;
+    operation?: AiOperation;
+    serviceTier?: ServiceTier;
+    /** Records carrying ANY of these tags. */
+    tags?: string[];
+    isSystemCost?: boolean;
+    systemCostCategory?: string;
+    enforcedOnly?: boolean;
+    /** Default `['posted', 'reversed']`. */
+    status?: UsageStatus[];
+    from: Date;
+    to: Date;
+}
+/** One aggregated row of a usage report. */
+interface UsageSummary {
+    /** groupBy key → value; empty groupBy = one grand-total row. */
+    group: Record<string, string>;
+    records: number;
+    totalTokens: number;
+    tokens: Record<TokenCategory, number>;
+    rawCostNanoUsd: bigint;
+    surchargeNanoUsd: bigint;
+    billedCostNanoUsd: bigint;
+    /** Σ cacheReadTokens × (inputRate − cacheReadRate) — the "you saved $X via caching" figure. */
+    cacheSavingsNanoUsd: bigint;
+}
+
+/**
+ * @fileoverview The event envelope, the event-type union, and one payload type
+ * per event in the catalog (see spec §12). Delivery is at-least-once, so `id` is
+ * the consumer's dedupe key. `bigint` payload fields cross a JSON boundary as
+ * decimal strings (§15.5) — in-process delivery keeps them as `bigint`.
+ * @layer shared
+ */
+
+/** Every event `type` the library emits. */
+type AiTokensEventType = 'ai_tokens.usage.recorded' | 'ai_tokens.usage.reversed' | 'ai_tokens.hold.released' | 'ai_tokens.budget.threshold_crossed' | 'ai_tokens.budget.exceeded' | 'ai_tokens.budget.projected_exceeded' | 'ai_tokens.wallet.low_balance' | 'ai_tokens.wallet.depleted' | 'ai_tokens.wallet.granted' | 'ai_tokens.price.missing' | 'ai_tokens.audit';
+/** The at-least-once event envelope. */
+interface AiTokensEvent<T = unknown> {
+    /** UUID — the consumer's dedupe key. */
+    id: string;
+    type: AiTokensEventType;
+    occurredAt: Date;
+    tenantId: string;
+    scope?: MeteringScope;
+    data: T;
+}
+/** A per-window spend snapshot shared by budget event payloads. */
+interface BudgetDimensionSnapshot {
+    nanoUsd?: bigint;
+    tokens?: number;
+    count?: number;
+}
+/** `ai_tokens.usage.recorded` payload. */
+interface UsageRecordedEventData {
+    usageRecordId: string;
+    feature: string;
+    provider: ProviderId;
+    model: string;
+    serviceTier: ServiceTier;
+    totalTokens: number;
+    rawCostNanoUsd: bigint;
+    billedCostNanoUsd: bigint;
+    enforced: boolean;
+    isSystemCost: boolean;
+}
+/** `ai_tokens.usage.reversed` payload. */
+interface UsageReversedEventData {
+    usageRecordId: string;
+    reversalRecordId: string;
+    reason: string;
+}
+/** `ai_tokens.hold.released` payload. */
+interface HoldReleasedEventData {
+    holdId: string;
+    reason: string;
+    expired: boolean;
+}
+/** `ai_tokens.budget.threshold_crossed` payload. */
+interface BudgetThresholdCrossedEventData {
+    budgetId: string;
+    threshold: number;
+    usedFraction: number;
+    limit: BudgetDimensionSnapshot;
+    spent: BudgetDimensionSnapshot;
+    remaining: BudgetDimensionSnapshot;
+    resetsAt: Date | null;
+}
+/** `ai_tokens.budget.exceeded` payload. */
+interface BudgetExceededEventData {
+    budgetId: string;
+    policy: BudgetPolicy;
+    dimension: 'cost' | 'tokens' | 'count';
+    limit: BudgetDimensionSnapshot;
+    spent: BudgetDimensionSnapshot;
+    resetsAt: Date | null;
+}
+/** `ai_tokens.budget.projected_exceeded` payload. */
+interface BudgetProjectedExceededEventData {
+    budgetId: string;
+    projectedAt: Date;
+    usedFraction: number;
+    resetsAt: Date | null;
+}
+/** `ai_tokens.wallet.low_balance` payload. */
+interface WalletLowBalanceEventData {
+    walletId: string;
+    balanceNanoUsd: bigint;
+    thresholdFraction: number;
+}
+/** `ai_tokens.wallet.depleted` payload. */
+interface WalletDepletedEventData {
+    walletId: string;
+    balanceNanoUsd: bigint;
+}
+/** `ai_tokens.wallet.granted` payload. */
+interface WalletGrantedEventData {
+    walletId: string;
+    entryId: string;
+    amountNanoUsd: bigint;
+    expiresAt?: Date;
+}
+/** `ai_tokens.price.missing` payload. */
+interface PriceMissingEventData {
+    provider: ProviderId;
+    model: string;
+    operation: AiOperation;
+    serviceTier: ServiceTier;
+    usageRecordId: string;
+}
+/** `ai_tokens.audit` payload — an admin-plane mutation (§14.4). */
+interface AuditEventData {
+    action: string;
+    actor?: string;
+    details: Record<string, unknown>;
+}
+
+/**
+ * @fileoverview The canonical error response body. `AiTokensException` (server
+ * layer) serializes to this shape so hosts get a stable `{ error: {...} }`
+ * envelope (see spec §16).
+ * @layer shared
+ */
+
+/** The JSON body every {@link AI_TOKENS_ERROR_CODES} failure serializes to. */
+interface AiTokensErrorResponse {
+    error: {
+        code: keyof typeof AI_TOKENS_ERROR_CODES;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+}
+
+/**
+ * @fileoverview The budget persistence port (spec §15.1). Multi-dimension
+ * budgets with atomic conditional consume, signed window adjustment, and window
+ * rotation. Only validated at init when the budget feature is enabled.
+ * @layer server
+ */
+
+/** A signed or absolute per-window spend delta across the three budget dimensions. */
+interface BudgetDelta {
+    nanoUsd: bigint;
+    tokens: number;
+    count: number;
+}
+/** Limits checked by {@link IBudgetStore.conditionalConsume} (absent = unlimited). */
+interface BudgetLimits {
+    nanoUsd?: bigint;
+    tokens?: number;
+    count?: number;
+}
+/** A window's materialized spend counters. */
+interface BudgetWindowSpend {
+    spentNanoUsd: bigint;
+    spentTokens: number;
+    spentCount: number;
+}
+/** The budget port. */
+interface IBudgetStore {
+    /** Create or replace a budget. */
+    upsert(budget: Omit<Budget, 'id' | 'createdAt'> & {
+        id?: string;
+    }): Promise<Budget>;
+    /** Delete a budget. */
+    remove(budgetId: string): Promise<void>;
+    /** Load one budget by id — the rotateWindow/reconcileWindow paths read it by id (§10.5). */
+    findBudgetById(budgetId: string): Promise<Budget | null>;
+    /**
+     * Every budget for the tenant scoped to the EXACT scope or tenant-wide (§10.3). A
+     * single {@link MeteringScope} carries no team/user lineage, so the tenant is the
+     * only ancestor resolvable — intermediate ancestors are not matched. Each budget
+     * returned consumes independently; a subject-level budget never exempts the tenant cap.
+     */
+    findMatching(tenantId: string, scope: MeteringScope): Promise<Budget[]>;
+    /**
+     * Atomic multi-dimension conditional consume (§10.8). `false` = a limit would be
+     * exceeded. Creates the window row on first touch.
+     */
+    conditionalConsume(budgetId: string, windowStart: Date, delta: BudgetDelta, limits: BudgetLimits): Promise<boolean>;
+    /** Signed release/adjust of a window's counters (capture delta, release, reverse). */
+    adjustWindow(budgetId: string, windowStart: Date, delta: BudgetDelta): Promise<void>;
+    /** A window's current spend, or `null` when it has no row yet. */
+    getWindow(budgetId: string, windowStart: Date): Promise<BudgetWindowSpend | null>;
+    /** Move a budget's active window start (rotateWindow support). */
+    setWindowStart(budgetId: string, windowStart: Date): Promise<void>;
+}
+
+/**
+ * @fileoverview The ledger persistence port (spec §15.1). The append-only usage
+ * ledger: idempotent append, atomic state transitions, and aggregate queries.
+ * Implemented by the official Prisma adapter or a custom store.
+ * @layer server
+ */
+
+/** Aggregate cost totals returned by {@link ILedgerStore.sumCost}. */
+interface LedgerCostSummary {
+    rawCostNanoUsd: bigint;
+    billedCostNanoUsd: bigint;
+    surchargeNanoUsd: bigint;
+    totalTokens: number;
+    records: number;
+}
+/** A report group-by dimension (spec §13.1). */
+type ReportGroupBy = 'day' | 'week' | 'month' | 'feature' | 'provider' | 'model' | 'operation' | 'serviceTier' | 'scope' | 'beneficiary' | 'tag' | 'systemCostCategory';
+/** The append-only usage ledger port. */
+interface ILedgerStore {
+    /**
+     * Upsert on `(tenantId, idempotencyKey)` — a replay returns the existing record
+     * iff the payload hash matches; a different hash is a conflict (§8.4). When
+     * `hashChain` is true and the record is `posted`, the store reads the tenant's
+     * last chain hash, computes this record's `prevHash`/`hash`, and persists them
+     * ATOMICALLY under a per-tenant lock (§8.6) — the read-compute-write is one
+     * serialized operation so concurrent appends never fork the chain. When false
+     * (the default), no chain lookup or hashing occurs.
+     */
+    append(record: NewUsageRecord, payloadHash: string, hashChain?: boolean): Promise<UsageRecord>;
+    /**
+     * State transitions only (§8.3): `pending→posted` (settle, amounts patched),
+     * `pending→released`, `posted→reversed` (annotation only — amount fields
+     * rejected). Atomic: returns `null` when the record was not in the expected
+     * source state (how exactly one reaper replica wins an expired hold). When
+     * `hashChain` is true and `to` is `posted` (settlement), the store computes and
+     * persists the record's chain `prevHash`/`hash` under the same per-tenant lock (§8.6).
+     */
+    transition(id: string, from: UsageStatus, to: UsageStatus, patch?: Partial<UsageRecord>, hashChain?: boolean): Promise<UsageRecord | null>;
+    /** Look up a record by its per-tenant idempotency key. */
+    findByIdempotencyKey(tenantId: string, key: string): Promise<UsageRecord | null>;
+    /**
+     * Load one record by its global id — the reversal path loads the original to
+     * negate it into a compensating record (§8.5). Returns `null` when absent.
+     */
+    findById(id: string): Promise<UsageRecord | null>;
+    /** Find pending holds older than `olderThan` for the reaper sweep. */
+    findExpiredHolds(olderThan: Date, limit: number): Promise<UsageRecord[]>;
+    /** Query records by filter. */
+    query(filter: LedgerFilter): Promise<UsageRecord[]>;
+    /** Aggregate cost/token totals for a filter. */
+    sumCost(filter: LedgerFilter): Promise<LedgerCostSummary>;
+    /**
+     * OPTIONAL scalable aggregation (spec §13.1): `SUM … GROUP BY` across the report
+     * dimensions, computed in the store (the official Prisma adapter uses SQL). A
+     * store that omits it falls back to `UsageReportService`'s documented
+     * query-and-aggregate-in-memory path, capped at `reporting.maxExportRows`.
+     */
+    summarize?(filter: LedgerFilter, groupBy: ReportGroupBy[]): Promise<UsageSummary[]>;
+    /**
+     * The last posted record's hash for a tenant (hash-chain continuation, §8.6).
+     * The chain is serialized per tenant: the official Prisma adapter takes a
+     * Postgres advisory lock so the last-hash read and the chained append/settle run
+     * as one atomic operation; an in-memory store simulates this with a per-tenant
+     * mutex. Returns `null` before the tenant's first chained record.
+     */
+    lastHash(tenantId: string): Promise<string | null>;
+}
+
+/**
+ * @fileoverview The pricing persistence port (spec §15.1). Effective-dated rate
+ * resolution, append-only price upserts, and the model list that powers §6.6
+ * prefix matching.
+ * @layer server
+ */
+
+/** A distinct priced model tuple, returned by {@link IPricingStore.listModels}. */
+interface PricedModel {
+    model: string;
+    operation: AiOperation;
+    serviceTier: ServiceTier;
+}
+/** The effective-dated price registry port. */
+interface IPricingStore {
+    /** The price row in effect at `at` for the tuple, or `null` when none matches. */
+    resolveRate(provider: ProviderId, model: string, operation: AiOperation, serviceTier: ServiceTier, at: Date): Promise<PriceVersion | null>;
+    /** Close the current open row (`effectiveTo = now`) and insert the new open row. */
+    upsertPrice(input: NewPriceVersion): Promise<PriceVersion>;
+    /** Full effective-dated history for a tuple (newest first). */
+    getPriceHistory(provider: ProviderId, model: string, operation: AiOperation, serviceTier?: ServiceTier): Promise<PriceVersion[]>;
+    /** All distinct (model, operation, serviceTier) for a provider — powers §6.6 prefix matching. */
+    listModels(provider: ProviderId): Promise<PricedModel[]>;
+}
+
+/**
+ * @fileoverview The wallet persistence port (spec §15.1). Materialized-balance
+ * wallets with atomic conditional debit, grant allocation, and reconciliation.
+ * Only validated at init when the wallet feature is enabled.
+ * @layer server
+ */
+
+/** An open grant with its remaining spendable value. */
+type OpenGrant = WalletEntry & {
+    remainingNanoUsd: bigint;
+};
+/** A page of wallet entries with the total count. */
+interface WalletEntryPage {
+    entries: WalletEntry[];
+    total: number;
+}
+/** Filter for {@link IWalletStore.listEntries}. */
+interface WalletEntryFilter {
+    from?: Date;
+    to?: Date;
+    type?: WalletEntryType;
+    limit?: number;
+    offset?: number;
+}
+/** The prepaid wallet port. */
+interface IWalletStore {
+    /** The wallet for a ref, or `null` when it does not exist yet. */
+    getWallet(ref: WalletRef): Promise<Wallet | null>;
+    /**
+     * Create the wallet when missing (idempotent) and append the entry plus any
+     * grant allocations in one transaction.
+     */
+    appendEntry(ref: WalletRef, entry: NewWalletEntry, allocations?: {
+        grantEntryId: string;
+        amountNanoUsd: bigint;
+    }[]): Promise<WalletEntry>;
+    /** Atomic conditional debit against the materialized balance. `null` = insufficient (§9.4). */
+    conditionalDebit(ref: WalletRef, entry: NewWalletEntry, overdraftNanoUsd: bigint): Promise<WalletEntry | null>;
+    /** Open grants with remaining value, ordered per `order` — feeds allocation. */
+    openGrants(ref: WalletRef, order: 'expiry' | 'priority' | 'fifo'): Promise<OpenGrant[]>;
+    /** A page of entries for a ref. */
+    listEntries(ref: WalletRef, filter?: WalletEntryFilter): Promise<WalletEntryPage>;
+    /** Recompute the materialized balance from Σ entries. */
+    reconcile(ref: WalletRef): Promise<Wallet>;
+}
+
+/**
+ * @fileoverview The aggregate persistence bundle (spec §4.1). Ledger + pricing
+ * are always required; the wallet and budget halves are `Partial` and validated
+ * at init only when the corresponding feature is configured.
+ * @layer server
+ */
+
+/**
+ * The single store object a host provides. `forRoot()` fans it out under each
+ * per-port DI token; a host may override any individual port by binding its token
+ * (§4.6).
+ */
+interface IAiTokensStore extends ILedgerStore, IPricingStore, Partial<IWalletStore>, Partial<IBudgetStore> {
+}
+
+/**
+ * @fileoverview The optional live cross-replica budget counter port (spec §15.1,
+ * §10.8). The fast path for budget enforcement; the DB conditional consume is the
+ * fallback. Values are serialized as int64 decimal strings. Implemented by the
+ * official Redis adapter (`./redis`).
+ * @layer server
+ */
+/** The live budget counter port. */
+interface IBudgetCounterStore {
+    /**
+     * Atomically increment `key` by `amount` iff the result stays `<= limit`,
+     * setting the TTL. Returns `false` when the increment would exceed the limit.
+     */
+    incrIfBelow(key: string, amount: bigint, limit: bigint, ttlSeconds: number): Promise<boolean>;
+    /** Decrement `key` by `amount` (release/reverse). */
+    decr(key: string, amount: bigint): Promise<void>;
+    /** Reset `key` (window rotation). */
+    reset(key: string): Promise<void>;
+}
+
+/**
+ * @fileoverview The token-estimation port (spec §14.2.1). Used by `hold()`
+ * pre-flight estimation and the aborted-stream fallback (§5.6). The library ships
+ * no tokenizer — the host plugs one in (tiktoken, provider count-tokens, …).
+ * @layer server
+ */
+
+/** A host-plugged token counter. */
+interface ITokenizer {
+    /** Count the tokens `text` consumes for the given model/provider (sync or async). */
+    countTokens(input: {
+        text: string;
+        model?: string;
+        provider?: ProviderId;
+    }): number | Promise<number>;
+}
+
+/**
+ * @fileoverview The OpenTelemetry telemetry port (spec §14.1). Emits `gen_ai.*`
+ * attributes and metrics. Content is never captured. Without a sink, telemetry is
+ * a no-op.
+ * @layer server
+ */
+
+/** A pluggable OpenTelemetry sink for gen_ai usage and duration signals. */
+interface ITelemetrySink {
+    /** Record a usage measurement with its `gen_ai.*` attributes. */
+    recordUsage(attributes: Record<string, string | number>, record: UsageRecord): void;
+    /** Optionally record an operation duration in milliseconds. */
+    recordDuration?(attributes: Record<string, string | number>, milliseconds: number): void;
+}
+
+/**
+ * @fileoverview The programmatic event-delivery port (spec §12.1). A sink ships
+ * events to webhooks, queues, or realtime fan-out. Sink failures are logged,
+ * never thrown into the metering path. `bigint` payload fields are serialized as
+ * decimal strings at the JSON boundary (§15.5).
+ * @layer server
+ */
+
+/** A programmatic sink for the library's typed events. */
+interface IEventSink {
+    /** Deliver one event (at-least-once). */
+    deliver(event: AiTokensEvent): Promise<void>;
+}
+
+/**
+ * @fileoverview The optional prompt/response content sidecar port (spec §14.2).
+ * The immutable ledger NEVER stores text; hosts opt into a separate, redacted,
+ * short-TTL sidecar. `purge()` supports erasure requests independently of the
+ * ledger.
+ * @layer server
+ */
+/** The opt-in, redacted, short-TTL content sidecar port. */
+interface IContentStore {
+    /** Persist masked text for a record with a TTL. */
+    put(input: {
+        usageRecordId: string;
+        tenantId: string;
+        role: 'prompt' | 'completion';
+        text: string;
+        ttlSeconds: number;
+    }): Promise<void>;
+    /** Delete stored text by tenant, record, or subject; returns the number purged. */
+    purge(filter: {
+        tenantId: string;
+        usageRecordId?: string;
+        subjectId?: string;
+    }): Promise<number>;
+}
+
+/**
+ * @fileoverview The markup-policy port (spec §7.2). Resolves the markup
+ * multiplier per call from the scope/model/feature context. Resolved once per
+ * record; the resolved 4-dp value is persisted. A throwing policy fails the call
+ * (never a silent 1.0 fallback).
+ * @layer server
+ */
+
+/** A host policy that varies the markup multiplier per call. */
+interface IMarkupPolicy {
+    /** Return the multiplier for this call (validated finite and `> 0`; sync or async). */
+    resolve(ctx: {
+        scope: MeteringScope;
+        provider: ProviderId;
+        model: string;
+        operation: AiOperation;
+        serviceTier: ServiceTier;
+        feature?: string;
+    }): number | Promise<number>;
+}
+
+/**
+ * @fileoverview The per-call metering context and the metered-result wrapper
+ * (spec §11.1). The context carries the payer scope, feature, normalization
+ * instructions, and idempotency key. It is TRUSTED INPUT — the host builds it
+ * from its VERIFIED auth layer, never from client-supplied body/query fields.
+ * @layer server
+ */
+
+/** Everything the metering path needs about one call. */
+interface MeteringContext {
+    tenantId: string;
+    /** The PAYER — enforcement target. */
+    scope: MeteringScope;
+    /** Optional distinct beneficiary (reporting dimension). */
+    beneficiary?: MeteringScope;
+    /** Optional actor id (audit). */
+    requestedBy?: string;
+    feature: string;
+    tags?: string[];
+    /** Normalization/rating instructions for `meter()`/interceptor. */
+    preset?: ProviderPreset;
+    ratingMode?: RatingMode;
+    /** Price-lookup override for deployment-named models (Azure/Bedrock) — §6.6. */
+    baseModel?: string;
+    /** Declared tier when it cannot come from the response (e.g. Batch API result files). */
+    serviceTier?: ServiceTier;
+    /** Non-token line items the provider does not report in usage. */
+    extraUnits?: Record<string, number>;
+    /** Strongly recommended; derive with `deriveIdempotencyKey(payload)` (§8.4). */
+    idempotencyKey?: string;
+    correlationId?: string;
+    /** `record()` only: also debit wallet + consume budgets post-hoc. Default `false`. */
+    enforce?: boolean;
+    isSystemCost?: boolean;
+    systemCostCategory?: string;
+}
+/** The wrapper `meter()` returns: the function result plus its settled usage record. */
+interface MeterResult<T> {
+    result: T;
+    usage: UsageRecord;
+}
+/** The pure pre-flight cost estimate `estimateCost()` returns. */
+interface CostEstimate {
+    rawCostNanoUsd: bigint;
+    billedCostNanoUsd: bigint;
+}
+
+/**
+ * @fileoverview The auth-hold types (spec §11.1). A {@link Hold} is a plain,
+ * method-free object that survives process boundaries (store it in Redis, hand it
+ * to a worker); `capture()`/`release()` revalidate it against the store AND the
+ * caller's tenant/scope (§14.4) and read the authoritative amounts from the pending
+ * record, so the Hold's own fields are informational. Its `bigint` money field
+ * crosses a JSON boundary via `toJsonSafe()` as a decimal string, exactly like every
+ * other library value (§15.5) — never `JSON.stringify` a bigint directly. A
+ * {@link HoldEstimate} is the discriminated union of ways to size a hold.
+ * @layer server
+ */
+
+/**
+ * A reservation over real wallet/budget headroom, settled by `capture()`. Plain and
+ * method-free; serialize with `toJsonSafe()` (its `bigint` field becomes a decimal
+ * string, §15.5) to cross a process/JSON boundary.
+ */
+interface Hold {
+    /** Equals the pending `UsageRecord` id. */
+    id: string;
+    tenantId: string;
+    scope: MeteringScope;
+    estimatedTokens: number;
+    /** Billed (post-markup) estimate. Serialize via `toJsonSafe()` at a JSON boundary (§15.5). */
+    estimatedCostNanoUsd: bigint;
+    expiresAt: Date;
+}
+/** The three ways to size a hold, as a discriminated union. */
+type HoldEstimate = {
+    provider: ProviderId;
+    model: string;
+    operation: AiOperation;
+    serviceTier?: ServiceTier;
+    inputTokens: number;
+    maxOutputTokens: number;
+} | {
+    tokens: number;
+} | {
+    amountNanoUsd: bigint;
+};
+
+/**
+ * @fileoverview The module configuration contract (spec §4.1) and the async
+ * dynamic-module options pattern. `store` is required; every feature block is
+ * opt-in and enables its service/guard only when present. All persisted money is
+ * nano-USD regardless of `currency` — that setting is presentation-only (§7.4).
+ * @layer server
+ */
+
+/** The synchronous configuration for `BymaxAiTokensModule.forRoot()`. */
+interface BymaxAiTokensModuleOptions {
+    /** Persistence adapter implementing the storage ports. REQUIRED. */
+    store: IAiTokensStore;
+    /**
+     * Resolves the metering scope from the current request for `BudgetGuard` and
+     * `MeteringInterceptor`. TRUSTED INPUT: read the host's VERIFIED auth context
+     * (JWT claims/session), never client-supplied body/query fields. REQUIRED only
+     * when the guard/interceptor/decorators are used.
+     */
+    scopeResolver?: (ctx: ExecutionContext) => MeteringContext | Promise<MeteringContext>;
+    /** Default rating mode; overridable per call/preset. Default `'rate-table'`. */
+    ratingMode?: RatingMode;
+    /** Presentation currency for reports/exports/status. Persisted money is always nano-USD. Default `'USD'`. */
+    currency?: string;
+    /**
+     * FX resolver USD → `currency`, returning integer nano-units of `currency` per
+     * USD. REQUIRED when `currency !== 'USD'` (else `AI_TOKENS_FX_REQUIRED` at init).
+     */
+    fx?: (date: Date, currency: string) => Promise<bigint> | bigint;
+    /** Price registry behavior. */
+    pricing?: {
+        /** Seed from `MODEL_PRICES_SEED` on first boot (idempotent, advisory-locked). Default `true`. */
+        seedFromSnapshot?: boolean;
+        /** Throw `AI_TOKENS_PRICE_NOT_FOUND` when no rate matches; else cost 0 + `priceMissing`. Default `true`. */
+        strict?: boolean;
+        /** In-memory rate cache TTL. Default `300_000` ms. */
+        cacheTtlMs?: number;
+        /** Model-ID alias map consulted during rate resolution (§6.6). */
+        modelAliases?: Record<string, string>;
+    };
+    /**
+     * Markup / margin — a flat multiplier or a policy object. Validated finite, `> 0`,
+     * at most 4 decimal places. Default `1.0` (bill at cost).
+     */
+    markup?: number | IMarkupPolicy;
+    /** Enables `WalletService` when present. */
+    wallets?: {
+        /** 1 credit = this many nano-USD. Default `1_000_000_000n` (1 credit = $1). */
+        creditRateNanoUsd?: bigint;
+        /** Allowed negative balance (postpaid overdraft) in nano-USD. Default `0n`. */
+        overdraftNanoUsd?: bigint;
+        /** Grant burn order. Default `'expiry'`. */
+        burnOrder?: 'expiry' | 'priority' | 'fifo';
+    };
+    /** Enables `BudgetService` + `BudgetGuard` when present. */
+    budgets?: {
+        /** Default enforcement policy when a budget is exceeded. Default `'block'`. */
+        defaultPolicy?: BudgetPolicy;
+        /** Soft-alert thresholds as fractions of the limit. Default `[0.8, 1.0]`. */
+        alertThresholds?: number[];
+        /** Optional live cross-replica spend counter (Redis). Falls back to DB atomic consume. */
+        counter?: IBudgetCounterStore;
+        /** Enforce budgets as a hard ceiling even if the counter store is unavailable. Default `true`. */
+        failClosed?: boolean;
+        /** Host callback invoked when a matched budget has policy `'throttle'`. */
+        onThrottle?: (ctx: {
+            context: MeteringContext;
+            budget: Budget;
+            status: BudgetStatus;
+        }) => void | Promise<void>;
+    };
+    /** Hold lifecycle (applies whenever `hold()`/`meter()` is used). */
+    holds?: {
+        /** Pending-hold TTL; expired holds are swept. Default `3_600` s. */
+        ttlSeconds?: number;
+        /** Reaper sweep interval. Default `300` s. */
+        reaperIntervalSeconds?: number;
+    };
+    /** Ledger extras. */
+    ledger?: {
+        /** Per-tenant tamper-evident hash chain over posted records (§8.6). Default `false`. */
+        hashChain?: boolean;
+    };
+    /** Pre-flight token estimation used by `hold()` when the caller supplies text instead of counts. */
+    tokenizer?: ITokenizer;
+    /** Typed event emission (§12). */
+    events?: {
+        /** Emit through `@nestjs/event-emitter` when installed. Default `true`. */
+        emitter?: boolean;
+        /** Additional programmatic sink (webhooks, queues). */
+        sink?: IEventSink;
+    };
+    /** OpenTelemetry emission of `gen_ai.*` attributes and metrics. */
+    telemetry?: {
+        sink?: ITelemetrySink;
+        /** Emit token-usage + duration metrics. Default `true` when a sink is present. */
+        metrics?: boolean;
+    };
+    /** Reporting + export. */
+    reporting?: {
+        /** Max rows a single export streams before requiring pagination. Default `1_000_000`. */
+        maxExportRows?: number;
+    };
+    /**
+     * PII policy for the optional prompt/response text sidecar. The immutable ledger
+     * NEVER stores text. Default `undefined` (no text is ever stored).
+     */
+    content?: {
+        store: IContentStore;
+        /** Mask function applied before persistence. */
+        mask?: (text: string) => string;
+        /** Retention in seconds. Default `604_800` (7 days). */
+        ttlSeconds?: number;
+    };
+}
+/** Factory contract for `useExisting` / `useClass` async configuration. */
+interface BymaxAiTokensModuleOptionsFactory {
+    createAiTokensOptions(): BymaxAiTokensModuleOptions | Promise<BymaxAiTokensModuleOptions>;
+}
+/**
+ * Asynchronous configuration for `BymaxAiTokensModule.forRootAsync()` — the
+ * standard NestJS async dynamic-module options shape (the async factory is not
+ * yet wired; the contract is defined here).
+ */
+interface BymaxAiTokensModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+    useFactory?: (...args: unknown[]) => BymaxAiTokensModuleOptions | Promise<BymaxAiTokensModuleOptions>;
+    inject?: readonly (string | symbol | Type<unknown>)[];
+    useExisting?: Type<BymaxAiTokensModuleOptionsFactory>;
+    useClass?: Type<BymaxAiTokensModuleOptionsFactory>;
+}
+
+/**
+ * @fileoverview The `@Global()` dynamic module (spec §2.1/§4.4/§4.6). `forRoot()`
+ * validates and resolves the options synchronously; `forRootAsync()` resolves them
+ * from injected dependencies (`useFactory`/`useClass`/`useExisting`). Both feed the
+ * SAME options-agnostic core providers (each derives its value from the resolved
+ * `BYMAX_AI_TOKENS_OPTIONS` token, so wiring is shared by construction), fanning the
+ * single `store` object out under each per-port token. `forRoot()` registers the
+ * wallet/budget providers only when their feature block is present; `forRootAsync()`
+ * — which cannot inspect the options at module-definition time — registers them
+ * unconditionally, resolving to `null` when disabled (services treat `null` as
+ * absent). The module is global so the guard/interceptor are injectable anywhere.
+ * @layer server/module
+ */
+
+/**
+ * The root NestJS dynamic module for `@bymax-one/nest-ai-tokens`. Register once
+ * at application root with `forRoot()` or `forRootAsync()`. Exports the metering,
+ * pricing, ledger, wallet, budget, report services and the enforcement primitives.
+ */
+declare class BymaxAiTokensModule {
+    /**
+     * 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: BymaxAiTokensModuleOptions): DynamicModule;
+    /**
+     * 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: BymaxAiTokensModuleAsyncOptions): DynamicModule;
+}
+
+/**
+ * @fileoverview The eleven `Symbol()` dependency-injection tokens (spec §4.5).
+ * `forRoot()` registers the resolved options plus each store port and optional
+ * collaborator under these tokens; a host may override any individual port by
+ * binding its token directly (§4.6).
+ * @layer server
+ */
+/** The fully-resolved {@link ResolvedAiTokensOptions} object. */
+declare const BYMAX_AI_TOKENS_OPTIONS: unique symbol;
+/** The ledger store port. */
+declare const BYMAX_AI_TOKENS_LEDGER_STORE: unique symbol;
+/** The pricing store port. */
+declare const BYMAX_AI_TOKENS_PRICING_STORE: unique symbol;
+/** The wallet store port (only bound when wallets are enabled). */
+declare const BYMAX_AI_TOKENS_WALLET_STORE: unique symbol;
+/** The budget store port (only bound when budgets are enabled). */
+declare const BYMAX_AI_TOKENS_BUDGET_STORE: unique symbol;
+/** The optional live budget counter port. */
+declare const BYMAX_AI_TOKENS_BUDGET_COUNTER: unique symbol;
+/** The optional tokenizer port. */
+declare const BYMAX_AI_TOKENS_TOKENIZER: unique symbol;
+/** The optional telemetry sink port. */
+declare const BYMAX_AI_TOKENS_TELEMETRY: unique symbol;
+/** The optional event sink port. */
+declare const BYMAX_AI_TOKENS_EVENT_SINK: unique symbol;
+/** The optional content sidecar port. */
+declare const BYMAX_AI_TOKENS_CONTENT_STORE: unique symbol;
+/** The optional logger. */
+declare const BYMAX_AI_TOKENS_LOGGER: unique symbol;
+
+/**
+ * @fileoverview The fully-resolved options every service consumes (spec §4.2/§4.6).
+ * Each opt-in feature is a discriminated union — `{ enabled: false }` or
+ * `{ enabled: true, ...resolved }` — so services never branch on `undefined`.
+ * @layer server
+ */
+
+/** Resolved pricing behavior. */
+interface ResolvedPricingOptions {
+    seedFromSnapshot: boolean;
+    strict: boolean;
+    cacheTtlMs: number;
+    modelAliases: Record<string, string>;
+}
+/** Resolved hold lifecycle. */
+interface ResolvedHoldsOptions {
+    ttlSeconds: number;
+    reaperIntervalSeconds: number;
+}
+/** Resolved ledger extras. */
+interface ResolvedLedgerOptions {
+    hashChain: boolean;
+}
+/** Resolved event emission. */
+interface ResolvedEventsOptions {
+    emitter: boolean;
+    sink?: IEventSink | undefined;
+}
+/** Resolved reporting limits. */
+interface ResolvedReportingOptions {
+    maxExportRows: number;
+}
+/** Resolved wallet feature (disabled or fully-resolved). */
+type ResolvedWalletsOptions = {
+    enabled: false;
+} | {
+    enabled: true;
+    creditRateNanoUsd: bigint;
+    overdraftNanoUsd: bigint;
+    burnOrder: 'expiry' | 'priority' | 'fifo';
+};
+/** Resolved budget feature (disabled or fully-resolved). */
+type ResolvedBudgetsOptions = {
+    enabled: false;
+} | {
+    enabled: true;
+    defaultPolicy: BudgetPolicy;
+    alertThresholds: readonly number[];
+    failClosed: boolean;
+    counter?: IBudgetCounterStore | undefined;
+    onThrottle?: BudgetThrottleCallback | undefined;
+};
+/** The host callback invoked when a matched budget has policy `'throttle'`. */
+type BudgetThrottleCallback = (ctx: {
+    context: MeteringContext;
+    budget: Budget;
+    status: BudgetStatus;
+}) => void | Promise<void>;
+/** Resolved telemetry feature (disabled or fully-resolved). */
+type ResolvedTelemetryOptions = {
+    enabled: false;
+} | {
+    enabled: true;
+    sink: ITelemetrySink;
+    metrics: boolean;
+};
+/** Resolved content sidecar feature (disabled or fully-resolved). */
+type ResolvedContentOptions = {
+    enabled: false;
+} | {
+    enabled: true;
+    store: IContentStore;
+    mask?: ((text: string) => string) | undefined;
+    ttlSeconds: number;
+};
+/** The fully-resolved options object bound under `BYMAX_AI_TOKENS_OPTIONS`. */
+interface ResolvedAiTokensOptions {
+    store: IAiTokensStore;
+    scopeResolver?: ((ctx: ExecutionContext) => MeteringContext | Promise<MeteringContext>) | undefined;
+    ratingMode: RatingMode;
+    currency: string;
+    fx?: ((date: Date, currency: string) => Promise<bigint> | bigint) | undefined;
+    /** A resolved 4-dp multiplier or a markup policy. */
+    markup: number | IMarkupPolicy;
+    pricing: ResolvedPricingOptions;
+    wallets: ResolvedWalletsOptions;
+    budgets: ResolvedBudgetsOptions;
+    holds: ResolvedHoldsOptions;
+    ledger: ResolvedLedgerOptions;
+    tokenizer?: ITokenizer | undefined;
+    events: ResolvedEventsOptions;
+    telemetry: ResolvedTelemetryOptions;
+    reporting: ResolvedReportingOptions;
+    content: ResolvedContentOptions;
+}
+
+/**
+ * @fileoverview `PricingService` — effective-dated rate resolution with the §6.6
+ * six-step model-resolution chain, an in-memory TTL cache, price upserts, and the
+ * idempotent snapshot seed (§6.3/§6.4). A call is priced at the rate in effect at
+ * its timestamp; batch/flex/priority tiers must find their own row (no silent
+ * fallback to standard rates).
+ * @layer server
+ */
+
+/** Inputs to {@link PricingService.resolveRate}. */
+interface ResolveRateInput {
+    provider: ProviderId;
+    model: string;
+    operation: AiOperation;
+    at: Date;
+    /** Defaults to `'standard'`. */
+    serviceTier?: ServiceTier;
+    /** Price-lookup override for deployment-named models (Azure/Bedrock) — §6.6 step 2. */
+    baseModel?: string;
+}
+/**
+ * Effective-dated rate resolution with a six-step model-resolution chain, an
+ * in-memory TTL cache, price upserts, and idempotent snapshot seed. Past
+ * records are never re-rated (point-in-time pricing). See file overview.
+ */
+declare class PricingService implements OnModuleInit {
+    private readonly options;
+    private readonly store;
+    private readonly now;
+    private readonly cache;
+    /**
+     * @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: ResolvedAiTokensOptions, store: IPricingStore, now?: () => number);
+    /** Seed the registry on boot when enabled. */
+    onModuleInit(): Promise<void>;
+    /**
+     * 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.
+     */
+    resolveRate(input: ResolveRateInput): Promise<PriceVersion | null>;
+    /**
+     * 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.
+     */
+    upsertPrice(input: NewPriceVersion): Promise<PriceVersion>;
+    /** Full effective-dated history for a tuple. */
+    getPriceHistory(provider: ProviderId, model: string, operation: AiOperation, serviceTier?: ServiceTier): Promise<PriceVersion[]>;
+    /** Seed the registry from the pinned snapshot; idempotent and advisory-locked. */
+    seedFromSnapshot(): Promise<void>;
+    /** The §6.6 six-step model-resolution chain (exact → baseModel → alias → normalized → prefix). */
+    private resolveUncached;
+    /** §6.6 step 5: longest-`startsWith` match among priced models for provider+operation+tier. */
+    private resolveByLongestPrefix;
+}
+
+/**
+ * @fileoverview The optional per-tenant tamper-evident hash chain (spec §8.6).
+ * When `ledger.hashChain` is enabled, each SETTLED record (`posted`, including
+ * compensating records) hashes the previous settled record for its tenant, so any
+ * post-hoc modification of a record's content becomes detectable — the SOC 2
+ * expectation for billing records.
+ *
+ * The hashed field set is the immutable settled content: the payload-hash fields
+ * (§8.4) plus the record `id`. `status` and `reversedByRecordId` are deliberately
+ * EXCLUDED because the sole permitted post-posting mutation is the annotation-only
+ * `posted → reversed` flip (§8.3): the chain must survive it (a reversed record
+ * keeps its settlement hash, §8.6 rule 1), so the hash cannot depend on fields
+ * that the annotation changes. Any change to a content, cost, token, or id field
+ * breaks the chain.
+ *
+ * THROUGHPUT CAVEAT (§20.2): enabling the chain serializes posted writes per tenant
+ * (a Postgres advisory lock in the official adapter) — a measurable cost on hot
+ * tenants. Leave `ledger.hashChain` off unless tamper evidence is required.
+ * @layer server
+ */
+
+/** The outcome of {@link LedgerService.verifyChain}: intact, or the first broken record. */
+type ChainVerification = {
+    valid: true;
+} | {
+    valid: false;
+    brokenAtRecordId: string;
+};
+
+/**
+ * @fileoverview `LedgerService` — the append-only usage ledger core over
+ * `ILedgerStore` (spec §8): exactly-once append (payload-hash replay-or-conflict,
+ * §8.4), filtered queries, cost aggregation, the lifecycle state machine
+ * (`transition`, §8.3), the ledger-only compensation primitive (`reverse`, §8.5
+ * steps 1–2), and the opt-in per-tenant tamper-evident hash chain (§8.6). Balance
+ * and spend math sums `posted` + `reversed` records only (§8.3), so those are the
+ * default query statuses. The service NEVER issues an `UPDATE`/`DELETE` of a posted
+ * amount — corrections are compensating records (a `posted` row with negated
+ * amounts) and the sole permitted post-posting mutation is the annotation-only
+ * `posted → reversed` flip.
+ * @layer server
+ */
+
+/**
+ * Caller-supplied fields for {@link LedgerService.append}; the service derives
+ * `idempotencyKey` (from `ctxKey` or a random UUID) and `totalTokens`.
+ */
+type LedgerAppendInput = Omit<NewUsageRecord, 'idempotencyKey' | 'totalTokens'>;
+/** The resolved-options subset the ledger consumes (the hash-chain flag, §8.6). */
+type LedgerServiceOptions = Pick<ResolvedAiTokensOptions, 'ledger'>;
+/**
+ * Audit hook invoked by {@link LedgerService.verifyChain}. The module wires it to
+ * the event dispatcher's `ai_tokens.audit` emission; it defaults to a no-op so the
+ * service has no dependency cycle on the dispatcher.
+ */
+type LedgerAuditHook = (action: string, details: Record<string, unknown>) => void;
+/**
+ * Append-only usage ledger over {@link ILedgerStore}. Provides exactly-once
+ * append (content-derived idempotency), lifecycle transitions, filtered queries,
+ * cost aggregation, and the ledger-only compensation primitive. See file overview.
+ */
+declare class LedgerService {
+    private readonly store;
+    private readonly options;
+    private readonly audit;
+    /**
+     * @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: ILedgerStore, options?: LedgerServiceOptions, audit?: LedgerAuditHook);
+    /** Whether the per-tenant tamper-evident hash chain is enabled (§8.6). */
+    private get hashChainEnabled();
+    /**
+     * 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.
+     */
+    append(input: LedgerAppendInput, ctxKey?: string): Promise<UsageRecord>;
+    /**
+     * 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: string, key: string): Promise<UsageRecord | null>;
+    /**
+     * 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: string): Promise<UsageRecord | null>;
+    /**
+     * 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: Date, limit: number): Promise<UsageRecord[]>;
+    /**
+     * 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: LedgerFilter): Promise<UsageRecord[]>;
+    /**
+     * 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: LedgerFilter): Promise<LedgerCostSummary>;
+    /** Default the status filter to the balance-contributing statuses when unset. */
+    private withBalanceStatuses;
+    /**
+     * 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.
+     */
+    transition(id: string, from: UsageStatus, to: UsageStatus, patch?: Partial<UsageRecord>): Promise<UsageRecord | null>;
+    /**
+     * 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 }`.
+     */
+    verifyChain(tenantId: string, from?: Date, to?: Date): Promise<ChainVerification>;
+    /**
+     * 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`.
+     */
+    reverse(recordId: string, reason: string): Promise<UsageRecord>;
+    /**
+     * 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.
+     */
+    private assertLegalTransition;
+}
+
+/**
+ * @fileoverview `MarkupResolver` — the internal per-call markup engine (spec §7.2).
+ * Resolves the billed/raw multiplier from either a static number (validated and
+ * rounded to 4 dp at init) or an `IMarkupPolicy` (resolved and validated per call),
+ * and returns the resolved 4-dp value plus a bound `applyMarkup` so the caller
+ * persists exactly what was applied. Markup applies in BOTH rating modes (§2.3) —
+ * the returned `apply` is used on a rate-table cost and on a provider-reported cost
+ * alike. A policy that throws or returns an invalid multiplier fails the call with
+ * `AI_TOKENS_INVALID_CONFIG` — never a silent `1.0` fallback. Internal: not part of
+ * the public barrel; the module registers it.
+ * @layer server
+ */
+
+/** The per-call context an `IMarkupPolicy` receives (spec §7.2). */
+type MarkupContext = Parameters<IMarkupPolicy['resolve']>[0];
+/** The resolved markup: the 4-dp multiplier actually applied plus a bound applier. */
+interface ResolvedMarkup {
+    /** The resolved 4-dp multiplier — persist this on the record. */
+    multiplier: number;
+    /** Apply the resolved multiplier to a raw provider cost, exact bigint nano-USD. */
+    apply: (rawCostNanoUsd: bigint) => bigint;
+}
+/**
+ * Resolves the effective markup multiplier for a metering context, delegating
+ * to a host-supplied {@link IMarkupPolicy} when configured, or using the fixed
+ * module-level `options.markup` value as the default.
+ */
+declare class MarkupResolver {
+    private readonly options;
+    /**
+     * @param options The resolved options carrying the markup (a 4-dp number or a policy).
+     */
+    constructor(options: Pick<ResolvedAiTokensOptions, 'markup'>);
+    /**
+     * 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.
+     */
+    resolve(context: MarkupContext): Promise<ResolvedMarkup>;
+    /** Invoke a host policy, wrapping any failure as an invalid-config error. */
+    private invokePolicy;
+    /** Validate + round a policy's multiplier to 4 dp, or fail the call. */
+    private validate;
+}
+
+/**
+ * @fileoverview `TelemetryEmitter` — emits OpenTelemetry GenAI (`gen_ai.*`) usage
+ * and duration signals for every posted record through the pluggable
+ * {@link ITelemetrySink} (spec §14.1). It imports NOTHING from `@opentelemetry/api`
+ * — the sink port isolates that optional peer, so the host's sink owns the SDK.
+ * NO CONTENT: only token counts, model, provider, operation, and service tier
+ * become attributes — prompt/completion text never reaches telemetry. When no sink
+ * is configured every call is a cheap no-op that allocates no attribute object
+ * (the null guard runs before {@link buildGenAiAttributes}).
+ * @layer server
+ */
+
+/** Emits GenAI telemetry through a sink, or does nothing when none is configured. */
+declare class TelemetryEmitter {
+    private readonly sink;
+    /** @param sink The host telemetry sink, or `null` to disable telemetry. */
+    constructor(sink: ITelemetrySink | null);
+    /**
+     * Record a usage measurement for a posted record (no-op without a sink).
+     *
+     * @param record The posted usage record.
+     */
+    recordUsage(record: UsageRecord): void;
+    /**
+     * 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: UsageRecord, milliseconds: number): void;
+}
+
+/**
+ * @fileoverview `ContentCapture` — the ONLY path prompt/completion text may enter
+ * the library (spec §14.2/§14.3). It is OFF by default: unless `options.content` is
+ * configured, `capture()` is a pure no-op and no text is touched. When enabled it
+ * masks each text via `content.mask` (default identity), then writes it to the
+ * opt-in, short-TTL {@link IContentStore} sidecar under its role. The immutable
+ * ledger, events, telemetry, and logs NEVER receive text — a sidecar failure is
+ * logged (without the text) and never breaks the metering path. `IContentStore.purge`
+ * supports erasure independently of the ledger. Internal — not part of the public barrel.
+ * @layer server
+ */
+
+/** The text a host explicitly hands the library for the sidecar (never sourced by the library). */
+interface CaptureContentInput {
+    usageRecordId: string;
+    tenantId: string;
+    prompt?: string | undefined;
+    completion?: string | undefined;
+}
+/**
+ * The ONLY path through which prompt/completion text may enter the library.
+ * Disabled by default; when enabled, masks and forwards text to the opt-in
+ * {@link IContentStore} sidecar. A sidecar failure is always non-fatal. Internal.
+ */
+declare class ContentCapture {
+    private readonly options;
+    private readonly logger;
+    /** @param options The resolved content-sidecar settings (disabled by default). */
+    constructor(options: ResolvedContentOptions);
+    /**
+     * 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.
+     */
+    capture(input: CaptureContentInput): Promise<void>;
+}
+
+/**
+ * @fileoverview `WalletService` — the prepaid-credit facade over `IWalletStore`
+ * (spec §9.2). Wallets hold nano-USD balances as append-only entries
+ * (grant/debit/refund/adjustment/expiry) with a materialized balance column for
+ * atomic debits. `grant`/`debit`/`refund`/`adjust` each carry a per-wallet
+ * idempotency key (replay-or-conflict, §15.2); `debit` is the race-safe
+ * conditional path (§9.4) — the store reserves against the materialized balance,
+ * sweeps expired grants, and records the grant burn-down allocation trail (§9.3) in
+ * one atomic operation, so the service never does a check-then-write. `getBalance`
+ * reports the materialized balance; grant/adjust are admin-plane mutations that the
+ * host MUST restrict to privileged roles and that emit `ai_tokens.audit` (§14.4).
+ * `'key'` scopes cannot own money (§9.1). All amounts are bigint nano-USD.
+ * @layer server
+ */
+
+/** The resolved wallet settings the service consumes (the enabled half of the union). */
+type WalletServiceOptions = Extract<ResolvedWalletsOptions, {
+    enabled: true;
+}>;
+/** A wallet balance in nano-USD plus its presentation credits. */
+interface WalletBalance {
+    nanoUsd: bigint;
+    credits: number;
+}
+/** Input to {@link WalletService.grant}. */
+interface GrantInput {
+    amountNanoUsd: bigint;
+    priority?: number;
+    effectiveAt?: Date;
+    expiresAt?: Date;
+    idempotencyKey: string;
+    reason: string;
+}
+/** Input to {@link WalletService.debit}. */
+interface DebitInput {
+    amountNanoUsd: bigint;
+    usageRecordId?: string;
+    idempotencyKey: string;
+    reason?: string;
+}
+/** Input to {@link WalletService.refund}. */
+interface RefundInput {
+    amountNanoUsd: bigint;
+    usageRecordId?: string;
+    idempotencyKey: string;
+    reason: string;
+}
+/** Input to {@link WalletService.adjust}. */
+interface AdjustInput {
+    amountNanoUsd: bigint;
+    idempotencyKey: string;
+    reason: string;
+}
+/** Input to {@link WalletService.settleAdjustment}: the signed capture ±delta. */
+interface SettleAdjustmentInput {
+    /** The signed adjustment amount (`!= 0`): `+` credits, `−` debits. */
+    amountNanoUsd: bigint;
+    usageRecordId?: string;
+    idempotencyKey: string;
+    reason: string;
+}
+/**
+ * The event hooks `WalletService` fires; the module wires them to the dispatcher
+ * (default no-op so the service has no dependency cycle on the event dispatcher).
+ */
+interface WalletEventHooks {
+    granted(ref: WalletRef, data: WalletGrantedEventData): void | Promise<void>;
+    depleted(ref: WalletRef, data: WalletDepletedEventData): void | Promise<void>;
+    audit(action: string, details: Record<string, unknown>): void | Promise<void>;
+}
+/**
+ * Prepaid-credit facade over {@link IWalletStore}. Wallets hold nano-USD
+ * balances as append-only entries (grant/debit/refund/adjust) with a
+ * materialized balance column for atomic debits. See file overview.
+ */
+declare class WalletService {
+    private readonly store;
+    private readonly options;
+    private readonly events;
+    /**
+     * @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: IWalletStore, options: WalletServiceOptions, events?: WalletEventHooks);
+    /**
+     * The current balance, excluding not-yet-effective and expired grants (§9.2).
+     * Reads the materialized balance; expiry is applied lazily on debit, so a grant
+     * that lapses purely with the passage of time is reflected at the next debit or
+     * `reconcile` (the documented §9.3 lazy-materialization trade-off).
+     *
+     * @param ref The wallet owner (a `'tenant' | 'team' | 'user'`, never `'key'`).
+     * @returns The nano-USD balance and its presentation credits.
+     */
+    getBalance(ref: WalletRef): Promise<WalletBalance>;
+    /**
+     * 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.
+     */
+    grant(ref: WalletRef, input: GrantInput): Promise<WalletEntry>;
+    /**
+     * 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.
+     */
+    debit(ref: WalletRef, input: DebitInput): Promise<WalletEntry>;
+    /**
+     * 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.
+     */
+    refund(ref: WalletRef, input: RefundInput): Promise<WalletEntry>;
+    /**
+     * 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.
+     */
+    adjust(ref: WalletRef, input: AdjustInput): Promise<WalletEntry>;
+    /**
+     * 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.
+     */
+    settleAdjustment(ref: WalletRef, input: SettleAdjustmentInput): Promise<WalletEntry>;
+    /**
+     * 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.
+     */
+    getEntries(ref: WalletRef, filter?: WalletEntryFilter): Promise<WalletEntryPage>;
+    /**
+     * 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.
+     */
+    reconcile(ref: WalletRef): Promise<WalletBalance>;
+    /** Append a non-debit entry, mapping a store idempotency/missing-wallet signal to the catalog. */
+    private append;
+    /** Run the atomic conditional debit, mapping `null` to insufficient credits (§9.4). */
+    private conditionalDebit;
+    /** Map a store idempotency conflict / missing-wallet signal to the typed catalog error. */
+    private mapStoreError;
+    /** Reject a `'key'` owner at runtime (`'key'` scopes cannot own money, §9.1). */
+    private assertOwner;
+    /** Present a nano-USD balance as credits (presentation-only division). */
+    private toCredits;
+    /** Build the invalid-config exception with an actionable reason. */
+    private invalid;
+}
+
+/**
+ * @fileoverview `BudgetService` — multi-dimension budget CRUD, enforcement, and
+ * the read-side status query (spec §10). Budgets cap spend/tokens/operation-count
+ * per scope per window; windows anchor to calendar UTC or a per-subject `anchorAt`
+ * with month-end clamping (§10.1). Unlimited semantics are NORMATIVE (§10.2): no
+ * budget row / an absent limit = unlimited, a present `0` = a hard block, negatives
+ * are rejected at validation. Every matching budget across the scope hierarchy is
+ * checked and consumes INDEPENDENTLY (§10.3). Consumption is race-safe: `'block'`
+ * budgets go through the atomic §10.8 `conditionalConsume` (never a check-then-write)
+ * and roll back on any partial failure; `'allow'`/`'throttle'` record spend and
+ * signal. `reconcileWindow` recomputes a window from the ledger with the SAME §10.7
+ * predicate. `upsertBudget`/`removeBudget`/`rotateWindow` are admin-plane mutations
+ * the host MUST restrict to privileged roles and that emit `ai_tokens.audit` (§14.4).
+ * All money is bigint nano-USD.
+ * @layer server
+ */
+
+/** The resolved budget settings the service consumes (the enabled half of the union). */
+type BudgetServiceOptions = Extract<ResolvedBudgetsOptions, {
+    enabled: true;
+}>;
+/** Input to {@link BudgetService.upsertBudget}: `softThresholds`/`policy` default from options. */
+type UpsertBudgetInput = Omit<Budget, 'id' | 'createdAt' | 'softThresholds' | 'policy'> & {
+    id?: string;
+    softThresholds?: number[];
+    policy?: BudgetPolicy;
+};
+/** The event hooks `BudgetService` fires; the module wires them to the dispatcher. */
+interface BudgetEventHooks {
+    thresholdCrossed(tenantId: string, scope: MeteringScope, data: BudgetThresholdCrossedEventData): void | Promise<void>;
+    exceeded(tenantId: string, scope: MeteringScope, data: BudgetExceededEventData): void | Promise<void>;
+    projectedExceeded(tenantId: string, scope: MeteringScope, data: BudgetProjectedExceededEventData): void | Promise<void>;
+    audit(action: string, details: Record<string, unknown>): void | Promise<void>;
+}
+/**
+ * Multi-dimension budget CRUD, enforcement, and read-side status queries.
+ * Budgets cap spend/tokens/operation-count per scope per window; unlimited
+ * semantics are NORMATIVE (no row = no budget; 0 = block all). See file overview.
+ */
+declare class BudgetService {
+    private readonly store;
+    private readonly ledger;
+    private readonly options;
+    private readonly now;
+    private readonly events;
+    private readonly logger;
+    /** Highest soft-threshold emitted per `(budgetId, windowStartISO)` — per-instance dedupe (§20). */
+    private readonly notifiedThreshold;
+    /** Windows that have already emitted a projected-exceeded event, per instance. */
+    private readonly projected;
+    /**
+     * @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: IBudgetStore, ledger: LedgerService, options: BudgetServiceOptions, now?: () => Date, events?: BudgetEventHooks);
+    /**
+     * 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]`.
+     */
+    upsertBudget(input: UpsertBudgetInput): Promise<Budget>;
+    /**
+     * Delete a budget (ADMIN PLANE — §14.4). Emits `ai_tokens.audit`.
+     *
+     * @param budgetId The budget id.
+     * @param tenantId The owning tenant (audit context).
+     */
+    removeBudget(budgetId: string, tenantId: string): Promise<void>;
+    /**
+     * 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: string, scope?: MeteringScope): Promise<Budget[]>;
+    /**
+     * 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.
+     */
+    rotateWindow(budgetId: string, newWindowStart?: Date): Promise<void>;
+    /**
+     * 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.
+     */
+    consume(context: MeteringContext, delta: BudgetDelta): Promise<void>;
+    /**
+     * 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.
+     */
+    release(context: MeteringContext, delta: BudgetDelta): Promise<void>;
+    /**
+     * 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.
+     */
+    adjust(context: MeteringContext, delta: BudgetDelta): Promise<void>;
+    /**
+     * 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.
+     */
+    private adjustCounter;
+    /** Discard a diverged counter and reseed it to the authoritative DB window spend (§10.8). */
+    private resyncCounter;
+    /**
+     * 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.
+     */
+    reconcileWindow(budgetId: string, windowStart: Date): Promise<void>;
+    /**
+     * 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)
+     */
+    status(tenantId: string, scope: MeteringScope): Promise<BudgetStatus[]>;
+    /** Apply consumption for one located window (throws through {@link blockExceeded} on a hard shortfall). */
+    private applyConsumption;
+    /**
+     * 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.
+     */
+    private guardedConsume;
+    /**
+     * 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).
+     */
+    private counterFastPath;
+    /** Run the authoritative DB consume, rolling the counter back on a shortfall and failing closed on an outage. */
+    private databaseConsume;
+    /** Best-effort counter decrement (rollback); failures are logged, never thrown. */
+    private decrCounters;
+    /**
+     * 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.
+     */
+    private blockExceeded;
+    /** Signal an over-limit `'allow'`/`'throttle'` budget (records spend, never throws). */
+    private softOverLimit;
+    /** Invoke the host throttle callback (or warn + allow when none is configured). */
+    private throttle;
+    /** Emit each soft threshold crossed by this delta, once per window (per-instance dedupe). */
+    private signalThresholds;
+    /** Emit one `threshold_crossed` event. */
+    private emitThreshold;
+    /** Emit `projected_exceeded` once per window when the burn rate projects crossing before reset. */
+    private signalProjection;
+    /** The matching, feature-relevant budgets located in the current window. */
+    private matchingWindows;
+    /** Undo every recorded consumption (signed DB subtraction + live-counter decrement). */
+    private rollback;
+    /** Load a budget by id or throw an invalid-config error. */
+    private requireBudget;
+    /** Validate the §10.2 limit rules: no negatives and at least one limit dimension. */
+    private assertLimits;
+}
+
+/**
+ * @fileoverview `MeteringService` — the public metering facade (spec §11). It
+ * carries the whole lifecycle: the post-hoc `record()` (observe-only, or
+ * enforcing post-hoc with `enforce: true`), the pure `estimateCost()`, and the
+ * auth-hold flow `hold()` → `capture()` / `release()` plus the `meter()` wrapper,
+ * the orchestrated `reverse()`, and the combined `getStatus()`. Per the §11.2
+ * side-effect matrix: a hold reserves (budget consume → wallet debit, each step
+ * compensated), a capture settles the ±delta and is IDEMPOTENT, a release/reaper
+ * restores in full and NEVER bills, and `isSystemCost` rows touch only the ledger
+ * and events. Money is bigint nano-USD; no prompt/response text ever reaches the
+ * ledger, events, or logs.
+ * @layer server
+ */
+
+/** Input to {@link MeteringService.record}. */
+interface RecordInput {
+    /** Raw provider usage OR an already-normalized {@link NormalizedUsage}. */
+    usage: unknown;
+    /** Preset carrying the normalizer + rating mode (alternative to `normalizer`). */
+    preset?: ProviderPreset;
+    /** A bare normalizer (alternative to `preset`). */
+    normalizer?: UsageNormalizer;
+    /** The per-call metering context (trusted input from the host's auth layer). */
+    context: MeteringContext;
+    /** When the call happened; defaults to now (backfills pass the original time). */
+    occurredAt?: Date;
+    /**
+     * The ONLY path prompt/completion text enters the library (spec §14.2): masked +
+     * TTL'd into the opt-in content sidecar, dropped entirely when the feature is off.
+     * Never persisted to the ledger, events, telemetry, or logs.
+     */
+    content?: {
+        prompt?: string;
+        completion?: string;
+    };
+}
+/** Input to {@link MeteringService.estimateCost}. */
+interface EstimateCostInput {
+    provider: ProviderId;
+    model: string;
+    operation: AiOperation;
+    serviceTier?: ServiceTier;
+    inputTokens: number;
+    maxOutputTokens: number;
+    at?: Date;
+    /** Lets a markup policy resolve; defaults to a neutral estimate scope. */
+    scope?: MeteringScope;
+    feature?: string;
+}
+/** The event hooks the lifecycle fires; the module wires them to the dispatcher (default no-op). */
+interface MeteringEventHooks {
+    usageRecorded(record: UsageRecord): Promise<void>;
+    priceMissing(record: UsageRecord): Promise<void>;
+    holdReleased(record: UsageRecord, reason: string, expired: boolean): Promise<void>;
+    usageReversed(original: UsageRecord, reversalRecordId: string, reason: string): Promise<void>;
+    audit(action: string, details: Record<string, unknown>): Promise<void>;
+}
+/** The resolved-options subset the metering facade consumes. */
+type MeteringServiceOptions = Pick<ResolvedAiTokensOptions, 'ratingMode'> & {
+    /** Absent in record-only setups that never place a hold. */
+    holds?: ResolvedAiTokensOptions['holds'];
+    /** Absent when the wallet feature is disabled. */
+    wallets?: ResolvedAiTokensOptions['wallets'];
+};
+/**
+ * The public metering facade — `record()`, `estimateCost()`, `hold()`,
+ * `capture()`, `release()`, and the `meter()` wrapper. Wires the pricing,
+ * ledger, wallet, and budget services together with the markup and event
+ * layers. See file overview for the full lifecycle description.
+ */
+declare class MeteringService {
+    private readonly ledger;
+    private readonly pricing;
+    private readonly markup;
+    private readonly options;
+    private readonly events;
+    private readonly now;
+    private readonly telemetry;
+    private readonly content;
+    private readonly logger;
+    private readonly effects;
+    /** The wallet service, or `undefined` when the wallet feature is disabled. */
+    private readonly wallets;
+    /** The budget service, or `undefined` when the budget feature is disabled. */
+    private readonly budgets;
+    /** The wallet overdraft headroom (0 when wallets are disabled). */
+    private readonly overdraftNanoUsd;
+    /**
+     * @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: LedgerService, pricing: PricingService, markup: MarkupResolver, options: MeteringServiceOptions, events?: MeteringEventHooks, wallets?: WalletService | null, budgets?: BudgetService | null, now?: () => Date, telemetry?: TelemetryEmitter, content?: ContentCapture);
+    /**
+     * 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.
+     */
+    record(input: RecordInput): Promise<UsageRecord>;
+    /**
+     * Pure pre-flight cost estimate — no ledger or event side effects.
+     *
+     * @param input The hypothetical call.
+     * @returns The raw and billed nano-USD estimate.
+     */
+    estimateCost(input: EstimateCostInput): Promise<CostEstimate>;
+    /**
+     * 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).
+     */
+    hold(context: MeteringContext, estimate: HoldEstimate): Promise<Hold>;
+    /**
+     * 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).
+     */
+    capture(hold: Hold, usage: unknown, preset?: ProviderPreset, content?: {
+        prompt?: string;
+        completion?: string;
+    }): Promise<UsageRecord>;
+    /**
+     * 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.
+     */
+    release(hold: Hold, reason: string): Promise<void>;
+    /**
+     * 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.
+     */
+    meter<T>(fn: () => Promise<T>, context: MeteringContext, extract: (result: T) => unknown, estimate?: HoldEstimate): Promise<MeterResult<T>>;
+    /**
+     * 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`.
+     */
+    reverse(usageRecordId: string, reason: string): Promise<UsageRecord>;
+    /**
+     * 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.
+     */
+    getStatus(tenantId: string, scope: MeteringScope): Promise<AccessStatus>;
+    /**
+     * 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).
+     */
+    restoreReleasedHold(record: UsageRecord, reason: string, expired: boolean): Promise<void>;
+    /** Reserve the pending ledger row, compensating the reservation if the insert fails. */
+    private appendPending;
+    /** Forward host-supplied prompt/completion text to the opt-in content sidecar (§14.2). */
+    private captureContent;
+    /** Build the {@link Hold} view of a pending (or replayed) ledger record. */
+    private holdOf;
+    /** Load a hold's record and reject a cross-tenant/scope or missing hold as HOLD_NOT_FOUND (§14.4). */
+    private loadHoldRecord;
+    /** Dispatch a non-pending hold record: posted → idempotent return; released → expired/settled. */
+    private settledOrConflict;
+    /** Reload a record by id, or fail HOLD_NOT_FOUND when it vanished mid-capture. */
+    private reload;
+    /**
+     * 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).
+     */
+    private finalizeCaptureUsage;
+    /** Build the settlement patch for a `pending → posted` transition. */
+    private settlementPatch;
+    /** Build the wallet section of an {@link AccessStatus}, or `undefined` when wallets are off / scope is a key. */
+    private walletSection;
+    /** Resolve the normalizer chain and produce the normalized usage. */
+    private resolveNormalizedUsage;
+    /** Resolve markup for a settled/pending call from the normalized identity. */
+    private resolveMarkup;
+    /** Run a normalizer, wrapping a plain failure as a malformed-usage error. */
+    private normalize;
+    /** Rate a call in the resolved mode; a non-strict rate miss yields zero cost + `priceMissing`. */
+    private rate;
+}
+
+/**
+ * @fileoverview `UsageReportService` — real aggregation over the typed ledger
+ * (spec §13). `summarize()` groups `SUM`s across the twelve report dimensions
+ * (delegating to the store's optional SQL `summarize`, else a documented
+ * in-memory fallback capped at `reporting.maxExportRows`) and computes the
+ * cache-savings figure per group from each record's effective price. `export()`
+ * streams the full §13.2 field set as CSV or line-delimited JSON with every bigint
+ * rendered as a decimal string (§15.5) and, for a non-USD presentation currency,
+ * additional `fx`-converted columns (§7.4, presentation-only). Every export emits
+ * an `ai_tokens.audit` event — it is an ADMIN-PLANE surface the host MUST restrict
+ * to privileged roles (§14.4). No prompt/completion text is ever read or emitted.
+ * @layer server
+ */
+
+/** The resolved-options subset the report service consumes. */
+interface UsageReportOptions {
+    currency: string;
+    fx?: ((date: Date, currency: string) => Promise<bigint> | bigint) | undefined;
+    reporting: {
+        maxExportRows: number;
+    };
+}
+/** The `summarize()` input: a report filter plus the group-by dimensions. */
+type SummarizeInput = ReportFilter & {
+    groupBy: ReportGroupBy[];
+};
+/** The export serialization format. */
+type ReportExportFormat = 'csv' | 'json';
+/** The audit hook the module wires to the event dispatcher (default no-op). */
+type ReportAuditHook = (action: string, details: Record<string, unknown>) => void;
+/**
+ * Read-side reporting: per-scope cost summaries with currency conversion, CSV
+ * and JSON export, paginated history, and per-model analytics. All money is
+ * presented in nano-USD internally; `formatNanoUsd` handles display. See file overview.
+ */
+declare class UsageReportService {
+    private readonly store;
+    private readonly pricing;
+    private readonly options;
+    private readonly audit;
+    /**
+     * @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: ILedgerStore, pricing: IPricingStore, options: UsageReportOptions, audit?: ReportAuditHook);
+    /**
+     * 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`.
+     */
+    summarize(input: SummarizeInput): Promise<UsageSummary[]>;
+    /**
+     * 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`.
+     */
+    export(filter: ReportFilter, format: ReportExportFormat): Promise<Readable>;
+    /**
+     * 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.
+     */
+    private assertWithinMaxRows;
+    /** Yield the serialized rows (CSV header + rows, or ndjson lines). */
+    private serialize;
+    /** The ordered header names for the export (with fx columns when converting). */
+    private headers;
+    /** Build one export row as ordered `[header, cell]` pairs (all cells strings). */
+    private rowOf;
+    /** The nano-USD cache savings for a record: `cacheReadTokens × (inputRate − cacheReadRate)`. */
+    private cacheSavings;
+}
+
+/**
+ * @fileoverview `toJsonSafe` — the bigint-at-the-JSON-boundary helper (spec §15.5).
+ * `bigint` does not survive `JSON.stringify`, so any library value returned from a
+ * controller or shipped through an out-of-process `IEventSink` is first deep-cloned
+ * with every `bigint` rendered as an exact decimal string (e.g. `5000000n` →
+ * `"5000000"`). Token counts stay plain `number`; `Date` values are cloned and
+ * serialize to ISO strings via the standard JSON rules. In-process delivery keeps
+ * `bigint` intact — this helper is only for the JSON boundary.
+ * @layer server
+ */
+/** The result of {@link toJsonSafe}: every `bigint` replaced by a decimal string. */
+type JsonSafe<T> = T extends bigint ? string : T extends Date ? Date : T extends readonly (infer U)[] ? JsonSafe<U>[] : T extends object ? {
+    [K in keyof T]: JsonSafe<T[K]>;
+} : T;
+/**
+ * Deep-clone a value into a JSON-safe form, serializing every `bigint` as a
+ * decimal string so the result survives `JSON.stringify` losslessly.
+ *
+ * @param value The value to make JSON-safe (e.g. a `UsageRecord` or event envelope).
+ * @returns A structural clone with `bigint` fields rendered as decimal strings.
+ * @example
+ * toJsonSafe({ billedCostNanoUsd: 5_000_000n }) // { billedCostNanoUsd: '5000000' }
+ */
+declare function toJsonSafe<T>(value: T): JsonSafe<T>;
+
+/**
+ * @fileoverview `StreamUsageCollector` — abort-safe usage capture for streamed
+ * responses (spec §5.6). Provider `usage` arrives only in the final chunk (OpenAI:
+ * a trailing chunk with `usage` and empty `choices`; Anthropic: cumulative in
+ * `message_delta`, finalized at `message_stop`), and an aborted stream reports
+ * all-zero usage even though tokens were consumed. The collector accumulates the
+ * output text as chunks flow and, at `finalize()`, prefers the provider-final usage;
+ * on an abort it falls back to a tokenizer count of the accumulated output so the
+ * call is still billed for what it produced. `push()` NEVER throws — a malformed
+ * chunk is skipped and counted. Only token counts and (optionally) the prompt cross
+ * this boundary; prompt/response text stays here for counting and is never persisted.
+ * @layer server
+ */
+
+/** Construction options for {@link StreamUsageCollector}. */
+interface StreamUsageCollectorOptions {
+    provider: ProviderId;
+    model: string;
+    /** The rated operation; defaults to `'chat'`. */
+    operation?: AiOperation;
+    /** How to parse the provider-final usage chunk; defaults to the provider's built-in normalizer. */
+    preset?: ProviderPreset;
+    /** Fallback token counter for aborted streams; defaults to the module tokenizer. */
+    tokenizer?: ITokenizer;
+    /** Custom output-text extractor for providers beyond the OpenAI/Anthropic built-ins. */
+    outputText?: (chunk: Record<string, unknown>) => string | undefined;
+}
+/**
+ * Accumulates usage chunks from a streamed provider response and finalises
+ * into a {@link NormalizedUsage} object. Prefer the provider's own final
+ * usage block; fall back to tokenizer-estimated output tokens when the
+ * stream is aborted before the final chunk arrives.
+ *
+ * @example
+ * const collector = new StreamUsageCollector({ provider: 'openai-chat', model: 'gpt-4o' })
+ * // call collector.push(chunk) for each SSE chunk
+ * const usage = await collector.finalize()
+ */
+declare class StreamUsageCollector {
+    private readonly opts;
+    private readonly operation;
+    private outputText;
+    /** The provider-final response object to normalize, once seen. */
+    private finalResponse;
+    /** Anthropic streaming state accumulated across events (seeded from the constructed identity). */
+    private anthropicModel;
+    private anthropicBaseUsage;
+    private anthropicOutputTokens;
+    private promptTokens;
+    private promptText;
+    private finalized;
+    private malformed;
+    /** True after `finalize()` when the tokenizer fallback (not provider-final usage) was used. */
+    usedFallback: boolean;
+    /** @param opts The provider/model + optional preset/tokenizer/extractor. */
+    constructor(opts: StreamUsageCollectorOptions);
+    /** How many chunks were skipped as malformed (debug/observability). */
+    get malformedCount(): number;
+    /** Provide the prompt text so an aborted stream can count input tokens via the tokenizer. */
+    setPromptText(text: string): void;
+    /** Provide a pre-counted prompt token total (takes precedence over `setPromptText`). */
+    setPromptTokens(count: number): void;
+    /**
+     * 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: unknown): void;
+    /**
+     * 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.
+     */
+    finalize(): Promise<NormalizedUsage>;
+    /** Accumulate an OpenAI-shaped chunk and capture its trailing usage. */
+    private pushOpenAiLike;
+    /** Accumulate an Anthropic-shaped event and reconstruct its final usage at message_stop. */
+    private pushAnthropic;
+    /** Normalize a captured provider-final response via the preset or the provider default. */
+    private normalizeFinal;
+    /** Build the tokenizer-counted fallback usage for an aborted stream. */
+    private fallbackUsage;
+}
+
+/**
+ * @fileoverview The provider presets (spec §4.3). Each preset pairs a normalizer
+ * with the right provider id and rating mode; a preset is passed in
+ * `MeteringContext.preset`. `azureOpenai` reuses the OpenAI Chat normalizer but
+ * requires the caller to pass `baseModel` (§6.6); `vercelAiSdk` defaults its
+ * provider to `'openai'` and expects a per-call override; `openrouter` rates in
+ * `'provider-reported'` mode.
+ * @layer server
+ */
+
+/** The built-in provider presets, plus the `openaiCompatible(id)` factory. */
+declare const providerPresets: {
+    openaiChat: ProviderPreset;
+    openaiResponses: ProviderPreset;
+    azureOpenai: ProviderPreset;
+    anthropic: ProviderPreset;
+    gemini: ProviderPreset;
+    vertex: ProviderPreset;
+    bedrock: ProviderPreset;
+    mistral: ProviderPreset;
+    vercelAiSdk: ProviderPreset;
+    openrouter: ProviderPreset;
+    /** A custom OpenAI-compatible provider (DeepSeek, xAI, Groq, …). */
+    openaiCompatible: (id: string) => ProviderPreset;
+};
+
+/**
+ * @fileoverview `BudgetGuard` — the CanActivate enforcement gate (spec §11.3). It
+ * resolves the caller's metering context via the host-configured `scopeResolver`
+ * (TRUSTED INPUT — the host's VERIFIED auth context only, never client body/query,
+ * §14.4), merges the decorator config (feature precedence `@RequireBudget` >
+ * `@Meter` > `@AiFeature`), and checks budget status. If any matching HARD (`block`)
+ * budget is exhausted it throws `AI_TOKENS_BUDGET_EXCEEDED` (402, spend) or
+ * `AI_TOKENS_QUOTA_EXCEEDED` (429, tokens/count) BEFORE the handler runs; otherwise
+ * it enriches the request with `request.aiTokens = { status, context }` and returns
+ * true. This is CHECK-ONLY — it performs NO consumption; the §10.8 atomic consume
+ * still protects the actual charge at record/capture time (the documented gate
+ * race). A missing `scopeResolver` fails fast at guard construction. When
+ * `@RequireBudget.estimate` is present the guard additionally places a hold and
+ * attaches it to `request.aiTokens.hold` so the `MeteringInterceptor` settles it
+ * with the handler's actual usage (spec §11.3).
+ * @layer server
+ */
+
+/** The request enrichment the guard attaches (the `AIGenerationGuard` parity contract). */
+interface RequestAiTokens {
+    status: BudgetStatus[];
+    context: MeteringContext;
+    /** Present when `@RequireBudget.estimate` placed a hold; the interceptor settles it. */
+    hold?: Hold;
+}
+/**
+ * NestJS guard that checks budget status before each request and enriches
+ * `request.aiTokens` with the scope's current usage. Optionally places a
+ * spend hold when `@RequireBudget.estimate` is configured (see file overview).
+ */
+declare class BudgetGuard implements CanActivate {
+    private readonly budgets;
+    private readonly metering;
+    private readonly reflector;
+    private readonly scopeResolver;
+    /**
+     * @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: BudgetService, metering: MeteringService, reflector: Reflector, options: Pick<ResolvedAiTokensOptions, '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).
+     */
+    canActivate(executionContext: ExecutionContext): Promise<boolean>;
+}
+
+/**
+ * @fileoverview `MeteringInterceptor` — the declarative capture half of the
+ * controller path (spec §11.3/§11.4). After the handler resolves it extracts the
+ * raw usage from the return value (via `@Meter.extract`, default `result.usage`),
+ * then either settles the guard's hold (`capture`) or records enforcing post-hoc
+ * (`record({ enforce: true })`). On a handler error with a hold present it releases
+ * the hold and rethrows the ORIGINAL error — never swallowing it. With
+ * `exposeHeaders` it sets the three `x-ai-tokens-*` response headers as DECIMAL
+ * STRINGS (bigint never crosses the HTTP boundary raw, §15.5). Handlers without a
+ * `@Meter` are passed through untouched. `scopeResolver` is TRUSTED INPUT — the
+ * host's verified auth context, never client body/query (§14.4).
+ * @layer server
+ */
+
+/** The resolved-options subset the interceptor consumes. */
+type MeteringInterceptorOptions = Pick<ResolvedAiTokensOptions, 'scopeResolver'>;
+/**
+ * NestJS interceptor that captures the handler's actual usage (from the return
+ * value) and either settles the guard's hold or records a post-hoc enforcing
+ * charge. Reads `@Meter` metadata set by the {@link Meter} decorator.
+ */
+declare class MeteringInterceptor implements NestInterceptor {
+    private readonly reflector;
+    private readonly metering;
+    private readonly logger;
+    private readonly scopeResolver;
+    /**
+     * @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: Reflector, metering: MeteringService, options: MeteringInterceptorOptions);
+    /**
+     * 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: ExecutionContext, next: CallHandler): Observable<unknown>;
+    /** Settle the handler's usage and set the cost headers; returns the untouched result. */
+    private settle;
+    /** Capture the guard's hold when present, else record enforcing post-hoc. */
+    private capture;
+    /** The metering context: the guard's enrichment, else the host `scopeResolver`. */
+    private resolveContext;
+    /** Release the guard's hold (if any) and rethrow the ORIGINAL handler error. */
+    private onError;
+    /** Set the three `x-ai-tokens-*` headers as decimal strings via the HTTP adapter. */
+    private setHeaders;
+}
+
+/**
+ * @fileoverview The controller-level metering/enforcement decorators (spec §11.4).
+ * `@Meter` marks a handler for the `MeteringInterceptor` and is metadata-only
+ * here; `@RequireBudget` marks it for the `BudgetGuard`; `@AiFeature`
+ * is a lightweight feature tag. Each stores its config under an exported symbol key
+ * that the guard/interceptor read via the NestJS `Reflector`. Feature precedence is
+ * `@RequireBudget.feature` > `@Meter.feature` > `@AiFeature` (§11.4). These are pure
+ * metadata; they never touch a wallet, budget, or the request.
+ * @layer server
+ */
+
+/** Reflector key for {@link Meter} metadata. */
+declare const METER_METADATA = "bymax:ai-tokens:meter";
+/** Reflector key for {@link RequireBudget} metadata. */
+declare const REQUIRE_BUDGET_METADATA = "bymax:ai-tokens:require-budget";
+/** Reflector key for {@link AiFeature} metadata. */
+declare const AI_FEATURE_METADATA = "bymax:ai-tokens:ai-feature";
+/** `@Meter` configuration — consumed by the `MeteringInterceptor`. */
+interface MeterConfig {
+    /** The logical operation, e.g. `'workout.generate'`. */
+    feature: string;
+    /** Which scope type from the resolved context to charge (default `'user'`). */
+    scope?: ScopeType;
+    /** The normalizer + rating mode for the handler's return value. */
+    preset?: ProviderPreset;
+    /** Pull the raw usage out of the return value (default: `result.usage`). */
+    extract?: (result: unknown) => unknown;
+    /** Set `x-ai-tokens-*` response headers. */
+    exposeHeaders?: boolean;
+    /** Platform-absorbed cost — never consumes wallet/budget. */
+    isSystemCost?: boolean;
+    /** Cost-attribution labels. */
+    tags?: string[];
+}
+/** `@RequireBudget` configuration — consumed by the `BudgetGuard`. */
+interface RequireBudgetConfig {
+    /** Which scope type to enforce (default: the resolved context's scope). */
+    scope?: ScopeType;
+    /** Budget feature-filter matching; defaults to `@Meter`'s feature. */
+    feature?: string;
+    /** A static estimate → the guard places a hold the interceptor settles. */
+    estimate?: HoldEstimate;
+}
+/**
+ * Mark a handler for metering by the `MeteringInterceptor`. Metadata-only.
+ *
+ * @param config The metering configuration.
+ * @returns The metadata decorator.
+ */
+declare function Meter(config: MeterConfig): CustomDecorator;
+/**
+ * Require budget headroom on a handler — the {@link BudgetGuard} blocks the request
+ * pre-handler when a matching hard budget is exhausted.
+ *
+ * @param config The budget-enforcement configuration.
+ * @returns The metadata decorator.
+ */
+declare function RequireBudget(config?: RequireBudgetConfig): CustomDecorator;
+/**
+ * Tag a handler with a feature name (`@Meter.feature` wins when both are present).
+ *
+ * @param name The feature name.
+ * @returns The metadata decorator.
+ */
+declare function AiFeature(name: string): CustomDecorator;
+
+/**
+ * @fileoverview The typed exception the library throws. Extends NestJS
+ * `HttpException` so hosts get a stable `{ error: { code, message, details? } }`
+ * body and the right HTTP status by default (spec §16.1). The public surface is
+ * this class plus `AI_TOKENS_ERROR_CODES` and `AiTokensErrorResponse` (both from
+ * `./shared`); the message/status maps are internal.
+ * @layer server
+ */
+
+/**
+ * A typed library error. The status defaults to the code's mapped HTTP status
+ * (spec §16.2) and the body is the canonical `AiTokensErrorResponse` shape.
+ *
+ * @example
+ * throw new AiTokensException('AI_TOKENS_BUDGET_EXCEEDED', undefined, { budgetId })
+ */
+declare class AiTokensException 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: AiTokensErrorCode, statusCode?: HttpStatus, details?: Record<string, unknown>);
+}
+
+export { AI_FEATURE_METADATA, AI_OPERATIONS, AI_TOKENS_ERROR_CODES, AMOUNT_FIELDS, type AccessStatus, type AdjustInput, AiFeature, type AiOperation, type AiTokensErrorCode, type AiTokensErrorResponse, type AiTokensEvent, type AiTokensEventType, AiTokensException, type AuditEventData, BYMAX_AI_TOKENS_BUDGET_COUNTER, BYMAX_AI_TOKENS_BUDGET_STORE, BYMAX_AI_TOKENS_CONTENT_STORE, BYMAX_AI_TOKENS_EVENT_SINK, BYMAX_AI_TOKENS_LEDGER_STORE, BYMAX_AI_TOKENS_LOGGER, BYMAX_AI_TOKENS_OPTIONS, BYMAX_AI_TOKENS_PRICING_STORE, BYMAX_AI_TOKENS_TELEMETRY, BYMAX_AI_TOKENS_TOKENIZER, BYMAX_AI_TOKENS_WALLET_STORE, type Budget, type BudgetDelta, type BudgetDimensionSnapshot, type BudgetExceededEventData, BudgetGuard, type BudgetLimits, type BudgetPolicy, type BudgetProjectedExceededEventData, BudgetService, type BudgetServiceOptions, type BudgetStatus, type BudgetThresholdCrossedEventData, type BudgetWindowKind, type BudgetWindowSpend, BymaxAiTokensModule, type BymaxAiTokensModuleAsyncOptions, type BymaxAiTokensModuleOptions, type BymaxAiTokensModuleOptionsFactory, type CostBreakdown, type CostEstimate, type DebitInput, type EstimateCostInput, type FormatNanoUsdOptions, type GrantInput, type Hold, type HoldEstimate, type HoldReleasedEventData, type IAiTokensStore, type IBudgetCounterStore, type IBudgetStore, type IContentStore, type IEventSink, type ILedgerStore, type IMarkupPolicy, type IPricingStore, type ITelemetrySink, type ITokenizer, type IWalletStore, type JsonSafe, type KnownProviderId, type LedgerAppendInput, type LedgerCostSummary, type LedgerFilter, LedgerService, METER_METADATA, Meter, type MeterConfig, type MeterResult, type MeteringContext, MeteringInterceptor, type MeteringScope, MeteringService, type NewPriceVersion, type NewUsageRecord, type NewWalletEntry, type NormalizedUsage, type OpenGrant, PROVIDER_IDS, type PriceMissingEventData, type PriceVersion, type PricedModel, PricingService, type ProviderId, type ProviderPreset, RELEASE_FIELDS, REQUIRE_BUDGET_METADATA, REVERSAL_LINKAGE_FIELD, type RatingMode, type RecordInput, type RefundInput, type ReportExportFormat, type ReportFilter, type ReportGroupBy, type RequestAiTokens, RequireBudget, type RequireBudgetConfig, type ResolveRateInput, SERVICE_TIERS, SETTLEMENT_FIELDS, SETTLEMENT_PATCH_KEYS, type ScopeType, type ServiceTier, StreamUsageCollector, type StreamUsageCollectorOptions, type SummarizeInput, TOKEN_CATEGORIES, type TokenCategory, type UpsertBudgetInput, type UsageNormalizer, type UsageRecord, type UsageRecordedEventData, type UsageReportOptions, UsageReportService, type UsageReversedEventData, type UsageStatus, type UsageSummary, WALLET_ENTRY_TYPES, type Wallet, type WalletBalance, type WalletDepletedEventData, type WalletEntry, type WalletEntryFilter, type WalletEntryPage, type WalletEntryType, type WalletGrantedEventData, type WalletLowBalanceEventData, type WalletRef, WalletService, type WalletServiceOptions, applyMarkup, computeCostNanoUsd, deriveIdempotencyKey, floatUsdToNanoUsd, formatNanoUsd, isLegalLedgerTransition, isLegalTransitionPatchKey, normalizeAnthropicUsage, normalizeBedrockConverseUsage, normalizeGeminiUsage, normalizeMistralUsage, normalizeOpenAiChatUsage, normalizeOpenAiCompatibleUsage, normalizeOpenAiResponsesUsage, normalizeOpenRouterUsage, normalizeVercelAiSdkUsage, perMillion, providerPresets, resolveMultiplier4dp, toJsonSafe };