@bymax-one/nest-ai-tokens 1.0.0

package/dist/prisma/index.d.ts

@@ -0,0 +1,677 @@
+import { PrismaClient } from '@prisma/client';
+
+/**
+ * @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 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 & {});
+/** 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;
+}
+
+/**
+ * @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 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 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;
+}
+
+/**
+ * @fileoverview Reporting types: the query filter and the aggregated usage
+ * summary (including the cache-savings figure) produced by `UsageReportService`.
+ * @layer shared
+ */
+
+/** 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 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 `PrismaAiTokensStore` — the official PostgreSQL adapter (spec
+ * §15.1–15.3). It implements the ledger + pricing halves of `IAiTokensStore`
+ * against any `@prisma/client` instance, talking to PostgreSQL EXCLUSIVELY through
+ * PARAMETERIZED raw SQL (`$queryRaw`/`$executeRaw`/`$transaction`) so it never
+ * depends on generated model delegates and stays valid against the host's schema.
+ * Column identifiers are hardcoded constants (never interpolated from input) and
+ * every value is a bound parameter, so the raw SQL is injection-safe. Money is
+ * `BIGINT` nano-USD; `unitRates` round-trip as JSON of decimal strings; the
+ * `markupMultiplier` `Decimal(10,4)` maps to a `number` at the boundary (exact by
+ * the 4-dp rule, §7.2). Store errors map to the domain catalog (§15.2); a payload
+ * hash mismatch on the `(tenantId, idempotencyKey)` unique index becomes the
+ * exactly-once conflict, and unknown driver errors become `AI_TOKENS_STORE_ERROR`
+ * (connection details are never leaked). Row shapes, mappers, and SQL builders live
+ * in `./adapter-sql`; the wallet/budget halves use the same conditional-write
+ * discipline as the ledger half (§9.4, §10.8).
+ * @layer prisma
+ */
+
+/**
+ * The official PostgreSQL adapter. Construct it with the host's `PrismaClient`
+ * (the host's schema must include the shipped models, §15.3).
+ */
+declare class PrismaAiTokensStore implements IAiTokensStore {
+    private readonly prisma;
+    private readonly burnOrder;
+    /**
+     * @param prisma The host's Prisma client (talks to PostgreSQL).
+     * @param options Optional wallet grant burn order (must match the module's `wallets.burnOrder`; default `'expiry'`).
+     */
+    constructor(prisma: PrismaClient, options?: {
+        burnOrder?: 'expiry' | 'priority' | 'fifo';
+    });
+    append(record: NewUsageRecord, payloadHash: string, hashChain?: boolean): Promise<UsageRecord>;
+    transition(id: string, from: UsageStatus, to: UsageStatus, patch?: Partial<UsageRecord>, hashChain?: boolean): Promise<UsageRecord | null>;
+    findByIdempotencyKey(tenantId: string, key: string): Promise<UsageRecord | null>;
+    findById(id: string): Promise<UsageRecord | null>;
+    findExpiredHolds(olderThan: Date, limit: number): Promise<UsageRecord[]>;
+    query(filter: LedgerFilter): Promise<UsageRecord[]>;
+    sumCost(filter: LedgerFilter): Promise<LedgerCostSummary>;
+    lastHash(tenantId: string): Promise<string | null>;
+    resolveRate(provider: ProviderId, model: string, operation: AiOperation, serviceTier: ServiceTier, at: Date): Promise<PriceVersion | null>;
+    upsertPrice(input: NewPriceVersion): Promise<PriceVersion>;
+    getPriceHistory(provider: ProviderId, model: string, operation: AiOperation, serviceTier?: ServiceTier): Promise<PriceVersion[]>;
+    listModels(provider: ProviderId): Promise<PricedModel[]>;
+    /** Advisory seed lock (§6.4): the first caller wins; concurrent boots seed exactly once. */
+    acquireSeedLock(key: string): Promise<boolean>;
+    /** Insert one usage row and return it; shared by the plain and chained paths. */
+    private insert;
+    /** Insert a `posted` row under the per-tenant chain lock (§8.6). */
+    private insertChained;
+    /** Settle a hold `pending → posted`, computing its chain hash under the lock (§8.6). */
+    private settleChained;
+    /** Atomic status transition via a conditional `UPDATE`; 0 rows → `null` (§8.3). */
+    private updateStatus;
+    /** The tenant's last chain hash (most recently created settled row). */
+    private lastHashWithin;
+    getWallet(ref: WalletRef): Promise<Wallet | null>;
+    appendEntry(ref: WalletRef, entry: NewWalletEntry, allocations?: {
+        grantEntryId: string;
+        amountNanoUsd: bigint;
+    }[]): Promise<WalletEntry>;
+    conditionalDebit(ref: WalletRef, entry: NewWalletEntry, overdraftNanoUsd: bigint): Promise<WalletEntry | null>;
+    openGrants(ref: WalletRef, order: 'expiry' | 'priority' | 'fifo'): Promise<OpenGrant[]>;
+    listEntries(ref: WalletRef, filter?: WalletEntryFilter): Promise<WalletEntryPage>;
+    reconcile(ref: WalletRef): Promise<Wallet>;
+    upsert(input: Omit<Budget, 'id' | 'createdAt'> & {
+        id?: string;
+    }): Promise<Budget>;
+    remove(budgetId: string): Promise<void>;
+    findBudgetById(budgetId: string): Promise<Budget | null>;
+    findMatching(tenantId: string, scope: MeteringScope): Promise<Budget[]>;
+    conditionalConsume(budgetId: string, windowStart: Date, delta: BudgetDelta, limits: BudgetLimits): Promise<boolean>;
+    adjustWindow(budgetId: string, windowStart: Date, delta: BudgetDelta): Promise<void>;
+    getWindow(budgetId: string, windowStart: Date): Promise<BudgetWindowSpend | null>;
+    setWindowStart(budgetId: string, windowStart: Date): Promise<void>;
+    /** Load the wallet within a transaction (existence + id for the conditional debit). */
+    private getWalletWithin;
+    /** Fetch or (optionally) create the wallet for a ref within a transaction. */
+    private ensureWallet;
+    /** Insert a wallet entry, returning the stored row. */
+    private insertWalletEntry;
+    /** Insert the debit→grant allocation trail. */
+    private insertAllocations;
+    /** Apply a signed delta to the materialized balance. */
+    private applyBalanceDelta;
+    /** Write an `expiry` entry (with its allocation) for each expired grant with a remainder. */
+    private sweepExpiredGrants;
+    /** Greedily allocate a debit of `cost` across the open grants in burn order. */
+    private burnDown;
+    /** The open-grants query (remaining > 0, effective, not expired) ordered per burn order. */
+    private openGrantsSql;
+    /** Return the existing entry on a matching replay, throw the conflict, or `undefined` when new. */
+    private walletReplay;
+    /** Ensure a (zeroed) window row exists for first-touch consumption. */
+    private ensureWindow;
+    /** Map the P2002 replay-or-conflict path for a wallet entry (§15.2). */
+    private replayOrConflictWallet;
+    /** Return the existing record on a matching payload replay, else raise the conflict (§15.2). */
+    private replayOrConflict;
+}
+
+export { PrismaAiTokensStore };