@resvary/sdk 0.6.1 → 0.8.0

package/dist/credits/ledger.js

@@ -1,7 +1,7 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { creditUnitsToString, parseCreditUnits, toCreditUnits } from './amount.js';
-import { CreditNotFoundError, IdempotencyConflictError, InsufficientCreditsError, InvalidCreditStateError, } from './errors.js';
-import { InMemoryCreditStore } from './store.js';
+import { CreditNotFoundError, IdempotencyConflictError, InsufficientCreditsError, InvalidCreditStateError, UnsupportedCreditStoreCapabilityError, } from './errors.js';
+import { InMemoryCreditStore, isCreditPolicyStore, } from './store.js';
 import { createMeterDefinition, createPriceVersion, rateUsage } from '../pricing/rating.js';
 export class CreditLedger {
     projectId;
@@ -21,47 +21,218 @@ export class CreditLedger {
         const request = { customerId: input.customerId, metadata: input.metadata };
         return this.store.transaction((tx) => this.idempotent(tx, 'ensure_account', input.idempotencyKey, request, async () => this.ensureAccountInTransaction(tx, input.customerId, input.metadata)));
     }
-    async grantCredits(input) {
+    async createGrantPolicy(input) {
+        const store = this.requirePolicyStore();
         const amountUnits = toCreditUnits(input.amount);
         if (amountUnits <= 0n)
-            throw new Error('Credit grant amount must be positive');
+            throw new Error('Grant policy amount must be positive');
+        if (input.type === 'promotion') {
+            if (!Number.isSafeInteger(input.expiresInMs) || input.expiresInMs <= 0) {
+                throw new Error('Promotion expiresInMs must be a positive integer');
+            }
+        }
+        else if (!['day', 'week', 'month'].includes(input.cadence)) {
+            throw new Error('Allowance cadence must be day, week, or month');
+        }
         const request = { ...input, amountUnits: amountUnits.toString() };
-        return this.store.transaction((tx) => this.idempotent(tx, 'grant_credits', input.idempotencyKey, request, async () => {
+        return store.transaction((tx) => this.idempotent(tx, 'create_grant_policy', input.idempotencyKey, request, async () => {
+            const key = requireText(input.key, 'key');
+            const policies = (await tx.listGrantPolicies(this.projectId)).filter((policy) => policy.key === key);
+            const version = Math.max(0, ...policies.map((policy) => policy.version)) + 1;
+            const base = {
+                id: createId('gpol'),
+                projectId: this.projectId,
+                key,
+                version,
+                type: input.type,
+                amount: creditUnitsToString(amountUnits),
+                amountUnits: amountUnits.toString(),
+                createdAt: this.now(),
+                metadata: input.metadata,
+            };
+            const policy = input.type === 'allowance'
+                ? {
+                    ...base,
+                    type: 'allowance',
+                    cadence: input.cadence,
+                }
+                : {
+                    ...base,
+                    type: 'promotion',
+                    expiresInMs: input.expiresInMs,
+                };
+            await tx.saveGrantPolicy(policy);
+            await this.saveOutboxEvent(tx, 'credit.policy.created', { policy }, policy.createdAt);
+            return policy;
+        }));
+    }
+    async applyAllowance(input) {
+        const store = this.requirePolicyStore();
+        return store.transaction((tx) => this.idempotent(tx, 'apply_allowance', input.idempotencyKey, input, async () => {
             const now = this.now();
+            const policy = await this.requireGrantPolicy(tx, input.policyId, 'allowance');
+            await this.expireDueCreditLots(tx, now, input.customerId);
             const current = await this.ensureAccountInTransaction(tx, input.customerId, input.metadata);
-            const grant = {
-                id: createId('grant'),
-                accountId: current.id,
+            const periodKey = allowancePeriodKey(now, policy.cadence);
+            const existing = await tx.getGrantPolicyApplicationByIdentity(policy.id, current.id, periodKey);
+            if (existing) {
+                const account = await this.requireAccountById(tx, current.id);
+                return {
+                    policy,
+                    application: existing,
+                    account,
+                    grant: existing.grantId ? await tx.getGrant(existing.grantId) : undefined,
+                };
+            }
+            const lots = await tx.listCreditLots({
                 projectId: this.projectId,
                 customerId: current.customerId,
-                amount: creditUnitsToString(amountUnits),
-                amountUnits: amountUnits.toString(),
-                source: input.source ?? 'manual',
-                externalRef: input.externalRef,
+                policyId: policy.id,
+                kind: 'allowance',
+            });
+            const unspentUnits = lots.reduce((total, lot) => total + parseCreditUnits(lot.availableUnits) + parseCreditUnits(lot.reservedUnits), 0n);
+            const targetUnits = parseCreditUnits(policy.amountUnits);
+            const topUpUnits = targetUnits > unspentUnits ? targetUnits - unspentUnits : 0n;
+            let account = current;
+            let grant;
+            if (topUpUnits > 0n) {
+                const created = await this.createGrantInTransaction(tx, {
+                    customerId: current.customerId,
+                    amountUnits: topUpUnits,
+                    source: 'allowance',
+                    policyId: policy.id,
+                    lotKind: 'allowance',
+                    now,
+                    metadata: input.metadata,
+                });
+                account = created.account;
+                grant = created.grant;
+            }
+            const application = {
+                id: createId('gpa'),
+                policyId: policy.id,
+                policyType: 'allowance',
+                accountId: account.id,
+                projectId: this.projectId,
+                customerId: account.customerId,
+                periodKey,
+                grantId: grant?.id,
+                grantedAmount: creditUnitsToString(topUpUnits),
+                grantedUnits: topUpUnits.toString(),
                 createdAt: now,
                 metadata: input.metadata,
             };
-            const account = withBalances(current, parseCreditUnits(current.postedUnits) + amountUnits, parseCreditUnits(current.reservedUnits), now);
-            await tx.saveGrant(grant);
-            await tx.saveAccount(account);
-            await this.saveLedgerEntry(tx, account, 'grant', 'posted', amountUnits, 'grant', grant.id, now, input.metadata);
-            await this.saveOutboxEvent(tx, 'credit.granted', { account, grant }, now);
-            return { account, grant };
+            await tx.saveGrantPolicyApplication(application);
+            await this.saveOutboxEvent(tx, 'credit.allowance.applied', { policy, application, account, grant }, now);
+            return { policy, application, account, grant };
+        }));
+    }
+    async claimPromotion(input) {
+        const store = this.requirePolicyStore();
+        return store.transaction((tx) => this.idempotent(tx, 'claim_promotion', input.idempotencyKey, input, async () => {
+            const now = this.now();
+            const policy = await this.requireGrantPolicy(tx, input.policyId, 'promotion');
+            await this.expireDueCreditLots(tx, now, input.customerId);
+            const current = await this.ensureAccountInTransaction(tx, input.customerId, input.metadata);
+            const periodKey = 'claim';
+            const existing = await tx.getGrantPolicyApplicationByIdentity(policy.id, current.id, periodKey);
+            if (existing) {
+                const account = await this.requireAccountById(tx, current.id);
+                return {
+                    policy,
+                    application: existing,
+                    account,
+                    grant: existing.grantId ? await tx.getGrant(existing.grantId) : undefined,
+                };
+            }
+            const expiresAt = now + policy.expiresInMs;
+            if (!Number.isSafeInteger(expiresAt)) {
+                throw new Error('Promotion expiry exceeds the supported timestamp range');
+            }
+            const created = await this.createGrantInTransaction(tx, {
+                customerId: current.customerId,
+                amountUnits: parseCreditUnits(policy.amountUnits),
+                source: 'promotion',
+                policyId: policy.id,
+                expiresAt,
+                lotKind: 'promotion',
+                now,
+                metadata: input.metadata,
+            });
+            const application = {
+                id: createId('gpa'),
+                policyId: policy.id,
+                policyType: 'promotion',
+                accountId: created.account.id,
+                projectId: this.projectId,
+                customerId: created.account.customerId,
+                periodKey,
+                grantId: created.grant.id,
+                grantedAmount: created.grant.amount,
+                grantedUnits: created.grant.amountUnits,
+                createdAt: now,
+                metadata: input.metadata,
+            };
+            await tx.saveGrantPolicyApplication(application);
+            await this.saveOutboxEvent(tx, 'credit.promotion.claimed', { policy, application, account: created.account, grant: created.grant }, now);
+            return { policy, application, account: created.account, grant: created.grant };
         }));
     }
+    async sweepExpiredCreditLots(input = {}) {
+        const store = this.requirePolicyStore();
+        const limit = input.limit ?? 100;
+        if (!Number.isSafeInteger(limit) || limit <= 0) {
+            throw new Error('Credit lot sweep limit must be a positive integer');
+        }
+        const before = input.before ?? this.now();
+        if (!Number.isSafeInteger(before))
+            throw new Error('Credit lot sweep before must be an integer');
+        return store.transaction((tx) => this.expireDueCreditLots(tx, before, input.customerId, limit));
+    }
+    async grantCredits(input) {
+        const amountUnits = toCreditUnits(input.amount);
+        if (amountUnits <= 0n)
+            throw new Error('Credit grant amount must be positive');
+        const request = { ...input, amountUnits: amountUnits.toString() };
+        return this.withStoreTransaction((tx) => this.idempotent(tx, 'grant_credits', input.idempotencyKey, request, () => this.createGrantInTransaction(tx, {
+            customerId: input.customerId,
+            amountUnits,
+            source: input.source ?? 'manual',
+            externalRef: input.externalRef,
+            lotKind: 'general',
+            now: this.now(),
+            metadata: input.metadata,
+        })));
+    }
     async adjustCredits(input) {
         const deltaUnits = toSignedCreditUnits(input.amount);
         if (deltaUnits === 0n)
             throw new Error('Credit adjustment amount cannot be zero');
         const request = { ...input, deltaUnits: deltaUnits.toString() };
-        return this.store.transaction((tx) => this.idempotent(tx, 'adjust_credits', input.idempotencyKey, request, async () => {
+        return this.withStoreTransaction((tx) => this.idempotent(tx, 'adjust_credits', input.idempotencyKey, request, async () => {
             const now = this.now();
+            if (isPolicyTransaction(tx))
+                await this.expireDueCreditLots(tx, now, input.customerId);
             const current = await this.ensureAccountInTransaction(tx, input.customerId, input.metadata);
             const nextPosted = parseCreditUnits(current.postedUnits) + deltaUnits;
             const reserved = parseCreditUnits(current.reservedUnits);
             if (nextPosted < reserved) {
                 throw new InsufficientCreditsError((nextPosted - reserved).toString(), '0');
             }
+            if (isPolicyTransaction(tx)) {
+                if (deltaUnits > 0n) {
+                    await tx.saveCreditLot(createCreditLot({
+                        account: current,
+                        kind: 'general',
+                        amountUnits: deltaUnits,
+                        now,
+                        metadata: { ...input.metadata, reason: input.reason },
+                    }));
+                }
+                else {
+                    await this.consumeAvailableLots(tx, current, -deltaUnits, now);
+                }
+            }
             const account = withBalances(current, nextPosted, reserved, now);
             await tx.saveAccount(account);
             const entry = await this.saveLedgerEntry(tx, account, 'adjustment', 'posted', deltaUnits, 'adjustment', createId('adj'), now, {
@@ -100,15 +271,21 @@ export class CreditLedger {
             if (!meter)
                 throw new CreditNotFoundError('Meter', input.meterKey);
             const versions = await tx.listPriceVersions(meter.id);
-            const price = createPriceVersion({
+            const base = {
                 id: createId('price'),
                 projectId: this.projectId,
                 meter,
                 version: versions.reduce((max, item) => Math.max(max, item.version), 0) + 1,
-                rates: input.rates,
                 createdAt: this.now(),
                 metadata: input.metadata,
-            });
+            };
+            const price = 'components' in input
+                ? createPriceVersion({
+                    ...base,
+                    rates: input.rates,
+                    components: input.components,
+                })
+                : createPriceVersion({ ...base, rates: input.rates });
             await tx.savePriceVersion(price);
             return price;
         }));
@@ -149,7 +326,7 @@ export class CreditLedger {
         const amountUnits = toCreditUnits(input.amount);
         const rail = input.rail ?? 'arc_direct';
         const externalPaymentId = requireText(input.externalPaymentId ?? input.txHash ?? '', 'externalPaymentId');
-        return this.store.transaction(async (tx) => {
+        return this.withStoreTransaction(async (tx) => {
             const intent = await tx.getFundingIntent(input.fundingIntentId);
             if (!intent || intent.projectId !== this.projectId)
                 throw new CreditNotFoundError('Funding intent', input.fundingIntentId);
@@ -189,6 +366,8 @@ export class CreditLedger {
                         : `Funding underpayment: ${amountUnits} < ${intent.requestedUnits}`);
                 }
                 const now = this.now();
+                if (isPolicyTransaction(tx))
+                    await this.expireDueCreditLots(tx, now, intent.customerId);
                 const current = await this.requireAccountById(tx, intent.accountId);
                 const grant = {
                     id: createId('grant'),
@@ -237,6 +416,16 @@ export class CreditLedger {
                     metadata: input.metadata,
                 };
                 await tx.saveGrant(grant);
+                if (isPolicyTransaction(tx)) {
+                    await tx.saveCreditLot(createCreditLot({
+                        account: current,
+                        kind: 'general',
+                        amountUnits,
+                        grantId: grant.id,
+                        now,
+                        metadata: grant.metadata,
+                    }));
+                }
                 await tx.saveAccount(account);
                 await tx.saveFundingIntent(confirmedIntent);
                 await tx.saveFundingTransaction(fundingTransaction);
@@ -299,9 +488,11 @@ export class CreditLedger {
         }));
     }
     async reserveCredits(input) {
-        return this.store.transaction((tx) => this.idempotent(tx, 'reserve_credits', input.idempotencyKey, input, async () => {
+        return this.withStoreTransaction((tx) => this.idempotent(tx, 'reserve_credits', input.idempotencyKey, input, async () => {
             const now = this.now();
             await this.expireOpenReservations(tx, now, input.customerId);
+            if (isPolicyTransaction(tx))
+                await this.expireDueCreditLots(tx, now, input.customerId);
             const price = await this.requirePrice(tx, input.priceId);
             const rating = rateUsage(price, input.estimatedUsage);
             const reservedUnits = parseCreditUnits(rating.totalUnits);
@@ -330,6 +521,9 @@ export class CreditLedger {
             };
             const account = withBalances(current, parseCreditUnits(current.postedUnits), parseCreditUnits(current.reservedUnits) + reservedUnits, now);
             await tx.saveReservation(reservation);
+            if (isPolicyTransaction(tx)) {
+                await this.reserveCreditLots(tx, current, reservation.id, reservedUnits, now);
+            }
             await tx.saveAccount(account);
             await this.saveLedgerEntry(tx, account, 'reserve', 'reserved', reservedUnits, 'reservation', reservation.id, now, input.metadata);
             await this.saveOutboxEvent(tx, 'credit.reserved', { account, reservation }, now);
@@ -337,7 +531,7 @@ export class CreditLedger {
         }));
     }
     async commitUsage(input) {
-        return this.store.transaction((tx) => this.idempotent(tx, 'commit_usage', input.idempotencyKey, input, async () => {
+        return this.withStoreTransaction((tx) => this.idempotent(tx, 'commit_usage', input.idempotencyKey, input, async () => {
             const now = this.now();
             const reservation = await this.requireReservation(tx, input.reservationId);
             if (reservation.status === 'committed' && reservation.usageReceiptId) {
@@ -364,10 +558,16 @@ export class CreditLedger {
             if (chargeUnits > reservedUnits) {
                 throw new InvalidCreditStateError(`Actual charge exceeds reservation: ${rating.totalUnits} > ${reservation.reservedUnits}`);
             }
+            if (isPolicyTransaction(tx)) {
+                await this.expireDueCreditLots(tx, now, reservation.customerId);
+            }
             const accountBefore = await this.requireAccountById(tx, reservation.accountId);
             const postedBefore = parseCreditUnits(accountBefore.postedUnits);
             const reservedBefore = parseCreditUnits(accountBefore.reservedUnits);
-            const account = withBalances(accountBefore, postedBefore - chargeUnits, reservedBefore - reservedUnits, now);
+            const lotResult = isPolicyTransaction(tx)
+                ? await this.commitCreditLotAllocations(tx, reservation, chargeUnits, now)
+                : { allocations: undefined, expiredReleasedUnits: 0n, expiredLots: [] };
+            const account = withBalances(accountBefore, postedBefore - chargeUnits - lotResult.expiredReleasedUnits, reservedBefore - reservedUnits, now);
             const releasedUnits = reservedUnits - chargeUnits;
             const usageEvent = {
                 id: requireText(input.usageEventId, 'usageEventId'),
@@ -398,6 +598,7 @@ export class CreditLedger {
                 balanceBeforeUnits: accountBefore.availableUnits,
                 balanceAfterUnits: account.availableUnits,
                 createdAt: now,
+                allocations: lotResult.allocations,
                 metadata: input.metadata,
             };
             const committedReservation = {
@@ -416,6 +617,10 @@ export class CreditLedger {
             await tx.saveAccount(account);
             await this.saveLedgerEntry(tx, account, 'charge', 'posted', -chargeUnits, 'usage_receipt', receipt.id, now, input.metadata);
             await this.saveLedgerEntry(tx, account, 'release', 'reserved', -reservedUnits, 'usage_receipt', receipt.id, now, input.metadata);
+            for (const expired of lotResult.expiredLots) {
+                await this.saveLedgerEntry(tx, account, 'expire', 'posted', -expired.units, 'credit_lot', expired.lot.id, now, { reason: 'released_after_expiry', reservationId: reservation.id });
+                await this.saveOutboxEvent(tx, 'credit.lot.expired', { account, lot: expired.lot, expiredUnits: expired.units.toString() }, now);
+            }
             await this.saveOutboxEvent(tx, 'usage.charged', {
                 usageReceiptId: receipt.id,
                 accountId: account.id,
@@ -425,12 +630,13 @@ export class CreditLedger {
                 amountUnits: receipt.amountUnits,
                 releasedAmount: receipt.releasedAmount,
                 balanceAfterUnits: receipt.balanceAfterUnits,
+                allocations: receipt.allocations,
             }, now);
             return { receipt, reservation: committedReservation, balance: account };
         }));
     }
     async releaseReservation(input) {
-        return this.store.transaction((tx) => this.idempotent(tx, 'release_reservation', input.idempotencyKey, input, async () => {
+        return this.withStoreTransaction((tx) => this.idempotent(tx, 'release_reservation', input.idempotencyKey, input, async () => {
             const reservation = await this.requireReservation(tx, input.reservationId);
             if (reservation.status === 'released' || reservation.status === 'expired') {
                 return { reservation, balance: await this.requireAccountById(tx, reservation.accountId) };
@@ -442,7 +648,7 @@ export class CreditLedger {
         }));
     }
     async releaseExpiredReservations(input) {
-        return this.store.transaction((tx) => this.idempotent(tx, 'release_expired', input.idempotencyKey, input, async () => this.expireOpenReservations(tx, input.now ?? this.now())));
+        return this.withStoreTransaction((tx) => this.idempotent(tx, 'release_expired', input.idempotencyKey, input, async () => this.expireOpenReservations(tx, input.now ?? this.now())));
     }
     async runMetered(input, callback) {
         const reserved = await this.reserveCredits(input);
@@ -479,11 +685,59 @@ export class CreditLedger {
         return { value: result.value, replayed: false, ...committed };
     }
     async getBalance(customerId) {
+        if (isCreditPolicyStore(this.store)) {
+            return this.store.transaction(async (tx) => {
+                const normalized = requireText(customerId, 'customerId');
+                await this.expireDueCreditLots(tx, this.now(), normalized);
+                const account = await tx.getAccountByCustomer(this.projectId, normalized);
+                if (!account)
+                    throw new CreditNotFoundError('Credit account', customerId);
+                return account;
+            });
+        }
         const account = await this.store.getAccountByCustomer(this.projectId, requireText(customerId, 'customerId'));
         if (!account)
             throw new CreditNotFoundError('Credit account', customerId);
         return account;
     }
+    async getGrantPolicy(id) {
+        return this.forCurrentProject(await this.requirePolicyStore().getGrantPolicy(id));
+    }
+    listGrantPolicies() {
+        return this.requirePolicyStore().listGrantPolicies(this.projectId);
+    }
+    async getCreditLot(id) {
+        const store = this.requirePolicyStore();
+        const value = this.forCurrentProject(await store.getCreditLot(id));
+        if (!value)
+            return undefined;
+        await this.getBalance(value.customerId);
+        return this.forCurrentProject(await store.getCreditLot(id));
+    }
+    async listCreditLots(filter = {}) {
+        const store = this.requirePolicyStore();
+        const normalized = typeof filter === 'string' ? { customerId: filter } : filter;
+        if (normalized.customerId)
+            await this.getBalance(normalized.customerId);
+        else {
+            await store.transaction((tx) => this.expireDueCreditLots(tx, this.now(), undefined, Number.MAX_SAFE_INTEGER));
+        }
+        return store.listCreditLots({ ...normalized, projectId: this.projectId });
+    }
+    async listGrantPolicyApplications(filter = {}) {
+        const store = this.requirePolicyStore();
+        const normalized = typeof filter === 'string' ? { customerId: filter } : filter;
+        if (normalized.customerId)
+            await this.getBalance(normalized.customerId);
+        return store.listGrantPolicyApplications({ ...normalized, projectId: this.projectId });
+    }
+    async getGrantPolicyApplication(id) {
+        return this.forCurrentProject(await this.requirePolicyStore().getGrantPolicyApplication(id));
+    }
+    async listCreditLotAllocations(reservationId) {
+        const allocations = await this.requirePolicyStore().listCreditLotAllocations(reservationId);
+        return this.forCurrentProjectList(allocations);
+    }
     async getReservation(id) {
         return this.forCurrentProject(await this.store.getReservation(id));
     }
@@ -535,6 +789,209 @@ export class CreditLedger {
             return delivered;
         }));
     }
+    withStoreTransaction(handler) {
+        if (isCreditPolicyStore(this.store))
+            return this.store.transaction(handler);
+        return this.store.transaction(handler);
+    }
+    requirePolicyStore() {
+        if (!isCreditPolicyStore(this.store))
+            throw new UnsupportedCreditStoreCapabilityError();
+        return this.store;
+    }
+    async requireGrantPolicy(tx, id, type) {
+        const policy = await tx.getGrantPolicy(id);
+        if (!policy || policy.projectId !== this.projectId) {
+            throw new CreditNotFoundError('Grant policy', id);
+        }
+        if (policy.type !== type) {
+            throw new InvalidCreditStateError(`Grant policy ${policy.id} is ${policy.type}, not ${type}`);
+        }
+        return policy;
+    }
+    async createGrantInTransaction(tx, input) {
+        if (input.amountUnits <= 0n)
+            throw new Error('Credit grant amount must be positive');
+        if (isPolicyTransaction(tx)) {
+            await this.expireDueCreditLots(tx, input.now, input.customerId);
+        }
+        const current = await this.ensureAccountInTransaction(tx, input.customerId, input.metadata);
+        const grant = {
+            id: createId('grant'),
+            accountId: current.id,
+            projectId: this.projectId,
+            customerId: current.customerId,
+            amount: creditUnitsToString(input.amountUnits),
+            amountUnits: input.amountUnits.toString(),
+            source: input.source,
+            externalRef: input.externalRef,
+            policyId: input.policyId,
+            expiresAt: input.expiresAt,
+            createdAt: input.now,
+            metadata: input.metadata,
+        };
+        const account = withBalances(current, parseCreditUnits(current.postedUnits) + input.amountUnits, parseCreditUnits(current.reservedUnits), input.now);
+        await tx.saveGrant(grant);
+        if (isPolicyTransaction(tx)) {
+            await tx.saveCreditLot(createCreditLot({
+                account: current,
+                kind: input.lotKind,
+                amountUnits: input.amountUnits,
+                grantId: grant.id,
+                policyId: input.policyId,
+                expiresAt: input.expiresAt,
+                now: input.now,
+                metadata: input.metadata,
+            }));
+        }
+        await tx.saveAccount(account);
+        await this.saveLedgerEntry(tx, account, 'grant', 'posted', input.amountUnits, 'grant', grant.id, input.now, input.metadata);
+        await this.saveOutboxEvent(tx, 'credit.granted', { account, grant }, input.now);
+        return { account, grant };
+    }
+    async expireDueCreditLots(tx, before, customerId, limit = Number.MAX_SAFE_INTEGER) {
+        const due = (await tx.listCreditLots({
+            projectId: this.projectId,
+            customerId,
+            expiresBefore: before,
+        }))
+            .filter((lot) => parseCreditUnits(lot.availableUnits) > 0n)
+            .sort(compareCreditLots)
+            .slice(0, limit);
+        const accounts = new Map();
+        const lots = [];
+        for (const lot of due) {
+            const availableUnits = parseCreditUnits(lot.availableUnits);
+            if (availableUnits === 0n)
+                continue;
+            const accountBefore = accounts.get(lot.accountId) ?? (await this.requireAccountById(tx, lot.accountId));
+            const account = withBalances(accountBefore, parseCreditUnits(accountBefore.postedUnits) - availableUnits, parseCreditUnits(accountBefore.reservedUnits), before);
+            const expired = withCreditLotBalances(lot, 0n, parseCreditUnits(lot.reservedUnits), parseCreditUnits(lot.consumedUnits), parseCreditUnits(lot.expiredUnits) + availableUnits, before);
+            await tx.saveCreditLot(expired);
+            await tx.saveAccount(account);
+            await this.saveLedgerEntry(tx, account, 'expire', 'posted', -availableUnits, 'credit_lot', lot.id, before, { reason: 'lot_expired' });
+            await this.saveOutboxEvent(tx, 'credit.lot.expired', { account, lot: expired, expiredUnits: availableUnits.toString() }, before);
+            accounts.set(account.id, account);
+            lots.push(expired);
+        }
+        return { lots, accounts: [...accounts.values()] };
+    }
+    async reserveCreditLots(tx, account, reservationId, amountUnits, now) {
+        let remaining = amountUnits;
+        const lots = (await tx.listCreditLots({
+            projectId: this.projectId,
+            customerId: account.customerId,
+        }))
+            .filter((lot) => lot.accountId === account.id &&
+            parseCreditUnits(lot.availableUnits) > 0n &&
+            (lot.expiresAt === undefined || lot.expiresAt > now))
+            .sort(compareCreditLots);
+        const allocations = [];
+        for (const lot of lots) {
+            if (remaining === 0n)
+                break;
+            const available = parseCreditUnits(lot.availableUnits);
+            const allocated = available < remaining ? available : remaining;
+            const updatedLot = withCreditLotBalances(lot, available - allocated, parseCreditUnits(lot.reservedUnits) + allocated, parseCreditUnits(lot.consumedUnits), parseCreditUnits(lot.expiredUnits), now);
+            const allocation = createCreditLotAllocation({
+                reservationId,
+                lot,
+                amountUnits: allocated,
+                now,
+            });
+            await tx.saveCreditLot(updatedLot);
+            await tx.saveCreditLotAllocation(allocation);
+            allocations.push(allocation);
+            remaining -= allocated;
+        }
+        if (remaining !== 0n) {
+            throw new InvalidCreditStateError(`Credit lot balance is missing ${remaining.toString()} units for account ${account.id}`);
+        }
+        return allocations;
+    }
+    async commitCreditLotAllocations(tx, reservation, chargeUnits, now) {
+        const allocations = await tx.listCreditLotAllocations(reservation.id);
+        const allocatedTotal = allocations.reduce((total, allocation) => total + parseCreditUnits(allocation.reservedUnits), 0n);
+        if (allocatedTotal !== parseCreditUnits(reservation.reservedUnits)) {
+            throw new InvalidCreditStateError(`Reservation lot allocations are incomplete: ${reservation.id}`);
+        }
+        let remainingCharge = chargeUnits;
+        let expiredReleasedUnits = 0n;
+        const updated = [];
+        const expiredLots = [];
+        const allocationLots = await Promise.all(allocations.map(async (allocation) => {
+            const lot = await tx.getCreditLot(allocation.lotId);
+            if (!lot)
+                throw new CreditNotFoundError('Credit lot', allocation.lotId);
+            return { allocation, lot };
+        }));
+        allocationLots.sort((left, right) => compareCreditLots(left.lot, right.lot));
+        for (const { allocation, lot } of allocationLots) {
+            const reserved = parseCreditUnits(allocation.reservedUnits);
+            const consumed = reserved < remainingCharge ? reserved : remainingCharge;
+            const remainder = reserved - consumed;
+            const expired = lot.expiresAt !== undefined && lot.expiresAt <= now;
+            const updatedLot = withCreditLotBalances(lot, parseCreditUnits(lot.availableUnits) + (expired ? 0n : remainder), parseCreditUnits(lot.reservedUnits) - reserved, parseCreditUnits(lot.consumedUnits) + consumed, parseCreditUnits(lot.expiredUnits) + (expired ? remainder : 0n), now);
+            const updatedAllocation = withCreditLotAllocationBalances(allocation, 0n, parseCreditUnits(allocation.consumedUnits) + consumed, parseCreditUnits(allocation.releasedUnits) + (expired ? 0n : remainder), parseCreditUnits(allocation.expiredUnits) + (expired ? remainder : 0n), now);
+            await tx.saveCreditLot(updatedLot);
+            await tx.saveCreditLotAllocation(updatedAllocation);
+            updated.push(updatedAllocation);
+            remainingCharge -= consumed;
+            if (expired && remainder > 0n) {
+                expiredReleasedUnits += remainder;
+                expiredLots.push({ lot: updatedLot, units: remainder });
+            }
+        }
+        if (remainingCharge !== 0n) {
+            throw new InvalidCreditStateError(`Reservation cannot cover charge: ${reservation.id}`);
+        }
+        return { allocations: updated, expiredReleasedUnits, expiredLots };
+    }
+    async releaseCreditLotAllocations(tx, reservation, now) {
+        const allocations = await tx.listCreditLotAllocations(reservation.id);
+        const allocatedTotal = allocations.reduce((total, allocation) => total + parseCreditUnits(allocation.reservedUnits), 0n);
+        if (allocatedTotal !== parseCreditUnits(reservation.reservedUnits)) {
+            throw new InvalidCreditStateError(`Reservation lot allocations are incomplete: ${reservation.id}`);
+        }
+        let expiredReleasedUnits = 0n;
+        const expiredLots = [];
+        for (const allocation of allocations) {
+            const lot = await tx.getCreditLot(allocation.lotId);
+            if (!lot)
+                throw new CreditNotFoundError('Credit lot', allocation.lotId);
+            const reserved = parseCreditUnits(allocation.reservedUnits);
+            const expired = lot.expiresAt !== undefined && lot.expiresAt <= now;
+            const updatedLot = withCreditLotBalances(lot, parseCreditUnits(lot.availableUnits) + (expired ? 0n : reserved), parseCreditUnits(lot.reservedUnits) - reserved, parseCreditUnits(lot.consumedUnits), parseCreditUnits(lot.expiredUnits) + (expired ? reserved : 0n), now);
+            const updatedAllocation = withCreditLotAllocationBalances(allocation, 0n, parseCreditUnits(allocation.consumedUnits), parseCreditUnits(allocation.releasedUnits) + (expired ? 0n : reserved), parseCreditUnits(allocation.expiredUnits) + (expired ? reserved : 0n), now);
+            await tx.saveCreditLot(updatedLot);
+            await tx.saveCreditLotAllocation(updatedAllocation);
+            if (expired && reserved > 0n) {
+                expiredReleasedUnits += reserved;
+                expiredLots.push({ lot: updatedLot, units: reserved });
+            }
+        }
+        return { expiredReleasedUnits, expiredLots };
+    }
+    async consumeAvailableLots(tx, account, amountUnits, now) {
+        let remaining = amountUnits;
+        const lots = (await tx.listCreditLots({
+            projectId: this.projectId,
+            customerId: account.customerId,
+        }))
+            .filter((lot) => lot.accountId === account.id && parseCreditUnits(lot.availableUnits) > 0n)
+            .sort(compareCreditLots);
+        for (const lot of lots) {
+            if (remaining === 0n)
+                break;
+            const available = parseCreditUnits(lot.availableUnits);
+            const consumed = available < remaining ? available : remaining;
+            await tx.saveCreditLot(withCreditLotBalances(lot, available - consumed, parseCreditUnits(lot.reservedUnits), parseCreditUnits(lot.consumedUnits) + consumed, parseCreditUnits(lot.expiredUnits), now));
+            remaining -= consumed;
+        }
+        if (remaining !== 0n) {
+            throw new InvalidCreditStateError(`Credit lot balance is missing ${remaining.toString()} units for account ${account.id}`);
+        }
+    }
     async ensureAccountInTransaction(tx, customerIdValue, metadata) {
         const customerId = requireText(customerIdValue, 'customerId');
         const existing = await tx.getAccountByCustomer(this.projectId, customerId);
@@ -576,9 +1033,15 @@ export class CreditLedger {
         return this.closeReservation(tx, reservation, 'expired', now, 'ttl_expired');
     }
     async closeReservation(tx, reservation, status, now, reason) {
+        if (isPolicyTransaction(tx)) {
+            await this.expireDueCreditLots(tx, now, reservation.customerId);
+        }
         const accountBefore = await this.requireAccountById(tx, reservation.accountId);
         const reservedUnits = parseCreditUnits(reservation.reservedUnits);
-        const account = withBalances(accountBefore, parseCreditUnits(accountBefore.postedUnits), parseCreditUnits(accountBefore.reservedUnits) - reservedUnits, now);
+        const lotResult = isPolicyTransaction(tx)
+            ? await this.releaseCreditLotAllocations(tx, reservation, now)
+            : { expiredReleasedUnits: 0n, expiredLots: [] };
+        const account = withBalances(accountBefore, parseCreditUnits(accountBefore.postedUnits) - lotResult.expiredReleasedUnits, parseCreditUnits(accountBefore.reservedUnits) - reservedUnits, now);
         const closed = {
             ...reservation,
             status,
@@ -589,6 +1052,10 @@ export class CreditLedger {
         await tx.saveReservation(closed);
         await tx.saveAccount(account);
         await this.saveLedgerEntry(tx, account, 'release', 'reserved', -reservedUnits, 'reservation', reservation.id, now, { reason });
+        for (const expired of lotResult.expiredLots) {
+            await this.saveLedgerEntry(tx, account, 'expire', 'posted', -expired.units, 'credit_lot', expired.lot.id, now, { reason: 'released_after_expiry', reservationId: reservation.id });
+            await this.saveOutboxEvent(tx, 'credit.lot.expired', { account, lot: expired.lot, expiredUnits: expired.units.toString() }, now);
+        }
         await this.saveOutboxEvent(tx, status === 'expired' ? 'credit.expired' : 'credit.released', { account, reservation: closed, reason }, now);
         return { reservation: closed, balance: account };
     }
@@ -689,6 +1156,160 @@ function withBalances(account, posted, reserved, updatedAt) {
         updatedAt,
     };
 }
+function isPolicyTransaction(transaction) {
+    const value = transaction;
+    return (typeof value.getGrantPolicy === 'function' &&
+        typeof value.listGrantPolicies === 'function' &&
+        typeof value.getCreditLot === 'function' &&
+        typeof value.listCreditLots === 'function' &&
+        typeof value.listCreditLotAllocations === 'function' &&
+        typeof value.getGrantPolicyApplicationByIdentity === 'function' &&
+        typeof value.saveGrantPolicy === 'function' &&
+        typeof value.saveCreditLot === 'function' &&
+        typeof value.saveCreditLotAllocation === 'function' &&
+        typeof value.saveGrantPolicyApplication === 'function');
+}
+function createCreditLot(input) {
+    if (input.amountUnits <= 0n) {
+        throw new InvalidCreditStateError('Credit lot amount must be positive');
+    }
+    if (input.expiresAt !== undefined && input.expiresAt <= input.now) {
+        throw new InvalidCreditStateError('Credit lot expiry must be in the future');
+    }
+    const amount = creditUnitsToString(input.amountUnits);
+    return {
+        id: createId('lot'),
+        accountId: input.account.id,
+        projectId: input.account.projectId,
+        customerId: input.account.customerId,
+        kind: input.kind,
+        grantId: input.grantId,
+        policyId: input.policyId,
+        originalAmount: amount,
+        originalUnits: input.amountUnits.toString(),
+        availableAmount: amount,
+        availableUnits: input.amountUnits.toString(),
+        reservedAmount: '0',
+        reservedUnits: '0',
+        consumedAmount: '0',
+        consumedUnits: '0',
+        expiredAmount: '0',
+        expiredUnits: '0',
+        createdAt: input.now,
+        updatedAt: input.now,
+        expiresAt: input.expiresAt,
+        metadata: input.metadata,
+    };
+}
+function withCreditLotBalances(lot, available, reserved, consumed, expired, updatedAt) {
+    if (available < 0n || reserved < 0n || consumed < 0n || expired < 0n) {
+        throw new InvalidCreditStateError(`Credit lot balance cannot be negative: ${lot.id}`);
+    }
+    const original = parseCreditUnits(lot.originalUnits);
+    if (available + reserved + consumed + expired !== original) {
+        throw new InvalidCreditStateError(`Credit lot invariant violated: ${lot.id}`);
+    }
+    return {
+        ...lot,
+        availableAmount: creditUnitsToString(available),
+        availableUnits: available.toString(),
+        reservedAmount: creditUnitsToString(reserved),
+        reservedUnits: reserved.toString(),
+        consumedAmount: creditUnitsToString(consumed),
+        consumedUnits: consumed.toString(),
+        expiredAmount: creditUnitsToString(expired),
+        expiredUnits: expired.toString(),
+        updatedAt,
+    };
+}
+function createCreditLotAllocation(input) {
+    if (input.amountUnits <= 0n) {
+        throw new InvalidCreditStateError('Credit lot allocation amount must be positive');
+    }
+    const amount = creditUnitsToString(input.amountUnits);
+    return {
+        id: `cla_${createHash('sha256')
+            .update(`${input.reservationId}\u0000${input.lot.id}`)
+            .digest('hex')
+            .slice(0, 24)}`,
+        reservationId: input.reservationId,
+        lotId: input.lot.id,
+        accountId: input.lot.accountId,
+        projectId: input.lot.projectId,
+        customerId: input.lot.customerId,
+        allocatedAmount: amount,
+        allocatedUnits: input.amountUnits.toString(),
+        reservedAmount: amount,
+        reservedUnits: input.amountUnits.toString(),
+        consumedAmount: '0',
+        consumedUnits: '0',
+        releasedAmount: '0',
+        releasedUnits: '0',
+        expiredAmount: '0',
+        expiredUnits: '0',
+        createdAt: input.now,
+        updatedAt: input.now,
+    };
+}
+function withCreditLotAllocationBalances(allocation, reserved, consumed, released, expired, updatedAt) {
+    if (reserved < 0n || consumed < 0n || released < 0n || expired < 0n) {
+        throw new InvalidCreditStateError(`Credit lot allocation balance cannot be negative: ${allocation.id}`);
+    }
+    const allocated = parseCreditUnits(allocation.allocatedUnits);
+    if (reserved + consumed + released + expired !== allocated) {
+        throw new InvalidCreditStateError(`Credit lot allocation invariant violated: ${allocation.id}`);
+    }
+    return {
+        ...allocation,
+        reservedAmount: creditUnitsToString(reserved),
+        reservedUnits: reserved.toString(),
+        consumedAmount: creditUnitsToString(consumed),
+        consumedUnits: consumed.toString(),
+        releasedAmount: creditUnitsToString(released),
+        releasedUnits: released.toString(),
+        expiredAmount: creditUnitsToString(expired),
+        expiredUnits: expired.toString(),
+        updatedAt,
+    };
+}
+function compareCreditLots(left, right) {
+    const priority = (lot) => {
+        if (lot.kind === 'promotion')
+            return 0;
+        if (lot.kind === 'allowance')
+            return 1;
+        return 2;
+    };
+    const priorityDifference = priority(left) - priority(right);
+    if (priorityDifference !== 0)
+        return priorityDifference;
+    if (left.kind === 'promotion' && right.kind === 'promotion') {
+        const expiryDifference = (left.expiresAt ?? Number.MAX_SAFE_INTEGER) - (right.expiresAt ?? Number.MAX_SAFE_INTEGER);
+        if (expiryDifference !== 0)
+            return expiryDifference;
+    }
+    return left.createdAt - right.createdAt || left.id.localeCompare(right.id);
+}
+function allowancePeriodKey(timestamp, cadence) {
+    if (!Number.isSafeInteger(timestamp))
+        throw new Error('Clock must return an integer timestamp');
+    const date = new Date(timestamp);
+    if (Number.isNaN(date.getTime()))
+        throw new Error('Clock returned an invalid timestamp');
+    const day = date.toISOString().slice(0, 10);
+    if (cadence === 'day')
+        return `day:${day}`;
+    if (cadence === 'month')
+        return `month:${day.slice(0, 7)}`;
+    if (cadence === 'week') {
+        const utcDay = date.getUTCDay();
+        const daysSinceMonday = (utcDay + 6) % 7;
+        const monday = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+        monday.setUTCDate(monday.getUTCDate() - daysSinceMonday);
+        return `week:${monday.toISOString().slice(0, 10)}`;
+    }
+    throw new Error(`Unsupported allowance cadence: ${String(cadence)}`);
+}
 function normalizeUsage(usage) {
     return Object.fromEntries(Object.entries(usage).sort(([a], [b]) => a.localeCompare(b)));
 }