@bymax-one/nest-ai-tokens 1.0.0

package/dist/prisma/migrations/0001_init.sql

@@ -0,0 +1,198 @@
+-- @bymax-one/nest-ai-tokens — initial schema (spec §15.3).
+-- Seven tables; all money is BIGINT nano-USD; every table carries "tenantId".
+-- Apply with `prisma db execute --file` / `psql`, or let `prisma migrate` generate
+-- the equivalent from `schema.prisma.fragment`. The two PARTIAL indexes at the end
+-- cannot be expressed in the Prisma schema and are the reason for the shipped SQL.
+
+-- ---------------------------------------------------------------------------
+-- ai_usage_records — the immutable usage ledger (append-only).
+-- ---------------------------------------------------------------------------
+CREATE TABLE "ai_usage_records" (
+  "id"                 TEXT NOT NULL,
+  "tenantId"           TEXT NOT NULL,
+  "scopeType"          TEXT NOT NULL,
+  "scopeId"            TEXT NOT NULL,
+  "beneficiaryType"    TEXT,
+  "beneficiaryId"      TEXT,
+  "requestedBy"        TEXT,
+  "provider"           TEXT NOT NULL,
+  "model"              TEXT NOT NULL,
+  "requestedModel"     TEXT,
+  "operation"          TEXT NOT NULL,
+  "serviceTier"        TEXT NOT NULL DEFAULT 'standard',
+  "feature"            TEXT NOT NULL,
+  "tags"               TEXT[] NOT NULL DEFAULT ARRAY[]::TEXT[],
+  "inputTokens"        INTEGER NOT NULL DEFAULT 0,
+  "outputTokens"       INTEGER NOT NULL DEFAULT 0,
+  "cacheReadTokens"    INTEGER NOT NULL DEFAULT 0,
+  "cacheWrite5mTokens" INTEGER NOT NULL DEFAULT 0,
+  "cacheWrite1hTokens" INTEGER NOT NULL DEFAULT 0,
+  "reasoningTokens"    INTEGER NOT NULL DEFAULT 0,
+  "audioInTokens"      INTEGER NOT NULL DEFAULT 0,
+  "audioOutTokens"     INTEGER NOT NULL DEFAULT 0,
+  "imageInTokens"      INTEGER NOT NULL DEFAULT 0,
+  "imageOutTokens"     INTEGER NOT NULL DEFAULT 0,
+  "totalTokens"        INTEGER NOT NULL,
+  "extraUnits"         JSONB,
+  "priceVersionId"     TEXT,
+  "rawCostNanoUsd"     BIGINT NOT NULL,
+  "surchargeNanoUsd"   BIGINT NOT NULL DEFAULT 0,
+  "billedCostNanoUsd"  BIGINT NOT NULL,
+  "markupMultiplier"   DECIMAL(10,4) NOT NULL,
+  "currency"           TEXT NOT NULL DEFAULT 'USD',
+  "priceMissing"       BOOLEAN NOT NULL DEFAULT false,
+  "status"             TEXT NOT NULL DEFAULT 'posted',
+  "reversedByRecordId" TEXT,
+  "reversesRecordId"   TEXT,
+  "idempotencyKey"     TEXT NOT NULL,
+  "payloadHash"        TEXT NOT NULL,
+  "correlationId"      TEXT,
+  "requestId"          TEXT,
+  "isSystemCost"       BOOLEAN NOT NULL DEFAULT false,
+  "systemCostCategory" TEXT,
+  "enforced"           BOOLEAN NOT NULL DEFAULT false,
+  "prevHash"           TEXT,
+  "hash"               TEXT,
+  "occurredAt"         TIMESTAMP(3) NOT NULL,
+  "createdAt"          TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  "updatedAt"          TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  CONSTRAINT "ai_usage_records_pkey" PRIMARY KEY ("id")
+);
+CREATE UNIQUE INDEX "ai_usage_records_tenantId_idempotencyKey_key" ON "ai_usage_records" ("tenantId", "idempotencyKey");
+CREATE INDEX "ai_usage_records_tenantId_occurredAt_idx" ON "ai_usage_records" ("tenantId", "occurredAt");
+CREATE INDEX "ai_usage_records_tenantId_scopeType_scopeId_occurredAt_idx" ON "ai_usage_records" ("tenantId", "scopeType", "scopeId", "occurredAt");
+CREATE INDEX "ai_usage_records_tenantId_feature_occurredAt_idx" ON "ai_usage_records" ("tenantId", "feature", "occurredAt");
+CREATE INDEX "ai_usage_records_tenantId_provider_model_idx" ON "ai_usage_records" ("tenantId", "provider", "model");
+CREATE INDEX "ai_usage_records_tenantId_systemCostCategory_idx" ON "ai_usage_records" ("tenantId", "systemCostCategory");
+CREATE INDEX "ai_usage_records_tenantId_beneficiaryType_beneficiaryId_idx" ON "ai_usage_records" ("tenantId", "beneficiaryType", "beneficiaryId");
+CREATE INDEX "ai_usage_records_priceVersionId_idx" ON "ai_usage_records" ("priceVersionId");
+CREATE INDEX "ai_usage_records_status_createdAt_idx" ON "ai_usage_records" ("status", "createdAt");
+
+-- ---------------------------------------------------------------------------
+-- ai_model_prices — effective-dated price registry.
+-- ---------------------------------------------------------------------------
+CREATE TABLE "ai_model_prices" (
+  "id"                            TEXT NOT NULL,
+  "provider"                      TEXT NOT NULL,
+  "model"                         TEXT NOT NULL,
+  "operation"                     TEXT NOT NULL,
+  "serviceTier"                   TEXT NOT NULL DEFAULT 'standard',
+  "inputNanoUsdPerMillion"        BIGINT NOT NULL DEFAULT 0,
+  "outputNanoUsdPerMillion"       BIGINT NOT NULL DEFAULT 0,
+  "cacheReadNanoUsdPerMillion"    BIGINT NOT NULL DEFAULT 0,
+  "cacheWrite5mNanoUsdPerMillion" BIGINT NOT NULL DEFAULT 0,
+  "cacheWrite1hNanoUsdPerMillion" BIGINT NOT NULL DEFAULT 0,
+  "reasoningNanoUsdPerMillion"    BIGINT NOT NULL DEFAULT 0,
+  "audioInNanoUsdPerMillion"      BIGINT NOT NULL DEFAULT 0,
+  "audioOutNanoUsdPerMillion"     BIGINT NOT NULL DEFAULT 0,
+  "imageInNanoUsdPerMillion"      BIGINT NOT NULL DEFAULT 0,
+  "imageOutNanoUsdPerMillion"     BIGINT NOT NULL DEFAULT 0,
+  "tierThresholdTokens"           INTEGER,
+  "tierInputNanoUsdPerMillion"    BIGINT,
+  "tierOutputNanoUsdPerMillion"   BIGINT,
+  "unitRates"                     JSONB,
+  "currency"                      TEXT NOT NULL DEFAULT 'USD',
+  "effectiveFrom"                 TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  "effectiveTo"                   TIMESTAMP(3),
+  "source"                        TEXT NOT NULL DEFAULT 'snapshot',
+  CONSTRAINT "ai_model_prices_pkey" PRIMARY KEY ("id")
+);
+CREATE INDEX "ai_model_prices_provider_model_operation_serviceTier_effecti_idx" ON "ai_model_prices" ("provider", "model", "operation", "serviceTier", "effectiveFrom");
+
+-- ---------------------------------------------------------------------------
+-- ai_wallets + ai_wallet_entries + ai_wallet_debit_allocations (wallet feature).
+-- ---------------------------------------------------------------------------
+CREATE TABLE "ai_wallets" (
+  "id"             TEXT NOT NULL,
+  "tenantId"       TEXT NOT NULL,
+  "ownerType"      TEXT NOT NULL,
+  "ownerId"        TEXT NOT NULL,
+  "balanceNanoUsd" BIGINT NOT NULL DEFAULT 0,
+  "createdAt"      TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  "updatedAt"      TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  CONSTRAINT "ai_wallets_pkey" PRIMARY KEY ("id")
+);
+CREATE UNIQUE INDEX "ai_wallets_tenantId_ownerType_ownerId_key" ON "ai_wallets" ("tenantId", "ownerType", "ownerId");
+
+CREATE TABLE "ai_wallet_entries" (
+  "id"             TEXT NOT NULL,
+  "walletId"       TEXT NOT NULL,
+  "type"           TEXT NOT NULL,
+  "amountNanoUsd"  BIGINT NOT NULL,
+  "priority"       INTEGER NOT NULL DEFAULT 0,
+  "effectiveAt"    TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  "expiresAt"      TIMESTAMP(3),
+  "usageRecordId"  TEXT,
+  "idempotencyKey" TEXT NOT NULL,
+  "reason"         TEXT,
+  "createdAt"      TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  CONSTRAINT "ai_wallet_entries_pkey" PRIMARY KEY ("id")
+);
+CREATE UNIQUE INDEX "ai_wallet_entries_walletId_idempotencyKey_key" ON "ai_wallet_entries" ("walletId", "idempotencyKey");
+CREATE INDEX "ai_wallet_entries_walletId_effectiveAt_idx" ON "ai_wallet_entries" ("walletId", "effectiveAt");
+CREATE INDEX "ai_wallet_entries_walletId_type_expiresAt_idx" ON "ai_wallet_entries" ("walletId", "type", "expiresAt");
+
+CREATE TABLE "ai_wallet_debit_allocations" (
+  "id"            TEXT NOT NULL,
+  "debitEntryId"  TEXT NOT NULL,
+  "grantEntryId"  TEXT NOT NULL,
+  "amountNanoUsd" BIGINT NOT NULL,
+  CONSTRAINT "ai_wallet_debit_allocations_pkey" PRIMARY KEY ("id")
+);
+CREATE INDEX "ai_wallet_debit_allocations_grantEntryId_idx" ON "ai_wallet_debit_allocations" ("grantEntryId");
+CREATE INDEX "ai_wallet_debit_allocations_debitEntryId_idx" ON "ai_wallet_debit_allocations" ("debitEntryId");
+
+-- ---------------------------------------------------------------------------
+-- ai_budgets + ai_budget_windows (budget feature).
+-- ---------------------------------------------------------------------------
+CREATE TABLE "ai_budgets" (
+  "id"             TEXT NOT NULL,
+  "tenantId"       TEXT NOT NULL,
+  "scopeType"      TEXT NOT NULL,
+  "scopeId"        TEXT NOT NULL,
+  "features"       TEXT[] NOT NULL DEFAULT ARRAY[]::TEXT[],
+  "limitNanoUsd"   BIGINT,
+  "limitTokens"    BIGINT,
+  "limitCount"     INTEGER,
+  "window"         TEXT NOT NULL,
+  "anchorAt"       TIMESTAMP(3),
+  "expiresAt"      TIMESTAMP(3),
+  "softThresholds" JSONB NOT NULL,
+  "policy"         TEXT NOT NULL DEFAULT 'block',
+  "createdAt"      TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  "updatedAt"      TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  CONSTRAINT "ai_budgets_pkey" PRIMARY KEY ("id")
+);
+CREATE INDEX "ai_budgets_tenantId_scopeType_scopeId_idx" ON "ai_budgets" ("tenantId", "scopeType", "scopeId");
+
+CREATE TABLE "ai_budget_windows" (
+  "id"           TEXT NOT NULL,
+  "budgetId"     TEXT NOT NULL,
+  "windowStart"  TIMESTAMP(3) NOT NULL,
+  "spentNanoUsd" BIGINT NOT NULL DEFAULT 0,
+  "spentTokens"  BIGINT NOT NULL DEFAULT 0,
+  "spentCount"   INTEGER NOT NULL DEFAULT 0,
+  "updatedAt"    TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  CONSTRAINT "ai_budget_windows_pkey" PRIMARY KEY ("id")
+);
+CREATE UNIQUE INDEX "ai_budget_windows_budgetId_windowStart_key" ON "ai_budget_windows" ("budgetId", "windowStart");
+
+-- Foreign keys for the wallet/budget relation graph.
+ALTER TABLE "ai_wallet_entries" ADD CONSTRAINT "ai_wallet_entries_walletId_fkey" FOREIGN KEY ("walletId") REFERENCES "ai_wallets" ("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+ALTER TABLE "ai_wallet_debit_allocations" ADD CONSTRAINT "ai_wallet_debit_allocations_debitEntryId_fkey" FOREIGN KEY ("debitEntryId") REFERENCES "ai_wallet_entries" ("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+ALTER TABLE "ai_wallet_debit_allocations" ADD CONSTRAINT "ai_wallet_debit_allocations_grantEntryId_fkey" FOREIGN KEY ("grantEntryId") REFERENCES "ai_wallet_entries" ("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+ALTER TABLE "ai_budget_windows" ADD CONSTRAINT "ai_budget_windows_budgetId_fkey" FOREIGN KEY ("budgetId") REFERENCES "ai_budgets" ("id") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- ---------------------------------------------------------------------------
+-- PARTIAL indexes (PostgreSQL-only; not expressible in the Prisma schema).
+-- ---------------------------------------------------------------------------
+-- Exactly one OPEN price row per (provider, model, operation, serviceTier) — the
+-- seed/upsert race guard that makes the effective-dated close-and-insert atomic.
+CREATE UNIQUE INDEX "ai_model_prices_open_row_key"
+  ON "ai_model_prices" ("provider", "model", "operation", "serviceTier")
+  WHERE "effectiveTo" IS NULL;
+
+-- Fast reaper scan over pending holds only.
+CREATE INDEX "ai_usage_records_pending_createdAt_idx"
+  ON "ai_usage_records" ("createdAt")
+  WHERE "status" = 'pending';

package/dist/prisma/schema.prisma.fragment

@@ -0,0 +1,197 @@
+// @bymax-one/nest-ai-tokens — Prisma schema fragment (spec §15.3).
+//
+// The library owns its tables but not your ORM. The supported merge path is
+// Prisma's MULTI-FILE SCHEMA (requires Prisma >= 6):
+//
+//   1. Copy this file into your host schema folder, e.g.
+//      `prisma/schema/ai-tokens.prisma` (keep your `datasource`/`generator`
+//      blocks in your main `prisma/schema/schema.prisma`).
+//   2. Run `prisma migrate dev` — Prisma diffs these seven models and emits the
+//      migration for you.
+//
+// Hosts that manage SQL by hand instead apply the shipped
+// `migrations/0001_init.sql` (which additionally creates the two PostgreSQL
+// PARTIAL indexes that Prisma cannot express). Library upgrades that change the
+// models ship new incremental SQL files plus a documented fragment diff.
+//
+// All money is `BigInt` nano-USD; every table carries `tenantId`. Table names are
+// snake_case (via `@@map`); columns keep their camelCase field names — the
+// official `PrismaAiTokensStore` adapter references them exactly as written here.
+
+model AiUsageRecord {
+  id                  String    @id @default(uuid())
+  tenantId            String
+  scopeType           String // tenant | team | user | key   (the payer)
+  scopeId             String
+  beneficiaryType     String?
+  beneficiaryId       String?
+  requestedBy         String?
+  provider            String
+  model               String
+  requestedModel      String?
+  operation           String
+  serviceTier         String    @default("standard")
+  feature             String
+  tags                String[]  @default([])
+  inputTokens         Int       @default(0)
+  outputTokens        Int       @default(0)
+  cacheReadTokens     Int       @default(0)
+  cacheWrite5mTokens  Int       @default(0)
+  cacheWrite1hTokens  Int       @default(0)
+  reasoningTokens     Int       @default(0)
+  audioInTokens       Int       @default(0)
+  audioOutTokens      Int       @default(0)
+  imageInTokens       Int       @default(0)
+  imageOutTokens      Int       @default(0)
+  totalTokens         Int
+  extraUnits          Json? // Record<string, number>
+  priceVersionId      String? // no FK by design: records outlive price-row lifecycle; see index below
+  rawCostNanoUsd      BigInt
+  surchargeNanoUsd    BigInt    @default(0)
+  billedCostNanoUsd   BigInt
+  markupMultiplier    Decimal   @db.Decimal(10, 4)
+  currency            String    @default("USD")
+  priceMissing        Boolean   @default(false)
+  status              String    @default("posted") // record() fast path; holds insert 'pending'
+  reversedByRecordId  String?
+  reversesRecordId    String?
+  idempotencyKey      String
+  payloadHash         String
+  correlationId       String?
+  requestId           String?
+  isSystemCost        Boolean   @default(false)
+  systemCostCategory  String?
+  enforced            Boolean   @default(false)
+  prevHash            String?
+  hash                String?
+  occurredAt          DateTime
+  createdAt           DateTime  @default(now())
+  updatedAt           DateTime  @updatedAt
+
+  @@unique([tenantId, idempotencyKey])
+  @@index([tenantId, occurredAt])
+  @@index([tenantId, scopeType, scopeId, occurredAt])
+  @@index([tenantId, feature, occurredAt])
+  @@index([tenantId, provider, model])
+  @@index([tenantId, systemCostCategory])
+  @@index([tenantId, beneficiaryType, beneficiaryId])
+  @@index([priceVersionId])
+  @@index([status, createdAt]) // reaper scan; Postgres partial index (WHERE status = 'pending') in the shipped SQL
+  @@map("ai_usage_records")
+}
+
+model AiModelPrice {
+  id                            String    @id @default(uuid())
+  provider                      String
+  model                         String
+  operation                     String
+  serviceTier                   String    @default("standard")
+  inputNanoUsdPerMillion        BigInt    @default(0)
+  outputNanoUsdPerMillion       BigInt    @default(0)
+  cacheReadNanoUsdPerMillion    BigInt    @default(0)
+  cacheWrite5mNanoUsdPerMillion BigInt    @default(0)
+  cacheWrite1hNanoUsdPerMillion BigInt    @default(0)
+  reasoningNanoUsdPerMillion    BigInt    @default(0)
+  audioInNanoUsdPerMillion      BigInt    @default(0)
+  audioOutNanoUsdPerMillion     BigInt    @default(0)
+  imageInNanoUsdPerMillion      BigInt    @default(0)
+  imageOutNanoUsdPerMillion     BigInt    @default(0)
+  tierThresholdTokens           Int?
+  tierInputNanoUsdPerMillion    BigInt?
+  tierOutputNanoUsdPerMillion   BigInt?
+  unitRates                     Json? // Record<string, string> — nano-USD per unit as decimal strings
+  currency                      String    @default("USD")
+  effectiveFrom                 DateTime  @default(now())
+  effectiveTo                   DateTime?
+  source                        String    @default("snapshot")
+
+  @@index([provider, model, operation, serviceTier, effectiveFrom])
+  // Shipped SQL adds: CREATE UNIQUE INDEX ... ON ai_model_prices ("provider", "model", "operation", "serviceTier")
+  //                   WHERE "effectiveTo" IS NULL;   -- exactly one open row per key (seed/upsert race guard)
+  @@map("ai_model_prices")
+}
+
+model AiWallet {
+  id             String   @id @default(uuid())
+  tenantId       String
+  ownerType      String // tenant | team | user
+  ownerId        String
+  balanceNanoUsd BigInt   @default(0) // materialized; source of truth = Σ entries (§9.4)
+  createdAt      DateTime @default(now())
+  updatedAt      DateTime @updatedAt
+  entries        AiWalletEntry[]
+
+  @@unique([tenantId, ownerType, ownerId])
+  @@map("ai_wallets")
+}
+
+model AiWalletEntry {
+  id                 String    @id @default(uuid())
+  walletId           String
+  type               String // grant | debit | refund | adjustment | expiry
+  amountNanoUsd      BigInt
+  priority           Int       @default(0)
+  effectiveAt        DateTime  @default(now())
+  expiresAt          DateTime?
+  usageRecordId      String?
+  idempotencyKey     String
+  reason             String?
+  createdAt          DateTime  @default(now())
+  wallet             AiWallet  @relation(fields: [walletId], references: [id])
+  allocationsAsDebit AiWalletDebitAllocation[] @relation("debit")
+  allocationsAsGrant AiWalletDebitAllocation[] @relation("grant")
+
+  @@unique([walletId, idempotencyKey])
+  @@index([walletId, effectiveAt])
+  @@index([walletId, type, expiresAt])
+  @@map("ai_wallet_entries")
+}
+
+model AiWalletDebitAllocation {
+  id            String        @id @default(uuid())
+  debitEntryId  String
+  grantEntryId  String
+  amountNanoUsd BigInt
+  debitEntry    AiWalletEntry @relation("debit", fields: [debitEntryId], references: [id])
+  grantEntry    AiWalletEntry @relation("grant", fields: [grantEntryId], references: [id])
+
+  @@index([grantEntryId])
+  @@index([debitEntryId])
+  @@map("ai_wallet_debit_allocations")
+}
+
+model AiBudget {
+  id             String   @id @default(uuid())
+  tenantId       String
+  scopeType      String
+  scopeId        String
+  features       String[] @default([])
+  limitNanoUsd   BigInt?
+  limitTokens    BigInt?
+  limitCount     Int?
+  window         String // day | week | month | total | custom:<seconds>
+  anchorAt       DateTime?
+  expiresAt      DateTime?
+  softThresholds Json // number[]
+  policy         String   @default("block")
+  createdAt      DateTime @default(now())
+  updatedAt      DateTime @updatedAt
+  windows        AiBudgetWindow[]
+
+  @@index([tenantId, scopeType, scopeId])
+  @@map("ai_budgets")
+}
+
+model AiBudgetWindow {
+  id           String   @id @default(uuid())
+  budgetId     String
+  windowStart  DateTime
+  spentNanoUsd BigInt   @default(0)
+  spentTokens  BigInt   @default(0) // BigInt: 'total' windows on busy tenants exceed int4
+  spentCount   Int      @default(0)
+  updatedAt    DateTime @updatedAt
+  budget       AiBudget @relation(fields: [budgetId], references: [id])
+
+  @@unique([budgetId, windowStart])
+  @@map("ai_budget_windows")
+}

package/dist/redis/index.cjs

@@ -0,0 +1,110 @@
+'use strict';
+
+// src/redis/index.ts
+var SAFE_INTEGER_MAX = "9007199254740991";
+var INCR_IF_BELOW_LUA = `
+local amount = tonumber(ARGV[1])
+local limit = tonumber(ARGV[2])
+if amount > ${SAFE_INTEGER_MAX} or amount < -${SAFE_INTEGER_MAX} or limit > ${SAFE_INTEGER_MAX} or limit < -${SAFE_INTEGER_MAX} then
+  return -1
+end
+local newValue = redis.call('INCRBY', KEYS[1], ARGV[1])
+if newValue > ${SAFE_INTEGER_MAX} or newValue < -${SAFE_INTEGER_MAX} then
+  redis.call('DECRBY', KEYS[1], ARGV[1])
+  return -1
+end
+if newValue > limit then
+  redis.call('DECRBY', KEYS[1], ARGV[1])
+  return 0
+end
+redis.call('PEXPIRE', KEYS[1], ARGV[3])
+return 1
+`;
+var DECR_FLOOR_LUA = `
+local newValue = redis.call('DECRBY', KEYS[1], ARGV[1])
+if newValue < 0 then
+  redis.call('SET', KEYS[1], '0')
+end
+return 1
+`;
+var CounterValueOutOfRangeError = class extends Error {
+  isCounterValueOutOfRange = true;
+  constructor() {
+    super("counter operand or result exceeds the safe-integer range");
+    this.name = "CounterValueOutOfRangeError";
+  }
+};
+var RedisBudgetCounterStore = class {
+  keyPrefix;
+  source;
+  connecting = null;
+  /**
+   * @param redis A live `ioredis` client, or a connection URL to lazily connect.
+   * @param options Optional key prefix.
+   */
+  constructor(redis, options = {}) {
+    this.keyPrefix = options.keyPrefix ?? "";
+    this.source = redis;
+  }
+  /**
+   * Atomically increment `key` by `amount` iff the result stays `<= limit`, setting
+   * the TTL. Returns `false` when the increment would exceed the limit.
+   *
+   * @param key The dimension counter key.
+   * @param amount The amount to add (int64 nano-USD or token/count units).
+   * @param limit The dimension limit.
+   * @param ttlSeconds The key TTL (window length + grace).
+   * @returns `true` when incremented within the limit, `false` when it would exceed it.
+   * @throws {CounterValueOutOfRangeError} when an operand or the resulting counter exceeds the safe-integer range.
+   */
+  async incrIfBelow(key, amount, limit, ttlSeconds) {
+    const client = await this.resolve();
+    const result = await client.eval(
+      INCR_IF_BELOW_LUA,
+      1,
+      this.prefixed(key),
+      amount.toString(),
+      limit.toString(),
+      Math.ceil(ttlSeconds * 1e3).toString()
+    );
+    if (result === -1) throw new CounterValueOutOfRangeError();
+    return result === 1;
+  }
+  /**
+   * Decrement `key` by `amount`, flooring the stored value at zero (release/reverse).
+   *
+   * @param key The dimension counter key.
+   * @param amount The amount to subtract.
+   */
+  async decr(key, amount) {
+    const client = await this.resolve();
+    await client.eval(DECR_FLOOR_LUA, 1, this.prefixed(key), amount.toString());
+  }
+  /**
+   * Reset (delete) `key` — used on window rotation.
+   *
+   * @param key The dimension counter key.
+   */
+  async reset(key) {
+    const client = await this.resolve();
+    await client.del(this.prefixed(key));
+  }
+  /** Prepend the configured key prefix. */
+  prefixed(key) {
+    return `${this.keyPrefix}${key}`;
+  }
+  /** Resolve the live client, lazily connecting a URL via a dynamic `ioredis` import. */
+  resolve() {
+    if (typeof this.source !== "string") return Promise.resolve(this.source);
+    this.connecting ??= this.connect(this.source);
+    return this.connecting;
+  }
+  /** Dynamically import `ioredis` and connect the given URL. */
+  async connect(url) {
+    const { default: RedisClient } = await import('ioredis');
+    return new RedisClient(url);
+  }
+};
+
+exports.CounterValueOutOfRangeError = CounterValueOutOfRangeError;
+exports.RedisBudgetCounterStore = RedisBudgetCounterStore;

package/dist/redis/index.d.cts

@@ -0,0 +1,98 @@
+import { Redis } from 'ioredis';
+
+/**
+ * @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 `RedisBudgetCounterStore` — the optional live cross-replica budget
+ * counter (`./redis` subpath, spec §10.8, §15.1). It makes budget enforcement cheap
+ * under high concurrency: `incrIfBelow` is a SINGLE atomic Lua script (increment,
+ * then undo and reject when the result would exceed the limit), so two racing
+ * replicas can never both pass a nearly-full budget. The DB conditional consume
+ * stays authoritative — this counter is the fast path, not the source of truth.
+ * Values are int64 (Redis native) written/compared as decimal strings; keys carry
+ * the caller's optional prefix. `ioredis` is an OPTIONAL peer: the constructor
+ * accepts a live `Redis` instance, or a connection URL that is lazily connected via
+ * a DYNAMIC import so the base library never statically depends on the client.
+ * Connection URLs (which may embed credentials) are never logged or placed on an
+ * exception.
+ * @layer redis
+ */
+
+/** Construction options for {@link RedisBudgetCounterStore}. */
+interface RedisBudgetCounterStoreOptions {
+    /** Prepended to every counter key (namespacing a shared Redis). */
+    keyPrefix?: string;
+}
+/**
+ * Signals that a counter operand or result falls outside the IEEE-754 safe-integer
+ * range (`±(2^53 − 1)`), where the Lua/Redis double arithmetic the fast path relies
+ * on would silently lose precision. It is thrown so `BudgetService` treats the counter
+ * as unavailable and falls back to the authoritative DB conditional consume, which
+ * compares int64 nano-USD exactly.
+ */
+declare class CounterValueOutOfRangeError extends Error {
+    readonly isCounterValueOutOfRange = true;
+    constructor();
+}
+/** The official Redis adapter for the live budget counter port. */
+declare class RedisBudgetCounterStore implements IBudgetCounterStore {
+    private readonly keyPrefix;
+    private readonly source;
+    private connecting;
+    /**
+     * @param redis A live `ioredis` client, or a connection URL to lazily connect.
+     * @param options Optional key prefix.
+     */
+    constructor(redis: Redis | string, options?: RedisBudgetCounterStoreOptions);
+    /**
+     * Atomically increment `key` by `amount` iff the result stays `<= limit`, setting
+     * the TTL. Returns `false` when the increment would exceed the limit.
+     *
+     * @param key The dimension counter key.
+     * @param amount The amount to add (int64 nano-USD or token/count units).
+     * @param limit The dimension limit.
+     * @param ttlSeconds The key TTL (window length + grace).
+     * @returns `true` when incremented within the limit, `false` when it would exceed it.
+     * @throws {CounterValueOutOfRangeError} when an operand or the resulting counter exceeds the safe-integer range.
+     */
+    incrIfBelow(key: string, amount: bigint, limit: bigint, ttlSeconds: number): Promise<boolean>;
+    /**
+     * Decrement `key` by `amount`, flooring the stored value at zero (release/reverse).
+     *
+     * @param key The dimension counter key.
+     * @param amount The amount to subtract.
+     */
+    decr(key: string, amount: bigint): Promise<void>;
+    /**
+     * Reset (delete) `key` — used on window rotation.
+     *
+     * @param key The dimension counter key.
+     */
+    reset(key: string): Promise<void>;
+    /** Prepend the configured key prefix. */
+    private prefixed;
+    /** Resolve the live client, lazily connecting a URL via a dynamic `ioredis` import. */
+    private resolve;
+    /** Dynamically import `ioredis` and connect the given URL. */
+    private connect;
+}
+
+export { CounterValueOutOfRangeError, RedisBudgetCounterStore, type RedisBudgetCounterStoreOptions };