@hachej/boring-core 0.1.42 → 0.1.44

package/dist/{chunk-C3YMOITB.js → chunk-I56OTSPB.js}

@@ -1,7 +1,7 @@
 import {
   ERROR_CODES,
   HttpError
-} from "./chunk-H5KU6R6Y.js";
+} from "./chunk-LIBHVT7V.js";
 import {
   __export
 } from "./chunk-MLKGABMK.js";
@@ -13,13 +13,13 @@ function createDatabase(config) {
   if (!config.databaseUrl) {
     throw new Error("databaseUrl is required to create a database connection");
   }
-  const sql6 = postgres(config.databaseUrl, {
+  const sql7 = postgres(config.databaseUrl, {
     max: 10,
     idle_timeout: 20,
     connect_timeout: 10
   });
-  const db = drizzle(sql6);
-  return { db, sql: sql6 };
+  const db = drizzle(sql7);
+  return { db, sql: sql7 };
 }
 
 // src/server/db/migrate.ts
@@ -539,10 +539,14 @@ var schema_exports = {};
 __export(schema_exports, {
   accounts: () => accounts,
   accountsRelations: () => accountsRelations,
+  creditGrants: () => creditGrants,
+  creditPurchases: () => creditPurchases,
   idempotencyKeys: () => idempotencyKeys,
   sessions: () => sessions,
   sessionsRelations: () => sessionsRelations,
   telemetryEvents: () => telemetryEvents,
+  usageLedger: () => usageLedger,
+  usageReservations: () => usageReservations,
   userSettings: () => userSettings,
   userSettingsRelations: () => userSettingsRelations,
   users: () => users,
@@ -644,7 +648,7 @@ var accountsRelations = relations(accounts, ({ one }) => ({
 }));
 
 // src/server/db/schema.ts
-import { pgTable as pgTable2, text as text2, uuid as uuid2, jsonb, timestamp as timestamp2, primaryKey, index as index2, integer, boolean as boolean2, uniqueIndex, check, customType } from "drizzle-orm/pg-core";
+import { pgTable as pgTable2, text as text2, uuid as uuid2, jsonb, timestamp as timestamp2, primaryKey, index as index2, integer, bigint, boolean as boolean2, uniqueIndex, check, customType } from "drizzle-orm/pg-core";
 import { relations as relations2, sql as sql3 } from "drizzle-orm";
 var bytea = customType({
   dataType() {
@@ -867,6 +871,120 @@ var idempotencyKeys = pgTable2(
     index2("idempotency_keys_created_at_idx").on(table.createdAt)
   ]
 );
+var creditGrants = pgTable2(
+  "boring_credit_grants",
+  {
+    id: uuid2("id").default(sql3`gen_random_uuid()`).primaryKey(),
+    userId: text2("user_id").notNull(),
+    amountMicros: bigint("amount_micros", { mode: "number" }).notNull(),
+    reason: text2("reason").notNull(),
+    expiresAt: timestamp2("expires_at"),
+    createdAt: timestamp2("created_at").defaultNow().notNull()
+  },
+  (table) => [
+    uniqueIndex("boring_credit_grants_user_reason_idx").on(table.userId, table.reason),
+    check("boring_credit_grants_amount_check", sql3`${table.amountMicros} > 0`)
+  ]
+);
+var creditPurchases = pgTable2(
+  "boring_credit_purchases",
+  {
+    orderId: text2("order_id").primaryKey(),
+    userId: text2("user_id"),
+    amountMicros: bigint("amount_micros", { mode: "number" }),
+    status: text2("status").notNull().default("granted"),
+    source: text2("source").notNull().default("lemonsqueezy"),
+    createdAt: timestamp2("created_at").defaultNow().notNull(),
+    refundedAt: timestamp2("refunded_at"),
+    /** Cumulative credit micros already revoked for this order (supports
+     * repeated partial refunds without double-debiting). */
+    refundedMicros: bigint("refunded_micros", { mode: "number" }),
+    /** Pending refund fraction in parts-per-million (fraction × 1e6), set when a
+     * partial refund arrives before the grant; applied at grant time. */
+    pendingRefundPpm: bigint("pending_refund_ppm", { mode: "number" }),
+    /** Provider identity captured at grant time, for audit/reconcile and to match
+     * a later refund against the order we actually credited. */
+    storeId: text2("store_id"),
+    testMode: boolean2("test_mode"),
+    currency: text2("currency"),
+    variantId: text2("variant_id")
+  },
+  (table) => [
+    index2("boring_credit_purchases_user_idx").on(table.userId),
+    check("boring_credit_purchases_amount_check", sql3`${table.amountMicros} IS NULL OR ${table.amountMicros} > 0`),
+    check("boring_credit_purchases_status_check", sql3`${table.status} IN ('granted', 'refunded', 'refund_pending')`),
+    // A granted row must carry the credited user + amount; a pre-grant tombstone
+    // ('refunded' full, or 'refund_pending' partial) may omit them.
+    check(
+      "boring_credit_purchases_granted_check",
+      sql3`${table.status} IN ('refunded', 'refund_pending') OR (${table.userId} IS NOT NULL AND ${table.amountMicros} IS NOT NULL)`
+    )
+  ]
+);
+var usageReservations = pgTable2(
+  "boring_usage_reservations",
+  {
+    id: uuid2("id").default(sql3`gen_random_uuid()`).primaryKey(),
+    userId: text2("user_id").notNull(),
+    workspaceId: text2("workspace_id"),
+    sessionId: text2("session_id"),
+    runId: text2("run_id").notNull(),
+    source: text2("source").notNull().default(""),
+    amountMicros: bigint("amount_micros", { mode: "number" }).notNull(),
+    status: text2("status").notNull().default("active"),
+    // Durable terminal-charge intent: set true when the coordinator decided this
+    // run must be charged the fallback hold (started/successful run with no billable
+    // usage, or a failed usage write) BEFORE attempting the charge. If that charge
+    // write then fails transiently, the stale-expiry sweep still charges the hold
+    // (a marked reservation with zero billed rows is NOT freed) — so a started run
+    // can't go free on a brief finalization-time DB outage.
+    chargeOnExpire: boolean2("charge_on_expire").notNull().default(false),
+    createdAt: timestamp2("created_at").defaultNow().notNull(),
+    expiresAt: timestamp2("expires_at").notNull()
+  },
+  (table) => [
+    uniqueIndex("boring_usage_reservations_active_run_idx").on(table.runId).where(sql3`${table.status} = 'active'`),
+    index2("boring_usage_reservations_user_status_idx").on(table.userId, table.status, table.expiresAt),
+    check("boring_usage_reservations_amount_check", sql3`${table.amountMicros} > 0`),
+    check(
+      "boring_usage_reservations_status_check",
+      sql3`${table.status} IN ('active', 'settled', 'released', 'expired')`
+    )
+  ]
+);
+var usageLedger = pgTable2(
+  "boring_usage_ledger",
+  {
+    /** Caller-provided stable usage id; the idempotency key for inserts. */
+    id: text2("id").primaryKey(),
+    userId: text2("user_id").notNull(),
+    workspaceId: text2("workspace_id"),
+    sessionId: text2("session_id"),
+    runId: text2("run_id"),
+    messageId: text2("message_id"),
+    source: text2("source").notNull().default(""),
+    provider: text2("provider"),
+    model: text2("model"),
+    inputTokens: bigint("input_tokens", { mode: "number" }).notNull().default(0),
+    outputTokens: bigint("output_tokens", { mode: "number" }).notNull().default(0),
+    cacheReadTokens: bigint("cache_read_tokens", { mode: "number" }).notNull().default(0),
+    cacheWriteTokens: bigint("cache_write_tokens", { mode: "number" }).notNull().default(0),
+    providerCostMicros: bigint("provider_cost_micros", { mode: "number" }).notNull().default(0),
+    billedCostMicros: bigint("billed_cost_micros", { mode: "number" }).notNull(),
+    stopReason: text2("stop_reason"),
+    metadata: jsonb("metadata").notNull().default({}),
+    createdAt: timestamp2("created_at").defaultNow().notNull()
+  },
+  (table) => [
+    index2("boring_usage_ledger_user_created_idx").on(table.userId, table.createdAt),
+    index2("boring_usage_ledger_run_idx").on(table.runId),
+    check("boring_usage_ledger_billed_check", sql3`${table.billedCostMicros} >= 0`),
+    check(
+      "boring_usage_ledger_tokens_check",
+      sql3`${table.inputTokens} >= 0 AND ${table.outputTokens} >= 0 AND ${table.cacheReadTokens} >= 0 AND ${table.cacheWriteTokens} >= 0 AND ${table.providerCostMicros} >= 0`
+    )
+  ]
+);
 var telemetryEvents = pgTable2(
   "telemetry_events",
   {
@@ -1681,6 +1799,525 @@ var PostgresUserStore = class {
   }
 };
 
+// src/server/db/stores/PostgresMeteringStore.ts
+import { and as and2, desc as desc2, eq as eq3, gt, inArray, isNull as isNull2, lt, lte, or, sql as sql6 } from "drizzle-orm";
+var InsufficientCreditError = class extends Error {
+  constructor(availableMicros, requiredMicros) {
+    super("insufficient credit");
+    this.availableMicros = availableMicros;
+    this.requiredMicros = requiredMicros;
+    this.name = "InsufficientCreditError";
+  }
+  availableMicros;
+  requiredMicros;
+  statusCode = 402;
+  // Matches @hachej/boring-agent's canonical ErrorCode so the agent route
+  // preserves it (instead of degrading to INTERNAL_ERROR) when a sink throws
+  // this across the boundary.
+  code = "PAYMENT_REQUIRED";
+};
+var PostgresMeteringStore = class {
+  constructor(db) {
+    this.db = db;
+  }
+  db;
+  /** Idempotently create a grant keyed by (userId, reason). */
+  async grantOnce(input) {
+    if (!Number.isSafeInteger(input.amountMicros) || input.amountMicros <= 0) {
+      throw new Error("grant amountMicros must be a positive integer");
+    }
+    const rows = await this.db.insert(creditGrants).values({
+      userId: input.userId,
+      reason: input.reason,
+      amountMicros: input.amountMicros,
+      expiresAt: input.expiresAt ?? null
+    }).onConflictDoNothing({ target: [creditGrants.userId, creditGrants.reason] }).returning({ id: creditGrants.id });
+    return { created: rows.length > 0 };
+  }
+  /**
+   * Credit a purchase exactly once GLOBALLY per order id. The order id is the
+   * primary key, so a webhook retry or a delivery misrouted to a different user
+   * can never double-credit. A per-order advisory lock serializes this against
+   * revokePurchase so a refund that arrives BEFORE order_created (out-of-order
+   * delivery) leaves a 'refunded' tombstone that blocks this grant — the user
+   * never keeps credits for a refunded order. Returns `granted: false` when the
+   * order was already processed or has been refunded.
+   */
+  async grantPurchaseOnce(input) {
+    if (!input.orderId) throw new Error("grantPurchaseOnce requires an orderId");
+    if (!Number.isSafeInteger(input.amountMicros) || input.amountMicros <= 0) {
+      throw new Error("purchase amountMicros must be a positive integer");
+    }
+    const source = input.source ?? "lemonsqueezy";
+    const identity = { storeId: input.storeId ?? null, testMode: input.testMode ?? null, currency: input.currency ?? null, variantId: input.variantId ?? null };
+    return this.db.transaction(async (tx) => {
+      await tx.execute(sql6`SELECT pg_advisory_xact_lock(hashtext(${`purchase:${input.orderId}`}))`);
+      const existing = await tx.select({
+        status: creditPurchases.status,
+        userId: creditPurchases.userId,
+        amountMicros: creditPurchases.amountMicros,
+        pendingRefundPpm: creditPurchases.pendingRefundPpm,
+        storeId: creditPurchases.storeId,
+        testMode: creditPurchases.testMode,
+        currency: creditPurchases.currency,
+        variantId: creditPurchases.variantId
+      }).from(creditPurchases).where(eq3(creditPurchases.orderId, input.orderId)).limit(1);
+      const prior = existing[0];
+      if (prior && prior.status !== "refund_pending") {
+        if (prior.status === "granted" && (prior.userId !== input.userId || prior.amountMicros !== input.amountMicros || prior.storeId !== (input.storeId ?? null) || prior.testMode !== (input.testMode ?? null) || prior.currency !== (input.currency ?? null) || prior.variantId !== (input.variantId ?? null))) {
+          throw new Error(
+            `purchase ${input.orderId} already granted (user ${prior.userId}, ${prior.amountMicros} micros, store ${prior.storeId}, testMode ${prior.testMode}, variant ${prior.variantId}); refusing conflicting re-grant (user ${input.userId}, ${input.amountMicros} micros, store ${input.storeId ?? null}, testMode ${input.testMode ?? null}, variant ${input.variantId ?? null})`
+          );
+        }
+        return { granted: false };
+      }
+      const insertGrant = async () => {
+        const grantRows = await tx.insert(creditGrants).values({ userId: input.userId, reason: `purchase:${input.orderId}`, amountMicros: input.amountMicros }).onConflictDoNothing({ target: [creditGrants.userId, creditGrants.reason] }).returning({ id: creditGrants.id });
+        if (grantRows.length === 0) {
+          throw new Error(`purchase ${input.orderId} claimed but a credit grant already existed`);
+        }
+      };
+      if (prior?.status === "refund_pending") {
+        const pendingPpm = prior.pendingRefundPpm ?? 0;
+        const revoke = Math.min(input.amountMicros, Math.round(input.amountMicros * pendingPpm / 1e6));
+        await tx.update(creditPurchases).set({ userId: input.userId, amountMicros: input.amountMicros, status: revoke >= input.amountMicros ? "refunded" : "granted", pendingRefundPpm: null, refundedMicros: revoke > 0 ? revoke : null, refundedAt: revoke > 0 ? /* @__PURE__ */ new Date() : null, ...identity }).where(eq3(creditPurchases.orderId, input.orderId));
+        await insertGrant();
+        if (revoke > 0) {
+          await this.insertVerifiedLedgerDebit(tx, {
+            id: `refund:${input.orderId}:${revoke}`,
+            userId: input.userId,
+            amountMicros: revoke,
+            metadata: { kind: "purchase_refund", orderId: input.orderId, refundedToMicros: revoke, appliedAtGrant: true }
+          });
+        }
+        return { granted: true };
+      }
+      await tx.insert(creditPurchases).values({
+        orderId: input.orderId,
+        userId: input.userId,
+        amountMicros: input.amountMicros,
+        status: "granted",
+        source,
+        ...identity
+      });
+      await insertGrant();
+      return { granted: true };
+    });
+  }
+  /**
+   * Revoke a refunded/disputed purchase. Under the same per-order advisory lock
+   * as grantPurchaseOnce, supports repeated PARTIAL refunds:
+   *  - `refundFraction` is the cumulative fraction of the order (by money) that
+   *    has been refunded — i.e. LS `refunded_amount / total` (both tax-inclusive),
+   *    which maps the refund onto the same basis as the credited amount. The
+   *    revoked credits = round(creditedMicros × fraction), capped at credited.
+   *    The method debits only the delta since the last refund. Omit (undefined)
+   *    for a full refund of the entire credited amount.
+   *  - granted order  → debit the delta, track cumulative `refunded_micros`, and
+   *    mark 'refunded' once fully revoked; returns revoked=true when a debit was
+   *    posted.
+   *  - not yet seen   → write a 'refunded' tombstone so a later order_created
+   *    cannot grant; returns revoked=false (nothing was credited yet).
+   *  - already fully refunded / no new delta → no-op; returns revoked=false.
+   */
+  async revokePurchase(orderId, opts = {}) {
+    if (!orderId) throw new Error("revokePurchase requires an orderId");
+    const source = opts.source ?? "lemonsqueezy-refund";
+    const allowTombstone = opts.allowTombstone === true;
+    if (opts.refundFraction !== void 0 && (!Number.isFinite(opts.refundFraction) || opts.refundFraction < 0)) {
+      throw new Error("revokePurchase refundFraction must be a non-negative number");
+    }
+    return this.db.transaction(async (tx) => {
+      await tx.execute(sql6`SELECT pg_advisory_xact_lock(hashtext(${`purchase:${orderId}`}))`);
+      const existing = await tx.select({
+        userId: creditPurchases.userId,
+        amountMicros: creditPurchases.amountMicros,
+        status: creditPurchases.status,
+        refundedMicros: creditPurchases.refundedMicros,
+        pendingRefundPpm: creditPurchases.pendingRefundPpm,
+        storeId: creditPurchases.storeId,
+        testMode: creditPurchases.testMode,
+        currency: creditPurchases.currency
+      }).from(creditPurchases).where(eq3(creditPurchases.orderId, orderId)).limit(1);
+      const fraction = opts.refundFraction ?? 1;
+      const row = existing[0];
+      if (!row) {
+        if (!allowTombstone) return { revoked: false };
+        const tombstoneIdentity = { storeId: opts.expectedStoreId ?? null, testMode: opts.expectedTestMode ?? null };
+        await tx.insert(creditPurchases).values(
+          fraction >= 1 ? { orderId, status: "refunded", source, refundedAt: /* @__PURE__ */ new Date(), ...tombstoneIdentity } : { orderId, status: "refund_pending", source, refundedAt: /* @__PURE__ */ new Date(), pendingRefundPpm: Math.round(fraction * 1e6), ...tombstoneIdentity }
+        );
+        return { revoked: false };
+      }
+      if (row.status === "refund_pending") {
+        if (fraction >= 1) {
+          await tx.update(creditPurchases).set({ status: "refunded", pendingRefundPpm: null, refundedAt: /* @__PURE__ */ new Date() }).where(eq3(creditPurchases.orderId, orderId));
+        } else {
+          const newPpm = Math.max(row.pendingRefundPpm ?? 0, Math.round(fraction * 1e6));
+          await tx.update(creditPurchases).set({ pendingRefundPpm: newPpm, refundedAt: /* @__PURE__ */ new Date() }).where(eq3(creditPurchases.orderId, orderId));
+        }
+        return { revoked: false };
+      }
+      if (row.storeId != null && opts.expectedStoreId != null && row.storeId !== opts.expectedStoreId || row.testMode != null && opts.expectedTestMode != null && row.testMode !== opts.expectedTestMode || row.currency != null && opts.expectedCurrency != null && row.currency.toUpperCase() !== opts.expectedCurrency.toUpperCase()) {
+        throw new Error(`refund identity mismatch for ${orderId}: credited row (store=${row.storeId}, testMode=${row.testMode}, currency=${row.currency}) does not match expected (store=${opts.expectedStoreId}, testMode=${opts.expectedTestMode}, currency=${opts.expectedCurrency})`);
+      }
+      if (row.userId) {
+        await tx.execute(sql6`SELECT pg_advisory_xact_lock(hashtext(${row.userId}))`);
+      }
+      const credited = row.amountMicros ?? 0;
+      const alreadyRefunded = row.refundedMicros ?? 0;
+      const target = Math.min(credited, Math.round(credited * Math.min(1, fraction)));
+      const delta = target - alreadyRefunded;
+      const fullyRefunded = target >= credited;
+      if (delta <= 0) {
+        if (fullyRefunded && row.status !== "refunded") {
+          await tx.update(creditPurchases).set({ status: "refunded", refundedAt: /* @__PURE__ */ new Date() }).where(eq3(creditPurchases.orderId, orderId));
+        }
+        return { revoked: false };
+      }
+      const inserted = await this.insertVerifiedLedgerDebit(tx, {
+        id: `refund:${orderId}:${target}`,
+        userId: row.userId,
+        amountMicros: delta,
+        source,
+        metadata: { kind: "purchase_refund", orderId, refundedToMicros: target }
+      });
+      await tx.update(creditPurchases).set({ refundedMicros: target, status: fullyRefunded ? "refunded" : row.status, refundedAt: /* @__PURE__ */ new Date() }).where(eq3(creditPurchases.orderId, orderId));
+      return { revoked: inserted };
+    });
+  }
+  /**
+   * Insert a refund debit idempotently by id. If the id already exists (manual
+   * repair / corrupted retry), VERIFY the existing row is the same debit (user +
+   * amount) — throw on mismatch so a caller never records a refund the balance was
+   * not actually debited for. Returns true iff a new debit row was written.
+   */
+  async insertVerifiedLedgerDebit(tx, input) {
+    const rows = await tx.insert(usageLedger).values({
+      id: input.id,
+      userId: input.userId,
+      runId: input.runId ?? null,
+      source: input.source ?? "lemonsqueezy-refund",
+      billedCostMicros: input.amountMicros,
+      providerCostMicros: 0,
+      metadata: input.metadata
+    }).onConflictDoNothing({ target: usageLedger.id }).returning({ id: usageLedger.id });
+    if (rows.length > 0) return true;
+    const existing = await tx.select({ userId: usageLedger.userId, billedCostMicros: usageLedger.billedCostMicros }).from(usageLedger).where(eq3(usageLedger.id, input.id)).limit(1);
+    const e = existing[0];
+    if (!e || e.userId !== input.userId || e.billedCostMicros !== input.amountMicros) {
+      throw new Error(`ledger debit conflict for ${input.id}: existing debit does not match (refusing to record a debit that wasn't actually applied)`);
+    }
+    return false;
+  }
+  /** Total billed micros already recorded for a run (for fallback top-up so a
+   * partial-success run isn't charged the hold ON TOP of its real usage). */
+  async billedMicrosForRun(userId, runId) {
+    const rows = await this.db.select({ total: sql6`coalesce(sum(${usageLedger.billedCostMicros}), 0)` }).from(usageLedger).where(and2(eq3(usageLedger.userId, userId), eq3(usageLedger.runId, runId)));
+    return Number(rows[0]?.total ?? 0);
+  }
+  /** Total billed micros for a specific RESERVATION (run attempt). Preferred over
+   * billedMicrosForRun for fallback top-up: runId is reused on client-nonce
+   * replay, so summing by runId would count a prior attempt's billing and let a
+   * later reusing attempt settle free. */
+  async billedMicrosForReservation(userId, reservationId) {
+    const rows = await this.db.select({ total: sql6`coalesce(sum(${usageLedger.billedCostMicros}), 0)` }).from(usageLedger).where(and2(eq3(usageLedger.userId, userId), sql6`${usageLedger.metadata}->>'reservationId' = ${reservationId}`));
+    return Number(rows[0]?.total ?? 0);
+  }
+  /** Durably record that an ACTIVE reservation must be charged the fallback hold if
+   * it expires, BEFORE attempting the actual fallback charge. Committed on its own so
+   * the intent survives a subsequent failed charge write — the expiry sweep then
+   * charges a marked reservation even with zero billed rows (no free started run on a
+   * brief finalization-time DB outage). Idempotent; a no-op on a non-active row. */
+  async markReservationFallbackCharge(userId, reservationId) {
+    await this.db.update(usageReservations).set({ chargeOnExpire: true }).where(and2(eq3(usageReservations.id, reservationId), eq3(usageReservations.userId, userId), eq3(usageReservations.status, "active")));
+  }
+  async getBalance(userId, now = /* @__PURE__ */ new Date()) {
+    return this.computeBalance(this.db, userId, now);
+  }
+  /** Most-recent credit ledger for the account activity view: grants/purchases
+   * (positive) merged with usage/refund/fallback debits (negative), newest first,
+   * scoped to the user and capped at `limit` (clamped 1..50). Descriptions are
+   * generic/sanitized; zero-amount usage rows (zero-token) are omitted as noise. */
+  async listLedger(userId, limit) {
+    const cap = Math.min(50, Math.max(1, Number.isFinite(limit) ? Math.trunc(limit) : 1));
+    const [grants, usage] = await Promise.all([
+      this.db.select({ id: creditGrants.id, amountMicros: creditGrants.amountMicros, reason: creditGrants.reason, createdAt: creditGrants.createdAt }).from(creditGrants).where(eq3(creditGrants.userId, userId)).orderBy(desc2(creditGrants.createdAt)).limit(cap),
+      this.db.select({ id: usageLedger.id, billedCostMicros: usageLedger.billedCostMicros, source: usageLedger.source, createdAt: usageLedger.createdAt }).from(usageLedger).where(and2(eq3(usageLedger.userId, userId), gt(usageLedger.billedCostMicros, 0))).orderBy(desc2(usageLedger.createdAt)).limit(cap)
+    ]);
+    const entries = [
+      ...grants.map((g) => ({
+        id: opaqueLedgerId("g", g.id),
+        ...describeGrant(g.reason),
+        amountMicros: g.amountMicros,
+        createdAt: g.createdAt.toISOString()
+      })),
+      ...usage.map((u) => ({
+        id: opaqueLedgerId("u", u.id),
+        ...describeUsage(u.source),
+        amountMicros: -u.billedCostMicros,
+        createdAt: u.createdAt.toISOString()
+      }))
+    ];
+    return entries.sort((a, b) => a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0).slice(0, cap);
+  }
+  /**
+   * Reserve credit for a run. Serialized per user (advisory transaction
+   * lock) so concurrent reservations cannot jointly overdraw. Idempotent per
+   * runId: re-reserving while a reservation is still active returns the
+   * existing reservation instead of double-holding. Throws
+   * InsufficientCreditError when the available balance is below
+   * minAvailableMicros (default: the reservation amount itself).
+   */
+  async reserve(input, now = /* @__PURE__ */ new Date()) {
+    if (!Number.isSafeInteger(input.amountMicros) || input.amountMicros <= 0) {
+      throw new Error("reserve amountMicros must be a positive integer");
+    }
+    if (!Number.isFinite(input.ttlSeconds) || input.ttlSeconds <= 0) {
+      throw new Error("reserve ttlSeconds must be positive");
+    }
+    if (input.minAvailableMicros !== void 0 && (!Number.isSafeInteger(input.minAvailableMicros) || input.minAvailableMicros < 0)) {
+      throw new Error("reserve minAvailableMicros must be a non-negative integer");
+    }
+    const minAvailable = input.minAvailableMicros ?? input.amountMicros;
+    const expiresAt = new Date(now.getTime() + input.ttlSeconds * 1e3);
+    return this.db.transaction(async (tx) => {
+      await tx.execute(sql6`SELECT pg_advisory_xact_lock(hashtext(${input.userId}))`);
+      await this.expireUserStaleReservations(tx, input.userId, now);
+      const existing = await tx.select({ id: usageReservations.id }).from(usageReservations).where(and2(
+        eq3(usageReservations.runId, input.runId),
+        eq3(usageReservations.userId, input.userId),
+        eq3(usageReservations.status, "active")
+      )).limit(1);
+      const existingId = existing[0]?.id;
+      if (existingId) return { reservationId: existingId };
+      const balance = await this.computeBalance(tx, input.userId, now);
+      if (balance.availableMicros < minAvailable) {
+        throw new InsufficientCreditError(balance.availableMicros, minAvailable);
+      }
+      const rows = await tx.insert(usageReservations).values({
+        userId: input.userId,
+        workspaceId: input.workspaceId ?? null,
+        sessionId: input.sessionId ?? null,
+        runId: input.runId,
+        source: input.source ?? "",
+        amountMicros: input.amountMicros,
+        status: "active",
+        expiresAt
+      }).returning({ id: usageReservations.id });
+      const reservationId = rows[0]?.id;
+      if (!reservationId) throw new Error("reservation insert returned no id");
+      return { reservationId };
+    });
+  }
+  /** Idempotent ledger insert; returns whether a new row was written. Serialized
+   * under the user's advisory lock so a positive debit is ordered with that user's
+   * reserve()/expiry: a debit that pushes the balance below the floor is visible to a
+   * concurrent reserve (which then waits and is refused), keeping the documented
+   * "overshoot → next run refused" boundary even for over-budget/misrouted runs. */
+  async recordUsage(input) {
+    if (!Number.isSafeInteger(input.billedCostMicros) || input.billedCostMicros < 0) {
+      throw new Error("billedCostMicros must be a non-negative integer");
+    }
+    return this.db.transaction(async (tx) => {
+      await tx.execute(sql6`SELECT pg_advisory_xact_lock(hashtext(${input.userId}))`);
+      const rows = await tx.insert(usageLedger).values({
+        id: input.usageId,
+        userId: input.userId,
+        workspaceId: input.workspaceId ?? null,
+        sessionId: input.sessionId ?? null,
+        runId: input.runId ?? null,
+        messageId: input.messageId ?? null,
+        source: input.source ?? "",
+        provider: input.provider ?? null,
+        model: input.model ?? null,
+        inputTokens: input.inputTokens ?? 0,
+        outputTokens: input.outputTokens ?? 0,
+        cacheReadTokens: input.cacheReadTokens ?? 0,
+        cacheWriteTokens: input.cacheWriteTokens ?? 0,
+        providerCostMicros: input.providerCostMicros ?? 0,
+        billedCostMicros: input.billedCostMicros,
+        stopReason: input.stopReason ?? null,
+        metadata: input.metadata ?? {}
+      }).onConflictDoNothing({ target: usageLedger.id }).returning({ id: usageLedger.id });
+      if (rows.length > 0) return { inserted: true };
+      const existing = await tx.select({
+        userId: usageLedger.userId,
+        runId: usageLedger.runId,
+        messageId: usageLedger.messageId,
+        source: usageLedger.source,
+        provider: usageLedger.provider,
+        model: usageLedger.model,
+        inputTokens: usageLedger.inputTokens,
+        outputTokens: usageLedger.outputTokens,
+        cacheReadTokens: usageLedger.cacheReadTokens,
+        cacheWriteTokens: usageLedger.cacheWriteTokens,
+        providerCostMicros: usageLedger.providerCostMicros,
+        billedCostMicros: usageLedger.billedCostMicros,
+        stopReason: usageLedger.stopReason,
+        reservationId: sql6`${usageLedger.metadata}->>'reservationId'`
+      }).from(usageLedger).where(eq3(usageLedger.id, input.usageId)).limit(1);
+      const e = existing[0];
+      const incomingReservationId = input.metadata?.reservationId ?? null;
+      const matches = e && e.userId === input.userId && e.runId === (input.runId ?? null) && e.messageId === (input.messageId ?? null) && e.source === (input.source ?? "") && e.provider === (input.provider ?? null) && e.model === (input.model ?? null) && e.inputTokens === (input.inputTokens ?? 0) && e.outputTokens === (input.outputTokens ?? 0) && e.cacheReadTokens === (input.cacheReadTokens ?? 0) && e.cacheWriteTokens === (input.cacheWriteTokens ?? 0) && e.providerCostMicros === (input.providerCostMicros ?? 0) && e.billedCostMicros === input.billedCostMicros && e.stopReason === (input.stopReason ?? null) && e.reservationId === incomingReservationId;
+      if (!matches) {
+        throw new Error(`usage ledger id collision for ${input.usageId}: existing row does not match this usage (refusing to silently drop the debit or corrupt the audit trail)`);
+      }
+      return { inserted: false };
+    });
+  }
+  /**
+   * Finish a reservation. Settling also recovers reservations that expired
+   * before a delayed settlement retry, so charged usage never leaves a
+   * reservation dangling. Releasing only touches active rows. Idempotent:
+   * repeat calls are no-ops.
+   *
+   * A runId may have more than one row (an expired row plus a fresh active
+   * retry), so the runId fallback resolves to the single newest matching row
+   * — a settle never flips both the dead and the live reservation together.
+   */
+  async finishReservation(input, status) {
+    if (!input.reservationId && !input.runId) {
+      throw new Error("finishReservation requires reservationId or runId");
+    }
+    if (!input.reservationId && !input.userId) {
+      throw new Error("finishReservation by runId requires userId");
+    }
+    const matchable = status === "settled" ? ["active", "expired"] : ["active"];
+    return this.db.transaction(async (tx) => {
+      let userId = input.userId;
+      if (!userId && input.reservationId) {
+        const owner = await tx.select({ userId: usageReservations.userId }).from(usageReservations).where(eq3(usageReservations.id, input.reservationId)).limit(1);
+        userId = owner[0]?.userId;
+      }
+      if (userId) await tx.execute(sql6`SELECT pg_advisory_xact_lock(hashtext(${userId}))`);
+      let targetId = input.reservationId;
+      if (!targetId) {
+        const lookup = [
+          eq3(usageReservations.runId, input.runId),
+          inArray(usageReservations.status, matchable)
+        ];
+        if (input.userId) lookup.push(eq3(usageReservations.userId, input.userId));
+        const found = await tx.select({ id: usageReservations.id }).from(usageReservations).where(and2(...lookup));
+        if (found.length === 0) return { updated: false };
+        if (found.length > 1) {
+          throw new Error("finishReservation by runId is ambiguous (multiple rows); pass reservationId");
+        }
+        targetId = found[0]?.id;
+        if (!targetId) return { updated: false };
+      }
+      const conditions = [eq3(usageReservations.id, targetId), inArray(usageReservations.status, matchable)];
+      if (input.userId) conditions.push(eq3(usageReservations.userId, input.userId));
+      const rows = await tx.update(usageReservations).set({ status }).where(and2(...conditions)).returning({ id: usageReservations.id });
+      return { updated: rows.length > 0 };
+    });
+  }
+  /** Expire stale active reservations without charging. Returns the count. */
+  async expireStaleReservations(now = /* @__PURE__ */ new Date()) {
+    const users2 = await this.db.selectDistinct({ userId: usageReservations.userId }).from(usageReservations).where(and2(eq3(usageReservations.status, "active"), lt(usageReservations.expiresAt, now)));
+    let total = 0;
+    for (const { userId } of users2) {
+      total += await this.db.transaction(async (tx) => {
+        await tx.execute(sql6`SELECT pg_advisory_xact_lock(hashtext(${userId}))`);
+        return this.expireUserStaleReservations(tx, userId, now);
+      });
+    }
+    return total;
+  }
+  /**
+   * Expire one user's stale active reservations under the SINGLE charge-aware
+   * policy. CALLER MUST already hold pg_advisory_xact_lock(hashtext(userId)).
+   * A reservation that reached TTL without an explicit settle/release had a failed
+   * finalization: if it has POSITIVE billed usage (`billedTotal > 0`) OR carries the
+   * durable `charge_on_expire` marker, the run did chargeable work, so top it up to
+   * the hold (idempotent) rather than free it; a reservation with only zero-billed
+   * rows and no marker is a non-billable/pre-execution abandon and is freed (so a
+   * user who closed the tab isn't over-charged).
+   */
+  async expireUserStaleReservations(tx, userId, now) {
+    const stale = await tx.update(usageReservations).set({ status: "expired" }).where(and2(eq3(usageReservations.userId, userId), eq3(usageReservations.status, "active"), lte(usageReservations.expiresAt, now))).returning({ id: usageReservations.id, runId: usageReservations.runId, amountMicros: usageReservations.amountMicros, chargeOnExpire: usageReservations.chargeOnExpire });
+    for (const r of stale) {
+      const usage = await tx.select({ total: sql6`coalesce(sum(${usageLedger.billedCostMicros}), 0)` }).from(usageLedger).where(and2(eq3(usageLedger.userId, userId), sql6`${usageLedger.metadata}->>'reservationId' = ${r.id}`));
+      const billedTotal = Number(usage[0]?.total ?? 0);
+      if (r.chargeOnExpire) {
+        const topUp = Math.max(0, r.amountMicros - billedTotal);
+        if (topUp > 0) {
+          await this.insertVerifiedLedgerDebit(tx, {
+            id: `usage-fallback:${r.id}`,
+            userId,
+            runId: r.runId,
+            amountMicros: topUp,
+            source: "pi-chat-expired",
+            metadata: { kind: "reservation_expired_fallback", reservationId: r.id }
+          });
+        }
+      }
+    }
+    return stale.length;
+  }
+  async computeBalance(executor, userId, now) {
+    const [granted, used, reserved] = await Promise.all([
+      this.sumGrants(executor, userId, now),
+      this.sumUsage(executor, userId),
+      this.sumActiveReservations(executor, userId, now)
+    ]);
+    const remainingMicros = granted - used;
+    return {
+      userId,
+      grantedMicros: granted,
+      usedMicros: used,
+      remainingMicros,
+      activeReservedMicros: reserved,
+      availableMicros: remainingMicros - reserved
+    };
+  }
+  async sumGrants(executor, userId, now) {
+    const rows = await executor.select({ total: sql6`coalesce(sum(${creditGrants.amountMicros}), 0)` }).from(creditGrants).where(and2(eq3(creditGrants.userId, userId), or(isNull2(creditGrants.expiresAt), gt(creditGrants.expiresAt, now))));
+    return toSafeMicros(rows[0]?.total, "grant total");
+  }
+  async sumUsage(executor, userId) {
+    const rows = await executor.select({ total: sql6`coalesce(sum(${usageLedger.billedCostMicros}), 0)` }).from(usageLedger).where(eq3(usageLedger.userId, userId));
+    return toSafeMicros(rows[0]?.total, "usage total");
+  }
+  async sumActiveReservations(executor, userId, now) {
+    const rows = await executor.select({ total: sql6`coalesce(sum(${usageReservations.amountMicros}), 0)` }).from(usageReservations).where(
+      and2(
+        eq3(usageReservations.userId, userId),
+        eq3(usageReservations.status, "active"),
+        gt(usageReservations.expiresAt, now)
+      )
+    );
+    return toSafeMicros(rows[0]?.total, "active reservation total");
+  }
+};
+function toSafeMicros(value, label) {
+  const parsed = BigInt(value ?? "0");
+  if (parsed > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error(`metering ${label} exceeds the safe integer range (${parsed})`);
+  }
+  return Number(parsed);
+}
+function opaqueLedgerId(prefix, raw) {
+  let hash = 2166136261;
+  for (let i = 0; i < raw.length; i += 1) {
+    hash ^= raw.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return `${prefix}_${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+function describeGrant(reason) {
+  if (reason === "signup_grant") return { kind: "grant", description: "Signup grant" };
+  if (reason.startsWith("purchase:")) return { kind: "purchase", description: "Credit purchase" };
+  return { kind: "grant", description: "Credit grant" };
+}
+function describeUsage(source) {
+  if (source === "lemonsqueezy-refund") return { kind: "refund", description: "Refund" };
+  if (source.startsWith("pi-chat-fallback") || source.startsWith("pi-chat-expired")) {
+    return { kind: "fallback", description: "Usage reconciliation" };
+  }
+  return { kind: "usage", description: "Agent usage" };
+}
+
 export {
   users,
   verification_tokens,
@@ -1690,6 +2327,10 @@ export {
   workspaceRuntimes,
   workspaceInvites,
   idempotencyKeys,
+  creditGrants,
+  creditPurchases,
+  usageReservations,
+  usageLedger,
   telemetryEvents,
   schema_exports,
   createDatabase,
@@ -1697,5 +2338,7 @@ export {
   LocalUserStore,
   LocalWorkspaceStore,
   PostgresWorkspaceStore,
-  PostgresUserStore
+  PostgresUserStore,
+  InsufficientCreditError,
+  PostgresMeteringStore
 };