@drm3/sdk 0.1.2

package/dist/meter/sql/statements.js

@@ -0,0 +1,24 @@
+export function buildStatements(greatest) {
+    return {
+        ensureLedger: `INSERT INTO credits_ledger (tenant_id, app, balance, held) VALUES (?, ?, 0, 0)
+       ON CONFLICT (tenant_id, app) DO NOTHING`,
+        fund: "UPDATE credits_ledger SET balance = balance + ? WHERE tenant_id = ? AND app = ?",
+        insertReservation: `INSERT INTO credits_reservation
+         (id, tenant_id, app, held, charged, state, created_at, expires_at, capture_idem_key)
+       VALUES (?, ?, ?, ?, 0, 'held', ?, ?, NULL)`,
+        placeHold: `UPDATE credits_ledger SET held = held + ?
+        WHERE tenant_id = ? AND app = ? AND balance - held >= ?`,
+        dropReservation: "DELETE FROM credits_reservation WHERE id = ? AND state = 'held'",
+        selectByIdem: "SELECT charged FROM credits_reservation WHERE capture_idem_key = ?",
+        captureReservation: `UPDATE credits_reservation SET state = 'captured', charged = ?, capture_idem_key = ?
+        WHERE id = ? AND state = 'held'`,
+        applyLedgerCapture: `UPDATE credits_ledger SET balance = balance - ?, held = ${greatest}(held - ?, 0)
+        WHERE tenant_id = ? AND app = ?`,
+        releaseReservation: "UPDATE credits_reservation SET state = ?, charged = 0 WHERE id = ? AND state = 'held'",
+        releaseLedgerHold: `UPDATE credits_ledger SET held = ${greatest}(held - ?, 0) WHERE tenant_id = ? AND app = ?`,
+        selectBalance: "SELECT balance, held FROM credits_ledger WHERE tenant_id = ? AND app = ?",
+        selectExpired: "SELECT id FROM credits_reservation WHERE state = 'held' AND expires_at <= ?",
+        selectById: "SELECT * FROM credits_reservation WHERE id = ?",
+    };
+}
+//# sourceMappingURL=statements.js.map

package/dist/meter/sql/statements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.js","sourceRoot":"","sources":["../../../src/meter/sql/statements.ts"],"names":[],"mappings":"AA6BA,MAAM,UAAU,eAAe,CAAC,QAA4B;IAC1D,OAAO;QACL,YAAY,EAAE;+CAC6B;QAC3C,IAAI,EAAE,iFAAiF;QACvF,iBAAiB,EAAE;;kDAE2B;QAC9C,SAAS,EAAE;gEACiD;QAC5D,eAAe,EAAE,iEAAiE;QAClF,YAAY,EAAE,oEAAoE;QAClF,kBAAkB,EAAE;wCACgB;QACpC,kBAAkB,EAAE,2DAA2D,QAAQ;wCACnD;QACpC,kBAAkB,EAAE,uFAAuF;QAC3G,iBAAiB,EAAE,oCAAoC,QAAQ,+CAA+C;QAC9G,aAAa,EAAE,0EAA0E;QACzF,aAAa,EAAE,6EAA6E;QAC5F,UAAU,EAAE,gDAAgD;KAC7D,CAAC;AACJ,CAAC"}

package/dist/meter/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Core types. Credits are integer µcredits (base units, bigint) mirroring the
+ * on-chain balance - floats never enter the ledger. Errors are values, never
+ * thrown in the hot path.
+ */
+/** Integer µcredits (base units) - the "wei" of a credit; 1 credit = 10^6 µcredits.
+ *  "credit" is display-only (see units.ts). Always a whole bigint, so balances
+ *  never drift. Always >= 0n in any persisted balance/hold. */
+export type Credits = bigint;
+/** A wallet address (crypto user) or account id (non-crypto user). Opaque. */
+export type Tenant = string;
+/** App scope. The empty string is the GLOBAL bucket. */
+export type App = string;
+export declare const GLOBAL: App;
+export type ReservationState = "held" | "captured" | "voided" | "expired";
+export interface Reservation {
+    id: string;
+    tenant: Tenant;
+    /** The scope the hold draws from after app→global fallback is resolved. */
+    app: App;
+    held: Credits;
+    charged: Credits;
+    state: ReservationState;
+    createdAt: number;
+    expiresAt: number;
+    /** Set on capture; unique, so a retried capture can never double-charge. */
+    captureIdemKey?: string;
+}
+export interface Balance {
+    /** Total credits funded into this scope, minus what's been captured. */
+    balance: Credits;
+    /** Currently reserved by in-flight holds. */
+    held: Credits;
+    /** balance - held. Never negative. What a new request may draw on. */
+    available: Credits;
+}
+/** Typed error values. The hot path returns these instead of throwing. */
+export type MeterErrorCode = "INSUFFICIENT_FUNDS" | "RESERVATION_NOT_FOUND" | "ALREADY_FINALIZED";
+export interface MeterError {
+    ok: false;
+    code: MeterErrorCode;
+    message: string;
+}
+export type Result<T> = ({
+    ok: true;
+} & T) | MeterError;
+export declare const err: (code: MeterErrorCode, message: string) => MeterError;
+//# sourceMappingURL=types.d.ts.map

package/dist/meter/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/meter/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;+DAE+D;AAC/D,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAE7B,8EAA8E;AAC9E,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC;AAE5B,wDAAwD;AACxD,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC;AACzB,eAAO,MAAM,MAAM,EAAE,GAAQ,CAAC;AAE9B,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE1E,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,GAAG,EAAE,GAAG,CAAC;IACT,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,gBAAgB,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,OAAO;IACtB,wEAAwE;IACxE,OAAO,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,IAAI,EAAE,OAAO,CAAC;IACd,sEAAsE;IACtE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,0EAA0E;AAC1E,MAAM,MAAM,cAAc,GAAG,oBAAoB,GAAG,uBAAuB,GAAG,mBAAmB,CAAC;AAElG,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG,CAAC,CAAC,GAAG,UAAU,CAAC;AAExD,eAAO,MAAM,GAAG,GAAI,MAAM,cAAc,EAAE,SAAS,MAAM,KAAG,UAA4C,CAAC"}

package/dist/meter/types.js

@@ -0,0 +1,8 @@
+/**
+ * Core types. Credits are integer µcredits (base units, bigint) mirroring the
+ * on-chain balance - floats never enter the ledger. Errors are values, never
+ * thrown in the hot path.
+ */
+export const GLOBAL = "";
+export const err = (code, message) => ({ ok: false, code, message });
+//# sourceMappingURL=types.js.map

package/dist/meter/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/meter/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,MAAM,CAAC,MAAM,MAAM,GAAQ,EAAE,CAAC;AAsC9B,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,IAAoB,EAAE,OAAe,EAAc,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC"}

package/dist/meter/units.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Credit denomination - two tiers, modeled on ETH/wei but scaled like USDC.
+ *
+ *   credit   ⟷  ETH/USDC  - the denomination humans price and discuss in
+ *   µcredit  ⟷  wei       - the smallest indivisible unit; the ONLY thing stored
+ *
+ * Everything in the system - the off-chain meter ledger AND the on-chain
+ * contract - counts integer µcredits (BASE UNITS). "credit" is a DISPLAY
+ * convention only, exactly like ETH: the chain never stores "ETH", it stores
+ * wei, and a `decimals` value tells a wallet where to put the point. Same here.
+ *
+ * Because the stored unit is the smallest one, no real price is ever below
+ * 1 µcredit, so the ledger only ever adds and subtracts whole integers -
+ * rounding is impossible by construction (no floats anywhere; see PriceBook).
+ *
+ * 1 credit = 10^6 µcredits (6 decimals - DELIBERATELY identical to USDC, so
+ * credit↔USDC settlement is 1:1 integer math, also exact, no rounding). 6 is
+ * fine enough that real prices are whole integers, e.g. 1 credit / 10k tokens
+ * = exactly 100 µcredits/token. uint256 on-chain holds it with vast headroom.
+ *
+ * "µcredit" is a working name for the base unit (ETH's is "wei"); rebrand at
+ * will - it's a display label, it changes no math.
+ */
+/** Decimal places between a µcredit and a credit (USDC uses 6; we match it). */
+export declare const CREDIT_DECIMALS = 6;
+/** Base units in one credit. The scale factor; never a divisor in the hot path. */
+export declare const CREDIT: bigint;
+/** Format integer base units as a human "credit" string (DISPLAY ONLY - pure
+ *  integer math, no float ever touches a balance). e.g. 1_500…0n → "1.5". */
+export declare function formatCredits(baseUnits: bigint, decimals?: number): string;
+/** Parse a decimal "credit" string into exact integer base units (no float). */
+export declare function parseCredits(credits: string): bigint;
+//# sourceMappingURL=units.d.ts.map

package/dist/meter/units.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"units.d.ts","sourceRoot":"","sources":["../../src/meter/units.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,gFAAgF;AAChF,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,mFAAmF;AACnF,eAAO,MAAM,MAAM,QAAiC,CAAC;AAErD;6EAC6E;AAC7E,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAOrE;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKpD"}

package/dist/meter/units.js

@@ -0,0 +1,45 @@
+/**
+ * Credit denomination - two tiers, modeled on ETH/wei but scaled like USDC.
+ *
+ *   credit   ⟷  ETH/USDC  - the denomination humans price and discuss in
+ *   µcredit  ⟷  wei       - the smallest indivisible unit; the ONLY thing stored
+ *
+ * Everything in the system - the off-chain meter ledger AND the on-chain
+ * contract - counts integer µcredits (BASE UNITS). "credit" is a DISPLAY
+ * convention only, exactly like ETH: the chain never stores "ETH", it stores
+ * wei, and a `decimals` value tells a wallet where to put the point. Same here.
+ *
+ * Because the stored unit is the smallest one, no real price is ever below
+ * 1 µcredit, so the ledger only ever adds and subtracts whole integers -
+ * rounding is impossible by construction (no floats anywhere; see PriceBook).
+ *
+ * 1 credit = 10^6 µcredits (6 decimals - DELIBERATELY identical to USDC, so
+ * credit↔USDC settlement is 1:1 integer math, also exact, no rounding). 6 is
+ * fine enough that real prices are whole integers, e.g. 1 credit / 10k tokens
+ * = exactly 100 µcredits/token. uint256 on-chain holds it with vast headroom.
+ *
+ * "µcredit" is a working name for the base unit (ETH's is "wei"); rebrand at
+ * will - it's a display label, it changes no math.
+ */
+/** Decimal places between a µcredit and a credit (USDC uses 6; we match it). */
+export const CREDIT_DECIMALS = 6;
+/** Base units in one credit. The scale factor; never a divisor in the hot path. */
+export const CREDIT = 10n ** BigInt(CREDIT_DECIMALS);
+/** Format integer base units as a human "credit" string (DISPLAY ONLY - pure
+ *  integer math, no float ever touches a balance). e.g. 1_500…0n → "1.5". */
+export function formatCredits(baseUnits, decimals = 4) {
+    const neg = baseUnits < 0n;
+    const v = neg ? -baseUnits : baseUnits;
+    const whole = v / CREDIT;
+    const frac = ((v % CREDIT) * 10n ** BigInt(decimals)) / CREDIT;
+    const fracStr = decimals > 0 ? `.${frac.toString().padStart(decimals, "0")}` : "";
+    return `${neg ? "-" : ""}${whole}${fracStr}`;
+}
+/** Parse a decimal "credit" string into exact integer base units (no float). */
+export function parseCredits(credits) {
+    const [whole, frac = ""] = credits.trim().replace(/^-/, "").split(".");
+    const fracPadded = (frac + "0".repeat(CREDIT_DECIMALS)).slice(0, CREDIT_DECIMALS);
+    const units = BigInt(whole || "0") * CREDIT + BigInt(fracPadded || "0");
+    return credits.trim().startsWith("-") ? -units : units;
+}
+//# sourceMappingURL=units.js.map

package/dist/meter/units.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"units.js","sourceRoot":"","sources":["../../src/meter/units.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,gFAAgF;AAChF,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AAEjC,mFAAmF;AACnF,MAAM,CAAC,MAAM,MAAM,GAAG,GAAG,IAAI,MAAM,CAAC,eAAe,CAAC,CAAC;AAErD;6EAC6E;AAC7E,MAAM,UAAU,aAAa,CAAC,SAAiB,EAAE,QAAQ,GAAG,CAAC;IAC3D,MAAM,GAAG,GAAG,SAAS,GAAG,EAAE,CAAC;IAC3B,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IACvC,MAAM,KAAK,GAAG,CAAC,GAAG,MAAM,CAAC;IACzB,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,GAAG,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC;IAC/D,MAAM,OAAO,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAClF,OAAO,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,GAAG,OAAO,EAAE,CAAC;AAC/C,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,MAAM,CAAC,KAAK,EAAE,IAAI,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACvE,MAAM,UAAU,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;IAClF,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,GAAG,CAAC,GAAG,MAAM,GAAG,MAAM,CAAC,UAAU,IAAI,GAAG,CAAC,CAAC;IACxE,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;AACzD,CAAC"}

package/dist/meter/wallet-buckets.d.ts

@@ -0,0 +1,63 @@
+/**
+ * wallet-buckets - the allowance bucket layer: types, refill, and reads.
+ *
+ * Free functions over a SqlDriver so the Wallet class (wallet.ts) can compose them
+ * without a second copy of the logic. Covers the allowance/DDL/refill/read half;
+ * the cross-bucket charge lives in wallet-charge.ts.
+ */
+import type { SqlDriver } from "./sql/driver.js";
+export type Cadence = "daily" | "weekly" | "monthly" | "none";
+/** Config for one allowance bucket. The purse is implicit (always last, always
+ *  overdraftable) and is never described here. */
+export interface BucketDef {
+    /** Bucket name, unique within a (tenant, scope). e.g. 'daily', 'monthly'. */
+    name: string;
+    /** Refill ceiling in µcredits. */
+    cap: bigint;
+    /** Auto-refill cadence. 'none' = defined but dormant (never auto-refills). */
+    cadence: Cadence;
+    /** Burn order, lowest first. Allowances burn before the purse regardless. */
+    priority: number;
+    /** Optional upstream allocation this bucket is backed by (e.g. 'venice'). */
+    source?: string;
+}
+export interface BucketBalance {
+    name: string;
+    balance: bigint;
+    cap: bigint;
+    cadence: Cadence;
+    priority: number;
+    source: string | null;
+}
+export interface WalletBalance {
+    /** Spendable total: sum of allowance balances (each floored at 0) + purse. The
+     *  purse may be negative (overdraft), pulling the aggregate down. */
+    aggregate: bigint;
+    /** The existing credits_ledger balance for this scope (can be negative). */
+    purse: bigint;
+    /** Allowance buckets, burn order (priority asc). */
+    buckets: BucketBalance[];
+}
+export declare const GLOBAL = "";
+/** Period key for a cadence at a given instant (UTC). Refill fires when the
+ *  stored key differs from the current one. */
+export declare function periodKey(cadence: Cadence, nowMs: number): string;
+/** Idempotent DDL: the allowance buckets + the charge idempotency guard. The
+ *  purse (credits_ledger) is created by the base adapter's init - not here. */
+export declare function init(d: SqlDriver): Promise<void>;
+/** Define / update an allowance bucket's config (cap, cadence, priority). Does
+ *  not change the live balance; the next refill() applies the cap. */
+export declare function setBucket(d: SqlDriver, tenant: string, scope: string, def: BucketDef): Promise<void>;
+/** Refill every allowance whose epoch has rolled to its cap (reset-to-cap, not
+ *  additive). Returns the buckets topped and the total µcredits granted. */
+export declare function refill(d: SqlDriver, now: () => number, tenant: string, scope: string): Promise<{
+    topped: string[];
+    granted: bigint;
+}>;
+/** Read the wallet: aggregate, purse, and per-bucket allowance balances. */
+export declare function balance(d: SqlDriver, tenant: string, scope: string): Promise<WalletBalance>;
+/** Add µcredits to the PURSE (Stripe deposit / admin top-up). The purse is the
+ *  existing ledger; this nets against any overdraft automatically. */
+export declare function deposit(d: SqlDriver, tenant: string, scope: string, ucredits: bigint): Promise<void>;
+export declare function ensurePurse(d: SqlDriver, tenant: string, scope: string): Promise<void>;
+//# sourceMappingURL=wallet-buckets.d.ts.map

package/dist/meter/wallet-buckets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-buckets.d.ts","sourceRoot":"","sources":["../../src/meter/wallet-buckets.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAE9D;kDACkD;AAClD,MAAM,WAAW,SAAS;IACxB,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,OAAO,EAAE,OAAO,CAAC;IACjB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B;yEACqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,eAAO,MAAM,MAAM,KAAK,CAAC;AAEzB;+CAC+C;AAC/C,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAUjE;AAED;+EAC+E;AAC/E,wBAAsB,IAAI,CAAC,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BtD;AAED;sEACsE;AACtE,wBAAsB,SAAS,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB1G;AAED;4EAC4E;AAC5E,wBAAsB,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CA0B3I;AAED,4EAA4E;AAC5E,wBAAsB,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAoBjG;AAED;sEACsE;AACtE,wBAAsB,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK1G;AAED,wBAAsB,WAAW,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5F"}

package/dist/meter/wallet-buckets.js

@@ -0,0 +1,131 @@
+import { toBig } from "./sql/driver.js";
+export const GLOBAL = "";
+/** Period key for a cadence at a given instant (UTC). Refill fires when the
+ *  stored key differs from the current one. */
+export function periodKey(cadence, nowMs) {
+    if (cadence === "none")
+        return "none";
+    const d = new Date(nowMs);
+    const iso = d.toISOString(); // YYYY-MM-DDTHH:MM:SS.sssZ
+    if (cadence === "monthly")
+        return iso.slice(0, 7); // YYYY-MM
+    if (cadence === "daily")
+        return iso.slice(0, 10); // YYYY-MM-DD
+    // weekly: UTC year + zero-based week index (Mon-anchored not needed for a cap reset)
+    const start = Date.UTC(d.getUTCFullYear(), 0, 1);
+    const week = Math.floor((nowMs - start) / (7 * 24 * 3600 * 1000));
+    return `${d.getUTCFullYear()}-W${week}`;
+}
+/** Idempotent DDL: the allowance buckets + the charge idempotency guard. The
+ *  purse (credits_ledger) is created by the base adapter's init - not here. */
+export async function init(d) {
+    const INT = d.dialect === "postgres" ? "BIGINT" : "INTEGER";
+    await d.exec(`CREATE TABLE IF NOT EXISTS credits_allowance (
+       tenant_id   TEXT NOT NULL,
+       scope       TEXT NOT NULL,
+       bucket      TEXT NOT NULL,
+       balance     ${INT} NOT NULL DEFAULT 0,
+       cap         ${INT} NOT NULL DEFAULT 0,
+       cadence     TEXT NOT NULL DEFAULT 'none',
+       priority    ${INT} NOT NULL DEFAULT 100,
+       source      TEXT,
+       period      TEXT,
+       refilled_at ${INT},
+       PRIMARY KEY (tenant_id, scope, bucket)
+     )`);
+    await d.exec(`CREATE TABLE IF NOT EXISTS wallet_txn (
+       idem_key   TEXT PRIMARY KEY,
+       tenant_id  TEXT NOT NULL,
+       scope      TEXT NOT NULL,
+       charged    ${INT} NOT NULL,
+       at         ${INT} NOT NULL
+     )`);
+}
+/** Define / update an allowance bucket's config (cap, cadence, priority). Does
+ *  not change the live balance; the next refill() applies the cap. */
+export async function setBucket(d, tenant, scope, def) {
+    const s = scope || GLOBAL;
+    const existing = await d.all("SELECT bucket FROM credits_allowance WHERE tenant_id=? AND scope=? AND bucket=?", [tenant, s, def.name]);
+    if (existing.length) {
+        await d.run("UPDATE credits_allowance SET cap=?, cadence=?, priority=?, source=? WHERE tenant_id=? AND scope=? AND bucket=?", [
+            def.cap,
+            def.cadence,
+            def.priority,
+            def.source ?? null,
+            tenant,
+            s,
+            def.name,
+        ]);
+    }
+    else {
+        await d.run("INSERT INTO credits_allowance (tenant_id, scope, bucket, balance, cap, cadence, priority, source) VALUES (?,?,?,0,?,?,?,?)", [
+            tenant,
+            s,
+            def.name,
+            def.cap,
+            def.cadence,
+            def.priority,
+            def.source ?? null,
+        ]);
+    }
+}
+/** Refill every allowance whose epoch has rolled to its cap (reset-to-cap, not
+ *  additive). Returns the buckets topped and the total µcredits granted. */
+export async function refill(d, now, tenant, scope) {
+    const s = scope || GLOBAL;
+    const nowMs = now();
+    const rows = await d.all("SELECT bucket, cap, cadence, period FROM credits_allowance WHERE tenant_id=? AND scope=?", [tenant, s]);
+    const topped = [];
+    let granted = 0n;
+    for (const r of rows) {
+        if (r.cadence === "none")
+            continue;
+        const key = periodKey(r.cadence, nowMs);
+        if (r.period === key)
+            continue; // already refilled this epoch
+        const cap = toBig(r.cap);
+        await d.run("UPDATE credits_allowance SET balance=?, period=?, refilled_at=? WHERE tenant_id=? AND scope=? AND bucket=?", [
+            cap,
+            key,
+            nowMs,
+            tenant,
+            s,
+            r.bucket,
+        ]);
+        topped.push(r.bucket);
+        granted += cap;
+    }
+    return { topped, granted };
+}
+/** Read the wallet: aggregate, purse, and per-bucket allowance balances. */
+export async function balance(d, tenant, scope) {
+    const s = scope || GLOBAL;
+    const [purseRows, allowRows] = await Promise.all([
+        d.all("SELECT balance FROM credits_ledger WHERE tenant_id=? AND app=?", [tenant, s]),
+        d.all("SELECT bucket, balance, cap, cadence, priority, source FROM credits_allowance WHERE tenant_id=? AND scope=? ORDER BY priority ASC", [tenant, s]),
+    ]);
+    const purse = purseRows.length ? toBig(purseRows[0]?.balance) : 0n;
+    const buckets = allowRows.map((r) => ({
+        name: r.bucket,
+        balance: toBig(r.balance),
+        cap: toBig(r.cap),
+        cadence: r.cadence,
+        priority: Number(toBig(r.priority)),
+        source: r.source,
+    }));
+    const allowSum = buckets.reduce((acc, b) => acc + (b.balance > 0n ? b.balance : 0n), 0n);
+    return { aggregate: allowSum + purse, purse, buckets };
+}
+/** Add µcredits to the PURSE (Stripe deposit / admin top-up). The purse is the
+ *  existing ledger; this nets against any overdraft automatically. */
+export async function deposit(d, tenant, scope, ucredits) {
+    if (ucredits <= 0n)
+        return;
+    const s = scope || GLOBAL;
+    await ensurePurse(d, tenant, s);
+    await d.run("UPDATE credits_ledger SET balance = balance + ? WHERE tenant_id=? AND app=?", [ucredits, tenant, s]);
+}
+export async function ensurePurse(d, tenant, scope) {
+    await d.run("INSERT INTO credits_ledger (tenant_id, app, balance, held) VALUES (?,?,0,0) ON CONFLICT (tenant_id, app) DO NOTHING", [tenant, scope]);
+}
+//# sourceMappingURL=wallet-buckets.js.map

package/dist/meter/wallet-buckets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-buckets.js","sourceRoot":"","sources":["../../src/meter/wallet-buckets.ts"],"names":[],"mappings":"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"}

package/dist/meter/wallet-charge.d.ts

@@ -0,0 +1,15 @@
+import type { SqlDriver } from "./sql/driver.js";
+export interface ChargeResult {
+    /** Total µcredits actually applied (equals the request unless a replay -> 0n). */
+    charged: bigint;
+    /** Per-bucket breakdown, e.g. {daily: 30n, purse: 70n}. For the audit log. */
+    byBucket: Record<string, bigint>;
+    /** True when this idemKey was already charged (replay): nothing was applied. */
+    replay: boolean;
+}
+/** Charge across buckets in burn order: allowances by priority (floored at 0),
+ *  then the purse, which OVERDRAFTS for any remainder (goes negative). Idempotent
+ *  on idemKey across the whole charge. Never throws on funds - recording, not
+ *  gating (the admission gate is the caller's job, off available()). */
+export declare function charge(d: SqlDriver, now: () => number, tenant: string, scope: string, ucredits: bigint, idemKey?: string): Promise<ChargeResult>;
+//# sourceMappingURL=wallet-charge.d.ts.map

package/dist/meter/wallet-charge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-charge.d.ts","sourceRoot":"","sources":["../../src/meter/wallet-charge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAUjD,MAAM,WAAW,YAAY;IAC3B,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,gFAAgF;IAChF,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;wEAGwE;AACxE,wBAAsB,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAqDtJ"}

package/dist/meter/wallet-charge.js

@@ -0,0 +1,64 @@
+import { toBig } from "./sql/driver.js";
+/**
+ * wallet-charge - the cross-bucket charge (allowances first, purse overdrafts).
+ *
+ * Idempotent on `idemKey` across the WHOLE charge (allowance burns AND the purse
+ * overdraft) via a `wallet_txn` guard row, so a retried drain charges once.
+ */
+import { GLOBAL, ensurePurse } from "./wallet-buckets.js";
+/** Charge across buckets in burn order: allowances by priority (floored at 0),
+ *  then the purse, which OVERDRAFTS for any remainder (goes negative). Idempotent
+ *  on idemKey across the whole charge. Never throws on funds - recording, not
+ *  gating (the admission gate is the caller's job, off available()). */
+export async function charge(d, now, tenant, scope, ucredits, idemKey) {
+    const byBucket = {};
+    if (ucredits <= 0n)
+        return { charged: 0n, byBucket, replay: false };
+    const s = scope || GLOBAL;
+    // Whole-charge idempotency guard: a retried drain (same idemKey) records once.
+    if (idemKey) {
+        const nowMs = now();
+        const guard = await d.run("INSERT INTO wallet_txn (idem_key, tenant_id, scope, charged, at) VALUES (?,?,?,?,?) ON CONFLICT (idem_key) DO NOTHING", [
+            idemKey,
+            tenant,
+            s,
+            ucredits,
+            nowMs,
+        ]);
+        if (guard.rowsAffected === 0)
+            return { charged: 0n, byBucket, replay: true };
+    }
+    let remaining = ucredits;
+    // Allowances first, lowest priority number first. Conditional UPDATE floors at
+    // zero and the row count says how much it actually took (the row-lock pattern).
+    const allows = await d.all("SELECT bucket, balance FROM credits_allowance WHERE tenant_id=? AND scope=? AND balance > 0 ORDER BY priority ASC", [tenant, s]);
+    for (const a of allows) {
+        if (remaining <= 0n)
+            break;
+        const have = toBig(a.balance);
+        const take = have < remaining ? have : remaining;
+        if (take <= 0n)
+            continue;
+        // Guard on balance>=take so a concurrent burn can't drive it negative.
+        const res = await d.run("UPDATE credits_allowance SET balance = balance - ? WHERE tenant_id=? AND scope=? AND bucket=? AND balance >= ?", [
+            take,
+            tenant,
+            s,
+            a.bucket,
+            take,
+        ]);
+        if (res.rowsAffected > 0) {
+            byBucket[a.bucket] = (byBucket[a.bucket] ?? 0n) + take;
+            remaining -= take;
+        }
+    }
+    // Remainder hits the purse, which overdrafts (no floor - goes negative).
+    if (remaining > 0n) {
+        await ensurePurse(d, tenant, s);
+        await d.run("UPDATE credits_ledger SET balance = balance - ? WHERE tenant_id=? AND app=?", [remaining, tenant, s]);
+        byBucket.purse = (byBucket.purse ?? 0n) + remaining;
+        remaining = 0n;
+    }
+    return { charged: ucredits, byBucket, replay: false };
+}
+//# sourceMappingURL=wallet-charge.js.map

package/dist/meter/wallet-charge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-charge.js","sourceRoot":"","sources":["../../src/meter/wallet-charge.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC;;;;;GAKG;AACH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAW1D;;;wEAGwE;AACxE,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,CAAY,EAAE,GAAiB,EAAE,MAAc,EAAE,KAAa,EAAE,QAAgB,EAAE,OAAgB;IAC7H,MAAM,QAAQ,GAA2B,EAAE,CAAC;IAC5C,IAAI,QAAQ,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACpE,MAAM,CAAC,GAAG,KAAK,IAAI,MAAM,CAAC;IAE1B,+EAA+E;IAC/E,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC;QACpB,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,uHAAuH,EAAE;YACjJ,OAAO;YACP,MAAM;YACN,CAAC;YACD,QAAQ;YACR,KAAK;SACN,CAAC,CAAC;QACH,IAAI,KAAK,CAAC,YAAY,KAAK,CAAC;YAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC/E,CAAC;IAED,IAAI,SAAS,GAAG,QAAQ,CAAC;IACzB,+EAA+E;IAC/E,gFAAgF;IAChF,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,GAAG,CACxB,mHAAmH,EACnH,CAAC,MAAM,EAAE,CAAC,CAAC,CACZ,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,SAAS,IAAI,EAAE;YAAE,MAAM;QAC3B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAC9B,MAAM,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QACjD,IAAI,IAAI,IAAI,EAAE;YAAE,SAAS;QACzB,uEAAuE;QACvE,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,gHAAgH,EAAE;YACxI,IAAI;YACJ,MAAM;YACN,CAAC;YACD,CAAC,CAAC,MAAM;YACR,IAAI;SACL,CAAC,CAAC;QACH,IAAI,GAAG,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;YACzB,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;YACvD,SAAS,IAAI,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,IAAI,SAAS,GAAG,EAAE,EAAE,CAAC;QACnB,MAAM,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;QAChC,MAAM,CAAC,CAAC,GAAG,CAAC,6EAA6E,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;QACnH,QAAQ,CAAC,KAAK,GAAG,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC;QACpD,SAAS,GAAG,EAAE,CAAC;IACjB,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AACxD,CAAC"}

package/dist/meter/wallet.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Wallet - the multi-bucket layer over the single-balance ledger.
+ *
+ * A wallet is several BUCKETS drawn in a fixed BURN ORDER and presented as one
+ * aggregate. Two kinds:
+ *
+ *   - ALLOWANCES (daily / weekly / monthly): grants that refill to a cap each
+ *     epoch (reset-to-cap, NOT additive), floor at zero (you can't owe back a
+ *     grant), and are ALWAYS BURNED FIRST. New `credits_allowance` table.
+ *   - PURSE: the existing `credits_ledger` balance. Persists, burned LAST, and
+ *     the ONLY bucket that can overdraft (go negative) - the model the queue
+ *     already ships. Untouched here; the wallet just draws it last.
+ *
+ * Burn order is `priority` ascending across allowances, then the purse. So the
+ * canonical order daily -> monthly -> purse is priorities 10, 20, (purse) with
+ * weekly slotting at 15 when activated. Cadences are config: a bucket with
+ * `cadence:'none'` exists but never auto-refills, so daily/weekly can sit dormant
+ * in the schema until flipped on - no re-plumb.
+ *
+ * Idempotent on `idemKey` across the WHOLE charge (allowance burns AND the purse
+ * overdraft) via a `wallet_txn` guard row, so a retried drain charges once. This
+ * is purely additive: existing CreditsClient consumers are unaffected.
+ *
+ * This file is the barrel: the class stitches together wallet-buckets.ts (config,
+ * refill, reads) and wallet-charge.ts (the cross-bucket charge), and re-exports the
+ * full public API.
+ */
+import type { SqlDriver } from "./sql/driver.js";
+export type { Cadence, BucketDef, BucketBalance, WalletBalance } from "./wallet-buckets.js";
+export type { ChargeResult } from "./wallet-charge.js";
+import type { WalletBalance } from "./wallet-buckets.js";
+import type { BucketDef } from "./wallet-buckets.js";
+import type { ChargeResult } from "./wallet-charge.js";
+export interface WalletOptions {
+    /** Injectable clock (epoch ms). Defaults to Date.now. */
+    now?: () => number;
+}
+export declare class Wallet {
+    private readonly d;
+    private readonly now;
+    constructor(driver: SqlDriver, opts?: WalletOptions);
+    /** Idempotent DDL: the allowance buckets + the charge idempotency guard. The
+     *  purse (credits_ledger) is created by the base adapter's init - not here. */
+    init(): Promise<void>;
+    /** Define / update an allowance bucket's config (cap, cadence, priority). Does
+     *  not change the live balance; the next refill() applies the cap. */
+    setBucket(tenant: string, scope: string, def: BucketDef): Promise<void>;
+    /** Refill every allowance whose epoch has rolled to its cap (reset-to-cap, not
+     *  additive). Returns the buckets topped and the total µcredits granted. */
+    refill(tenant: string, scope: string): Promise<{
+        topped: string[];
+        granted: bigint;
+    }>;
+    /** Read the wallet: aggregate, purse, and per-bucket allowance balances. */
+    balance(tenant: string, scope: string): Promise<WalletBalance>;
+    /** Spendable now, for the admission gate: allowance balances (floored) + purse.
+     *  Same number as balance().aggregate, one query path. */
+    available(tenant: string, scope: string): Promise<bigint>;
+    /** Add µcredits to the PURSE (Stripe deposit / admin top-up). The purse is the
+     *  existing ledger; this nets against any overdraft automatically. */
+    deposit(tenant: string, scope: string, ucredits: bigint): Promise<void>;
+    /** Charge across buckets in burn order: allowances by priority (floored at 0),
+     *  then the purse, which OVERDRAFTS for any remainder (goes negative). Idempotent
+     *  on idemKey across the whole charge. Never throws on funds - recording, not
+     *  gating (the admission gate is the caller's job, off available()). */
+    charge(tenant: string, scope: string, ucredits: bigint, idemKey?: string): Promise<ChargeResult>;
+}
+//# sourceMappingURL=wallet.d.ts.map

package/dist/meter/wallet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet.d.ts","sourceRoot":"","sources":["../../src/meter/wallet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC5F,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAY;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,MAAM,EAAE,SAAS,EAAE,IAAI,GAAE,aAAkB;IAKvD;mFAC+E;IACzE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;0EACsE;IAChE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7E;gFAC4E;IACtE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAI3F,4EAA4E;IACtE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAIpE;8DAC0D;IACpD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI/D;0EACsE;IAChE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7E;;;4EAGwE;IAClE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAGvG"}

package/dist/meter/wallet.js

@@ -0,0 +1,47 @@
+import * as buckets from "./wallet-buckets.js";
+import * as chargeMod from "./wallet-charge.js";
+export class Wallet {
+    d;
+    now;
+    constructor(driver, opts = {}) {
+        this.d = driver;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /** Idempotent DDL: the allowance buckets + the charge idempotency guard. The
+     *  purse (credits_ledger) is created by the base adapter's init - not here. */
+    async init() {
+        return buckets.init(this.d);
+    }
+    /** Define / update an allowance bucket's config (cap, cadence, priority). Does
+     *  not change the live balance; the next refill() applies the cap. */
+    async setBucket(tenant, scope, def) {
+        return buckets.setBucket(this.d, tenant, scope, def);
+    }
+    /** Refill every allowance whose epoch has rolled to its cap (reset-to-cap, not
+     *  additive). Returns the buckets topped and the total µcredits granted. */
+    async refill(tenant, scope) {
+        return buckets.refill(this.d, this.now, tenant, scope);
+    }
+    /** Read the wallet: aggregate, purse, and per-bucket allowance balances. */
+    async balance(tenant, scope) {
+        return buckets.balance(this.d, tenant, scope);
+    }
+    /** Spendable now, for the admission gate: allowance balances (floored) + purse.
+     *  Same number as balance().aggregate, one query path. */
+    async available(tenant, scope) {
+        return (await this.balance(tenant, scope)).aggregate;
+    }
+    /** Add µcredits to the PURSE (Stripe deposit / admin top-up). The purse is the
+     *  existing ledger; this nets against any overdraft automatically. */
+    async deposit(tenant, scope, ucredits) {
+        return buckets.deposit(this.d, tenant, scope, ucredits);
+    }
+    /** Charge across buckets in burn order: allowances by priority (floored at 0),
+     *  then the purse, which OVERDRAFTS for any remainder (goes negative). Idempotent
+     *  on idemKey across the whole charge. Never throws on funds - recording, not
+     *  gating (the admission gate is the caller's job, off available()). */
+    async charge(tenant, scope, ucredits, idemKey) {
+        return chargeMod.charge(this.d, this.now, tenant, scope, ucredits, idemKey);
+    }
+}
+//# sourceMappingURL=wallet.js.map

package/dist/meter/wallet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet.js","sourceRoot":"","sources":["../../src/meter/wallet.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAC;AAC/C,OAAO,KAAK,SAAS,MAAM,oBAAoB,CAAC;AAahD,MAAM,OAAO,MAAM;IACA,CAAC,CAAY;IACb,GAAG,CAAe;IAEnC,YAAY,MAAiB,EAAE,OAAsB,EAAE;QACrD,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC;QAChB,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED;mFAC+E;IAC/E,KAAK,CAAC,IAAI;QACR,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;IAED;0EACsE;IACtE,KAAK,CAAC,SAAS,CAAC,MAAc,EAAE,KAAa,EAAE,GAAc;QAC3D,OAAO,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;IACvD,CAAC;IAED;gFAC4E;IAC5E,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,KAAa;QACxC,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IACzD,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,OAAO,CAAC,MAAc,EAAE,KAAa;QACzC,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAChD,CAAC;IAED;8DAC0D;IAC1D,KAAK,CAAC,SAAS,CAAC,MAAc,EAAE,KAAa;QAC3C,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACvD,CAAC;IAED;0EACsE;IACtE,KAAK,CAAC,OAAO,CAAC,MAAc,EAAE,KAAa,EAAE,QAAgB;QAC3D,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC1D,CAAC;IAED;;;4EAGwE;IACxE,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,KAAa,EAAE,QAAgB,EAAE,OAAgB;QAC5E,OAAO,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9E,CAAC;CACF"}

package/dist/receipts-api.d.ts

@@ -0,0 +1,5 @@
+import type { Receipt, ViewerConfig } from "./receipts-types.js";
+export declare function openReceiptModal(chain: Receipt[], cfg?: ViewerConfig): Promise<void>;
+export declare function openReceiptById(id: string, cfg?: ViewerConfig): Promise<void>;
+export declare function mountVerifyButton(target: HTMLElement | null, source: Receipt[] | Receipt | string | (() => Receipt[] | Receipt | string | Promise<Receipt[] | Receipt | string>), cfg?: ViewerConfig): void;
+//# sourceMappingURL=receipts-api.d.ts.map

package/dist/receipts-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipts-api.d.ts","sourceRoot":"","sources":["../src/receipts-api.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAajE,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,GAAE,YAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBrG;AAID,wBAAsB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,GAAE,YAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiC9F;AAID,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,WAAW,GAAG,IAAI,EAC1B,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,GAAG,MAAM,GAAG,CAAC,MAAM,OAAO,EAAE,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,OAAO,GAAG,MAAM,CAAC,CAAC,EACnH,GAAG,GAAE,YAAiB,GACrB,IAAI,CAcN"}