mcp-usage-control 1.0.0

package/dist/index.js

@@ -0,0 +1,2131 @@
+import { randomUUID } from 'node:crypto';
+import { emitUsageEvent, usageErrorName, } from './observability.js';
+export * from './observability.js';
+export * from './weighted-credits.js';
+export * from './windowed-budget-keys.js';
+export const USAGE_INPUT_LIMITS = Object.freeze({
+    identifierBytes: 1024,
+    scalarBudgets: 64,
+    vectorDimensions: 32,
+    vectorBudgetsPerDimension: 32,
+    vectorBudgetsTotal: 128,
+});
+export function assertUsageIdentifier(value, name) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new RangeError(`${name} must be a non-empty string`);
+    }
+    if (new TextEncoder().encode(value).byteLength > USAGE_INPUT_LIMITS.identifierBytes) {
+        throw new RangeError(`${name} exceeds the ${USAGE_INPUT_LIMITS.identifierBytes}-byte input limit`);
+    }
+}
+export function validateUsageRequestEnvelope(request) {
+    if (request === null || typeof request !== 'object' || Array.isArray(request)) {
+        throw new RangeError('request must be an object');
+    }
+    if (request.principal === null || typeof request.principal !== 'object' || Array.isArray(request.principal)) {
+        throw new RangeError('principal must be an object');
+    }
+    assertUsageIdentifier(request.operationId, 'operationId');
+    assertUsageIdentifier(request.principal.id, 'principal.id');
+    assertUsageIdentifier(request.tool, 'tool');
+    if (request.principal.tenantId !== undefined) {
+        assertUsageIdentifier(request.principal.tenantId, 'principal.tenantId');
+    }
+    if (request.principal.plan !== undefined) {
+        assertUsageIdentifier(request.principal.plan, 'principal.plan');
+    }
+}
+export function validateUsageBudgetEnvelope(budgets) {
+    if (!Array.isArray(budgets))
+        throw new TypeError('budgets must be an array');
+    if (budgets.length === 0)
+        throw new RangeError('budgets must contain at least one budget');
+    if (budgets.length > USAGE_INPUT_LIMITS.scalarBudgets) {
+        throw new RangeError(`budgets exceed the ${USAGE_INPUT_LIMITS.scalarBudgets}-budget input limit`);
+    }
+    for (const budget of budgets) {
+        if (budget === null || typeof budget !== 'object' || Array.isArray(budget)) {
+            throw new TypeError('budget must be an object');
+        }
+        assertUsageIdentifier(budget.key, 'budget.key');
+    }
+}
+export function validateUsageVectorEnvelope(dimensions) {
+    if (!Array.isArray(dimensions))
+        throw new TypeError('dimensions must be an array');
+    if (dimensions.length === 0)
+        throw new RangeError('dimensions must contain at least one dimension');
+    if (dimensions.length > USAGE_INPUT_LIMITS.vectorDimensions) {
+        throw new RangeError(`dimensions exceed the ${USAGE_INPUT_LIMITS.vectorDimensions}-dimension input limit`);
+    }
+    let totalBudgets = 0;
+    for (const dimension of dimensions) {
+        if (dimension === null || typeof dimension !== 'object' || Array.isArray(dimension)) {
+            throw new TypeError('dimension must be an object');
+        }
+        assertUsageIdentifier(dimension.key, 'dimension.key');
+        if (!Array.isArray(dimension.budgets) || dimension.budgets.length === 0) {
+            throw new RangeError('dimension.budgets must contain at least one budget');
+        }
+        if (dimension.budgets.length > USAGE_INPUT_LIMITS.vectorBudgetsPerDimension) {
+            throw new RangeError(`dimension budgets exceed the ${USAGE_INPUT_LIMITS.vectorBudgetsPerDimension}-budget input limit`);
+        }
+        totalBudgets += dimension.budgets.length;
+        if (totalBudgets > USAGE_INPUT_LIMITS.vectorBudgetsTotal) {
+            throw new RangeError(`vector topology exceeds the ${USAGE_INPUT_LIMITS.vectorBudgetsTotal}-budget input limit`);
+        }
+        validateUsageBudgetEnvelope(dimension.budgets);
+    }
+}
+export function validateUsageVectorGrowthEnvelope(dimensions) {
+    validateUsageVectorEnvelope(dimensions.map(dimension => ({
+        key: dimension.key,
+        units: dimension.additionalUnits,
+        budgets: dimension.budgets,
+    })));
+}
+export class UsageStateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UsageStateError';
+    }
+}
+export class UsageDeniedError extends Error {
+    reason;
+    constructor(reason) {
+        super('Usage denied by usage policy');
+        this.reason = reason;
+        this.name = 'UsageDeniedError';
+    }
+}
+export class UsageLease {
+    store;
+    reservation;
+    ttlMs;
+    observer;
+    metadata;
+    unresolvedGrowth;
+    constructor(store, reservation, ttlMs, observer, metadata, unresolvedGrowth) {
+        this.store = store;
+        this.reservation = reservation;
+        this.ttlMs = ttlMs;
+        this.observer = observer;
+        this.metadata = metadata;
+        this.unresolvedGrowth =
+            unresolvedGrowth === undefined ? undefined : canonicalizeGrowthRequest(unresolvedGrowth);
+    }
+    get reservedUnits() {
+        return this.reservation.reservedUnits;
+    }
+    /** Export a detached snapshot for trusted server-side suspend/resume workflows. */
+    toResumeState() {
+        return {
+            reservation: cloneReservationRecord(this.reservation),
+            ttlMs: this.ttlMs,
+            ...(this.metadata === undefined ? {} : { metadata: { ...this.metadata } }),
+            ...(this.unresolvedGrowth === undefined
+                ? {}
+                : { unresolvedGrowth: cloneGrowthRequest(this.unresolvedGrowth) }),
+        };
+    }
+    /**
+     * Increase capacity on the same logical reservation.
+     *
+     * A thrown Store/provider error is ambiguous. After one, this lease permits only an exact
+     * retry of the same increment until an authoritative accepted/denied result is returned.
+     */
+    async grow(input) {
+        const request = canonicalizeGrowthRequest(input);
+        if (this.unresolvedGrowth && !sameGrowthRequest(this.unresolvedGrowth, request)) {
+            throw new UsageStateError('A reservation growth attempt is unresolved; retry the same incrementId and parameters');
+        }
+        if (!isProgressiveUsageStore(this.store)) {
+            throw new UsageStateError('UsageStore does not support progressive reservation growth');
+        }
+        const expectedGrowthCursor = this.reservation.growthCursor;
+        if (!expectedGrowthCursor) {
+            throw new UsageStateError('Reservation was not created with progressive growth support');
+        }
+        this.unresolvedGrowth = request;
+        try {
+            const result = validateStoreGrowthResult(await this.store.growReservation({
+                reservationId: this.reservation.id,
+                incrementId: request.incrementId,
+                expectedGrowthCursor,
+                additionalUnits: request.additionalUnits,
+                budgets: request.budgets,
+            }), this.reservation, request);
+            this.reservation.growthCursor = result.growthCursor;
+            if (result.accepted)
+                this.reservation.reservedUnits = result.reservedUnits;
+            this.unresolvedGrowth = undefined;
+            return result;
+        }
+        catch (error) {
+            if (error instanceof UsageStateError) {
+                // Built-in Stores use UsageStateError only for authoritative state rejection.
+                // Transport/provider ambiguity keeps the attempt pinned for exact retry.
+                this.unresolvedGrowth = undefined;
+            }
+            throw error;
+        }
+    }
+    async markLiable() {
+        try {
+            const marked = await this.store.markLiable({ reservationId: this.reservation.id });
+            this.reservation.expiresAt = marked.expiresAt;
+            return marked;
+        }
+        catch (error) {
+            emitUsageEvent(this.observer, {
+                type: 'operation.error',
+                timestamp: Date.now(),
+                phase: 'mark_liable',
+                source: 'store',
+                reservationId: this.reservation.id,
+                ...reservationIdentity(this.reservation),
+                errorName: usageErrorName(error),
+                ...(this.metadata === undefined ? {} : { metadata: this.metadata }),
+            });
+            throw error;
+        }
+    }
+    async renew(ttlMs = this.ttlMs) {
+        assertPositiveInteger(ttlMs, 'ttlMs');
+        try {
+            const renewed = await this.store.renew({ reservationId: this.reservation.id, ttlMs });
+            this.reservation.expiresAt = renewed.expiresAt;
+            return renewed;
+        }
+        catch (error) {
+            emitUsageEvent(this.observer, {
+                type: 'operation.error',
+                timestamp: Date.now(),
+                phase: 'renew',
+                source: 'store',
+                reservationId: this.reservation.id,
+                ...reservationIdentity(this.reservation),
+                errorName: usageErrorName(error),
+                ...(this.metadata === undefined ? {} : { metadata: this.metadata }),
+            });
+            throw error;
+        }
+    }
+    async settle(actualUnits, outcome) {
+        try {
+            const settlement = await this.store.settle({
+                reservationId: this.reservation.id,
+                actualUnits,
+                outcome,
+            });
+            emitUsageEvent(this.observer, {
+                type: 'settlement.completed',
+                timestamp: Date.now(),
+                reservationId: this.reservation.id,
+                ...reservationIdentity(this.reservation),
+                budgetKeys: [...this.reservation.budgetKeys],
+                reservedUnits: settlement.reservedUnits,
+                actualUnits: settlement.actualUnits,
+                releasedUnits: settlement.releasedUnits,
+                outcome: settlement.outcome,
+                ...(this.metadata === undefined ? {} : { metadata: this.metadata }),
+            });
+            return settlement;
+        }
+        catch (error) {
+            emitUsageEvent(this.observer, {
+                type: 'operation.error',
+                timestamp: Date.now(),
+                phase: 'settle',
+                source: 'store',
+                reservationId: this.reservation.id,
+                ...reservationIdentity(this.reservation),
+                errorName: usageErrorName(error),
+                ...(this.metadata === undefined ? {} : { metadata: this.metadata }),
+            });
+            throw error;
+        }
+    }
+}
+export class VectorUsageLease {
+    store;
+    reservation;
+    ttlMs;
+    observer;
+    metadata;
+    unresolvedGrowth;
+    constructor(store, reservation, ttlMs, observer, metadata, unresolvedGrowth) {
+        this.store = store;
+        this.reservation = reservation;
+        this.ttlMs = ttlMs;
+        this.observer = observer;
+        this.metadata = metadata;
+        this.unresolvedGrowth =
+            unresolvedGrowth === undefined
+                ? undefined
+                : canonicalizeVectorGrowthRequest(unresolvedGrowth);
+    }
+    get reservedByDimension() {
+        return this.reservation.dimensions.map(dimension => ({
+            key: dimension.key,
+            reservedUnits: dimension.reservedUnits,
+        }));
+    }
+    toResumeState() {
+        return {
+            reservation: cloneVectorReservationRecord(this.reservation),
+            ttlMs: this.ttlMs,
+            ...(this.metadata === undefined ? {} : { metadata: { ...this.metadata } }),
+            ...(this.unresolvedGrowth === undefined
+                ? {}
+                : { unresolvedGrowth: cloneVectorGrowthRequest(this.unresolvedGrowth) }),
+        };
+    }
+    async grow(input) {
+        const request = canonicalizeVectorGrowthRequest(input);
+        if (this.unresolvedGrowth && !sameVectorGrowthRequest(this.unresolvedGrowth, request)) {
+            throw new UsageStateError('A vector growth attempt is unresolved; retry the same incrementId and parameters');
+        }
+        if (!isVectorUsageStore(this.store)) {
+            throw new UsageStateError('UsageStore does not support atomic vector usage');
+        }
+        const expectedGrowthCursor = this.reservation.growthCursor;
+        if (!expectedGrowthCursor) {
+            throw new UsageStateError('Vector reservation was not created with growth support');
+        }
+        this.unresolvedGrowth = request;
+        try {
+            const result = validateStoreVectorGrowthResult(await this.store.growVectorReservation({
+                reservationId: this.reservation.id,
+                incrementId: request.incrementId,
+                expectedGrowthCursor,
+                dimensions: request.dimensions,
+            }), this.reservation, request);
+            this.reservation.growthCursor = result.growthCursor;
+            if (result.accepted) {
+                const byKey = new Map(result.reservedByDimension.map(item => [item.key, item.reservedUnits]));
+                for (const dimension of this.reservation.dimensions) {
+                    const reservedUnits = byKey.get(dimension.key);
+                    if (reservedUnits === undefined) {
+                        throw new UsageStateError('Vector growth result omitted a reservation dimension');
+                    }
+                    dimension.reservedUnits = reservedUnits;
+                }
+            }
+            this.unresolvedGrowth = undefined;
+            return result;
+        }
+        catch (error) {
+            if (error instanceof UsageStateError)
+                this.unresolvedGrowth = undefined;
+            throw error;
+        }
+    }
+    async markLiable() {
+        try {
+            const marked = await this.store.markLiable({ reservationId: this.reservation.id });
+            this.reservation.expiresAt = marked.expiresAt;
+            return marked;
+        }
+        catch (error) {
+            emitUsageEvent(this.observer, {
+                type: 'operation.error',
+                timestamp: Date.now(),
+                phase: 'mark_liable',
+                source: 'store',
+                reservationId: this.reservation.id,
+                ...vectorReservationIdentity(this.reservation),
+                errorName: usageErrorName(error),
+                ...(this.metadata === undefined ? {} : { metadata: this.metadata }),
+            });
+            throw error;
+        }
+    }
+    async renew(ttlMs = this.ttlMs) {
+        assertPositiveInteger(ttlMs, 'ttlMs');
+        try {
+            const renewed = await this.store.renew({ reservationId: this.reservation.id, ttlMs });
+            this.reservation.expiresAt = renewed.expiresAt;
+            return renewed;
+        }
+        catch (error) {
+            emitUsageEvent(this.observer, {
+                type: 'operation.error',
+                timestamp: Date.now(),
+                phase: 'renew',
+                source: 'store',
+                reservationId: this.reservation.id,
+                ...vectorReservationIdentity(this.reservation),
+                errorName: usageErrorName(error),
+                ...(this.metadata === undefined ? {} : { metadata: this.metadata }),
+            });
+            throw error;
+        }
+    }
+    async settle(actualByDimension, outcome) {
+        if (!isVectorUsageStore(this.store)) {
+            throw new UsageStateError('UsageStore does not support atomic vector usage');
+        }
+        const actual = canonicalizeVectorActuals(actualByDimension, this.reservation.dimensions);
+        try {
+            const settlement = await this.store.settleVector({
+                reservationId: this.reservation.id,
+                actualByDimension: actual,
+                outcome,
+            });
+            emitUsageEvent(this.observer, {
+                type: 'vector.settlement.completed',
+                timestamp: Date.now(),
+                reservationId: this.reservation.id,
+                ...vectorReservationIdentity(this.reservation),
+                dimensions: settlement.dimensions.map(dimension => ({ ...dimension })),
+                outcome: settlement.outcome,
+                ...(this.metadata === undefined ? {} : { metadata: this.metadata }),
+            });
+            return settlement;
+        }
+        catch (error) {
+            emitUsageEvent(this.observer, {
+                type: 'operation.error',
+                timestamp: Date.now(),
+                phase: 'settle',
+                source: 'store',
+                reservationId: this.reservation.id,
+                ...vectorReservationIdentity(this.reservation),
+                errorName: usageErrorName(error),
+                ...(this.metadata === undefined ? {} : { metadata: this.metadata }),
+            });
+            throw error;
+        }
+    }
+}
+export class UsageControl {
+    store;
+    policy;
+    defaultReservationTtlMs;
+    observer;
+    metadata;
+    constructor(store, policy, optionsOrTtl = 60_000) {
+        this.store = store;
+        this.policy = policy;
+        if (typeof optionsOrTtl === 'number') {
+            this.defaultReservationTtlMs = optionsOrTtl;
+        }
+        else {
+            this.defaultReservationTtlMs = optionsOrTtl.defaultReservationTtlMs ?? 60_000;
+            this.observer = optionsOrTtl.observer;
+            this.metadata = optionsOrTtl.metadata;
+        }
+        assertPositiveInteger(this.defaultReservationTtlMs, 'defaultReservationTtlMs');
+    }
+    /**
+     * Reattach to an existing reservation without calling policy.quote() or reserve().
+     *
+     * The caller must obtain `state` from a trusted server-side `UsageLease` snapshot.
+     * The underlying store remains authoritative: the first renew/settle still fails
+     * closed if the reservation expired, was settled, or otherwise conflicts.
+     */
+    resumeLease(state) {
+        assertPositiveInteger(state.ttlMs, 'ttlMs');
+        const reservation = cloneReservationRecord(state.reservation);
+        return new UsageLease(this.store, reservation, state.ttlMs, this.observer, state.metadata === undefined ? undefined : { ...state.metadata }, state.unresolvedGrowth);
+    }
+    async reserve(request) {
+        validateRequestIdentity(request);
+        const requestForPolicy = request;
+        const metadata = resolveMetadata(this.metadata, requestForPolicy);
+        let quote;
+        try {
+            quote = normalizeUsagePolicyQuote(await this.policy.quote(requestForPolicy));
+        }
+        catch (error) {
+            emitUsageEvent(this.observer, {
+                type: 'operation.error',
+                timestamp: Date.now(),
+                phase: 'quote',
+                source: 'policy',
+                ...requestIdentity(requestForPolicy),
+                errorName: usageErrorName(error),
+                ...(metadata === undefined ? {} : { metadata }),
+            });
+            throw error;
+        }
+        if (quote.decision === 'deny') {
+            emitUsageEvent(this.observer, {
+                type: 'reserve.denied',
+                timestamp: Date.now(),
+                ...requestIdentity(requestForPolicy),
+                reason: quote.reason,
+                ...(metadata === undefined ? {} : { metadata }),
+            });
+            return { allowed: false, reason: quote.reason };
+        }
+        const budgets = quote.budgets;
+        const ttlMs = quote.reservationTtlMs ?? this.defaultReservationTtlMs;
+        assertPositiveInteger(ttlMs, 'reservationTtlMs');
+        let result;
+        try {
+            result = validateStoreReserveResult(await this.store.reserve({
+                request: requestForPolicy,
+                units: quote.units,
+                budgets,
+                ttlMs,
+            }), requestForPolicy, quote.units, budgets);
+        }
+        catch (error) {
+            emitUsageEvent(this.observer, {
+                type: 'operation.error',
+                timestamp: Date.now(),
+                phase: 'reserve',
+                source: 'store',
+                ...requestIdentity(requestForPolicy),
+                errorName: usageErrorName(error),
+                ...(metadata === undefined ? {} : { metadata }),
+            });
+            throw error;
+        }
+        if (!result.accepted) {
+            emitUsageEvent(this.observer, {
+                type: 'reserve.denied',
+                timestamp: Date.now(),
+                ...requestIdentity(requestForPolicy),
+                reason: result.reason,
+                ...(result.limitingBudgetKey === undefined
+                    ? {}
+                    : { limitingBudgetKey: result.limitingBudgetKey }),
+                ...(result.remaining === undefined ? {} : { remaining: result.remaining }),
+                ...(metadata === undefined ? {} : { metadata }),
+            });
+            return {
+                allowed: false,
+                reason: result.reason,
+                ...(result.limitingBudgetKey === undefined
+                    ? {}
+                    : { limitingBudgetKey: result.limitingBudgetKey }),
+                ...(result.remaining === undefined ? {} : { remaining: result.remaining }),
+            };
+        }
+        emitUsageEvent(this.observer, {
+            type: 'reserve.accepted',
+            timestamp: Date.now(),
+            ...requestIdentity(requestForPolicy),
+            reservationId: result.reservation.id,
+            budgetKeys: [...result.reservation.budgetKeys],
+            reservedUnits: result.reservation.reservedUnits,
+            remainingByBudget: result.remainingByBudget.map(balance => ({ ...balance })),
+            ...(metadata === undefined ? {} : { metadata }),
+        });
+        return {
+            allowed: true,
+            lease: new UsageLease(this.store, result.reservation, ttlMs, this.observer, metadata),
+            remainingByBudget: result.remainingByBudget.map(balance => ({ ...balance })),
+        };
+    }
+}
+export class VectorUsageControl {
+    store;
+    policy;
+    defaultReservationTtlMs;
+    observer;
+    metadata;
+    constructor(store, policy, optionsOrTtl = 60_000) {
+        this.store = store;
+        this.policy = policy;
+        if (typeof optionsOrTtl === 'number') {
+            this.defaultReservationTtlMs = optionsOrTtl;
+        }
+        else {
+            this.defaultReservationTtlMs = optionsOrTtl.defaultReservationTtlMs ?? 60_000;
+            this.observer = optionsOrTtl.observer;
+            this.metadata = optionsOrTtl.metadata;
+        }
+        assertPositiveInteger(this.defaultReservationTtlMs, 'defaultReservationTtlMs');
+    }
+    resumeLease(state) {
+        if (!isVectorUsageStore(this.store)) {
+            throw new UsageStateError('UsageStore does not support atomic vector usage');
+        }
+        assertPositiveInteger(state.ttlMs, 'ttlMs');
+        return new VectorUsageLease(this.store, cloneVectorReservationRecord(state.reservation), state.ttlMs, this.observer, state.metadata === undefined ? undefined : { ...state.metadata }, state.unresolvedGrowth);
+    }
+    async reserve(request) {
+        validateRequestIdentity(request);
+        if (!isVectorUsageStore(this.store)) {
+            throw new UsageStateError('UsageStore does not support atomic vector usage');
+        }
+        const requestForPolicy = request;
+        const metadata = resolveMetadata(this.metadata, requestForPolicy);
+        let quote;
+        try {
+            quote = normalizeVectorUsagePolicyQuote(await this.policy.quote(requestForPolicy));
+        }
+        catch (error) {
+            emitUsageEvent(this.observer, {
+                type: 'operation.error',
+                timestamp: Date.now(),
+                phase: 'quote',
+                source: 'policy',
+                ...requestIdentity(requestForPolicy),
+                errorName: usageErrorName(error),
+                ...(metadata === undefined ? {} : { metadata }),
+            });
+            throw error;
+        }
+        if (quote.decision === 'deny') {
+            emitUsageEvent(this.observer, {
+                type: 'vector.reserve.denied',
+                timestamp: Date.now(),
+                ...requestIdentity(requestForPolicy),
+                reason: quote.reason,
+                ...(metadata === undefined ? {} : { metadata }),
+            });
+            return { allowed: false, reason: quote.reason };
+        }
+        const dimensions = quote.dimensions;
+        const ttlMs = quote.reservationTtlMs ?? this.defaultReservationTtlMs;
+        assertPositiveInteger(ttlMs, 'reservationTtlMs');
+        let result;
+        try {
+            result = validateStoreVectorReserveResult(await this.store.reserveVector({ request: requestForPolicy, dimensions, ttlMs }), requestForPolicy, dimensions);
+        }
+        catch (error) {
+            emitUsageEvent(this.observer, {
+                type: 'operation.error',
+                timestamp: Date.now(),
+                phase: 'reserve',
+                source: 'store',
+                ...requestIdentity(requestForPolicy),
+                errorName: usageErrorName(error),
+                ...(metadata === undefined ? {} : { metadata }),
+            });
+            throw error;
+        }
+        if (!result.accepted) {
+            emitUsageEvent(this.observer, {
+                type: 'vector.reserve.denied',
+                timestamp: Date.now(),
+                ...requestIdentity(requestForPolicy),
+                reason: result.reason,
+                ...(result.limitingDimensionKey === undefined
+                    ? {}
+                    : { limitingDimensionKey: result.limitingDimensionKey }),
+                ...(result.limitingBudgetKey === undefined
+                    ? {}
+                    : { limitingBudgetKey: result.limitingBudgetKey }),
+                ...(result.remaining === undefined ? {} : { remaining: result.remaining }),
+                ...(metadata === undefined ? {} : { metadata }),
+            });
+            return {
+                allowed: false,
+                reason: result.reason,
+                ...(result.limitingDimensionKey === undefined
+                    ? {}
+                    : { limitingDimensionKey: result.limitingDimensionKey }),
+                ...(result.limitingBudgetKey === undefined
+                    ? {}
+                    : { limitingBudgetKey: result.limitingBudgetKey }),
+                ...(result.remaining === undefined ? {} : { remaining: result.remaining }),
+            };
+        }
+        emitUsageEvent(this.observer, {
+            type: 'vector.reserve.accepted',
+            timestamp: Date.now(),
+            ...requestIdentity(requestForPolicy),
+            reservationId: result.reservation.id,
+            dimensions: result.reservation.dimensions.map(dimension => ({
+                key: dimension.key,
+                reservedUnits: dimension.reservedUnits,
+                budgetKeys: [...dimension.budgetKeys],
+            })),
+            remainingByBudget: result.remainingByBudget.map(balance => ({ ...balance })),
+            ...(metadata === undefined ? {} : { metadata }),
+        });
+        return {
+            allowed: true,
+            lease: new VectorUsageLease(this.store, result.reservation, ttlMs, this.observer, metadata),
+            remainingByBudget: result.remainingByBudget.map(balance => ({ ...balance })),
+        };
+    }
+}
+const DEFAULT_MEMORY_MAX_RETAINED_OPERATIONS = 100_000;
+const DEFAULT_MEMORY_MAX_RETAINED_BUDGET_KEYS = 100_000;
+export class MemoryUsageStoreCapacityError extends UsageStateError {
+    resource;
+    limit;
+    constructor(resource, limit) {
+        super(resource === 'operations'
+            ? `MemoryUsageStore operation retention limit reached (${limit}); refusing to evict replay/accounting state`
+            : `MemoryUsageStore budget-key retention limit reached (${limit}); refusing to evict authoritative usage state`);
+        this.resource = resource;
+        this.limit = limit;
+        this.name = 'MemoryUsageStoreCapacityError';
+    }
+}
+export class MemoryUsageStore {
+    used = new Map();
+    reservations = new Map();
+    operations = new Map();
+    idempotencyTtlMs;
+    maxRetainedOperations;
+    maxRetainedBudgetKeys;
+    observer;
+    nextRecoveryAt = Number.POSITIVE_INFINITY;
+    constructor(options = {}) {
+        this.idempotencyTtlMs = options.idempotencyTtlMs ?? 86_400_000;
+        this.maxRetainedOperations =
+            options.maxRetainedOperations ?? DEFAULT_MEMORY_MAX_RETAINED_OPERATIONS;
+        this.maxRetainedBudgetKeys =
+            options.maxRetainedBudgetKeys ?? DEFAULT_MEMORY_MAX_RETAINED_BUDGET_KEYS;
+        this.observer = options.observer;
+        assertPositiveInteger(this.idempotencyTtlMs, 'idempotencyTtlMs');
+        assertPositiveInteger(this.maxRetainedOperations, 'maxRetainedOperations');
+        assertPositiveInteger(this.maxRetainedBudgetKeys, 'maxRetainedBudgetKeys');
+    }
+    /** Current bounded-retention counters for health checks and operational monitoring. */
+    stats() {
+        this.recoverExpired(Date.now());
+        return {
+            retainedOperations: this.reservations.size,
+            retainedBudgetKeys: this.used.size,
+            maxRetainedOperations: this.maxRetainedOperations,
+            maxRetainedBudgetKeys: this.maxRetainedBudgetKeys,
+        };
+    }
+    /**
+     * Explicitly retire one budget key after its accounting window is permanently over.
+     *
+     * This is never automatic because forgetting non-zero usage can reset quota semantics.
+     * Active reservations block retirement. Callers must ensure the same key will not later
+     * be reused for the same accounting window.
+     */
+    retireBudgetKey(budgetKey) {
+        if (typeof budgetKey !== 'string' || budgetKey.length === 0) {
+            throw new RangeError('budgetKey must be a non-empty string');
+        }
+        this.recoverExpired(Date.now());
+        for (const reservation of this.reservations.values()) {
+            if (reservation.state !== 'settled' &&
+                internalReservationBudgetKeys(reservation).includes(budgetKey)) {
+                throw new UsageStateError('Cannot retire a budget key referenced by an active reservation');
+            }
+        }
+        return this.used.delete(budgetKey);
+    }
+    async reconcileOperation(input) {
+        assertNonNegativeInteger(input.units, 'units');
+        const budgets = canonicalizeBudgets(input.budgets);
+        validateRequestIdentity(input.request);
+        const now = Date.now();
+        const reservationId = operationKeyFor(input.request);
+        const reservation = this.reservations.get(reservationId);
+        if (!reservation)
+            return { status: 'absent', reservationId };
+        if (reservation.mode !== 'scalar') {
+            throw new UsageStateError('Scalar operation reconciliation cannot target a vector reservation');
+        }
+        if (reservation.reservedUnits !== input.units ||
+            !sameBudgetKeys(reservation.budgetKeys, budgets)) {
+            throw new UsageStateError('Operation reconciliation input does not match retained reservation state');
+        }
+        if (reservation.state === 'pending' || reservation.state === 'liable') {
+            if (reservation.expiresAt <= now) {
+                return {
+                    status: 'expired',
+                    state: reservation.state,
+                    reservationId: reservation.id,
+                    expiredAt: reservation.expiresAt,
+                };
+            }
+            return {
+                status: 'active',
+                state: reservation.state,
+                reservation: cloneReservationRecord(reservation),
+            };
+        }
+        if (reservation.tombstoneExpiresAt !== undefined &&
+            reservation.tombstoneExpiresAt <= now) {
+            return { status: 'absent', reservationId };
+        }
+        if (reservation.outcome === 'lease_expired_after_execution_started') {
+            return {
+                status: 'expired',
+                state: 'liable',
+                reservationId: reservation.id,
+                expiredAt: reservation.expiresAt,
+            };
+        }
+        if (reservation.actualUnits === undefined || reservation.tombstoneExpiresAt === undefined) {
+            throw new UsageStateError('Settled reservation is missing reconciliation state');
+        }
+        return {
+            status: 'settled',
+            reservationId: reservation.id,
+            reservedUnits: reservation.reservedUnits,
+            actualUnits: reservation.actualUnits,
+            tombstoneExpiresAt: reservation.tombstoneExpiresAt,
+        };
+    }
+    async reconcileVectorOperation(input) {
+        validateRequestIdentity(input.request);
+        const dimensions = canonicalizeUsageDimensions(input.dimensions);
+        const now = Date.now();
+        const reservationId = operationKeyFor(input.request);
+        const reservation = this.reservations.get(reservationId);
+        if (!reservation)
+            return { status: 'absent', reservationId };
+        if (reservation.mode !== 'vector') {
+            throw new UsageStateError('Vector operation reconciliation cannot target a scalar reservation');
+        }
+        if (!sameVectorReconciliationTopology(reservation.dimensions, dimensions)) {
+            throw new UsageStateError('Vector reconciliation input does not match retained reservation state');
+        }
+        if (reservation.state === 'pending' || reservation.state === 'liable') {
+            if (reservation.expiresAt <= now) {
+                return {
+                    status: 'expired',
+                    state: reservation.state,
+                    reservationId: reservation.id,
+                    expiredAt: reservation.expiresAt,
+                };
+            }
+            return {
+                status: 'active',
+                state: reservation.state,
+                reservation: cloneVectorReservationRecord(reservation),
+            };
+        }
+        if (reservation.tombstoneExpiresAt !== undefined && reservation.tombstoneExpiresAt <= now) {
+            return { status: 'absent', reservationId };
+        }
+        if (reservation.outcome === 'lease_expired_after_execution_started') {
+            return {
+                status: 'expired',
+                state: 'liable',
+                reservationId: reservation.id,
+                expiredAt: reservation.expiresAt,
+            };
+        }
+        if (reservation.actualByDimension === undefined || reservation.tombstoneExpiresAt === undefined) {
+            throw new UsageStateError('Settled vector reservation is missing reconciliation state');
+        }
+        return {
+            status: 'settled',
+            reservationId: reservation.id,
+            reservedByDimension: reservation.dimensions.map(dimension => ({
+                key: dimension.key,
+                reservedUnits: dimension.reservedUnits,
+            })),
+            actualByDimension: reservation.actualByDimension.map(item => ({ ...item })),
+            tombstoneExpiresAt: reservation.tombstoneExpiresAt,
+        };
+    }
+    async reserve(input) {
+        assertNonNegativeInteger(input.units, 'units');
+        const budgets = canonicalizeBudgets(input.budgets);
+        assertPositiveInteger(input.ttlMs, 'ttlMs');
+        validateRequestIdentity(input.request);
+        const now = Date.now();
+        const expiresAt = safeAdd(now, input.ttlMs, 'reservation expiry');
+        this.recoverExpired(now);
+        const operationKey = operationKeyFor(input.request);
+        if (this.operations.has(operationKey)) {
+            return { accepted: false, reason: 'duplicate_operation' };
+        }
+        const remainingByBudget = budgets.map(budget => ({
+            key: budget.key,
+            remaining: Math.max(0, budget.limit - (this.used.get(budget.key) ?? 0)),
+        }));
+        const limiting = remainingByBudget.find(balance => input.units > balance.remaining);
+        if (limiting) {
+            return {
+                accepted: false,
+                reason: 'quota_exceeded',
+                limitingBudgetKey: limiting.key,
+                remaining: limiting.remaining,
+            };
+        }
+        this.assertOperationCapacity();
+        if (input.units > 0)
+            this.assertBudgetCapacity(budgets);
+        const reservation = {
+            mode: 'scalar',
+            id: operationKey,
+            operationId: input.request.operationId,
+            principalId: input.request.principal.id,
+            ...(input.request.principal.tenantId === undefined
+                ? {}
+                : { tenantId: input.request.principal.tenantId }),
+            ...(input.request.principal.plan === undefined ? {} : { plan: input.request.principal.plan }),
+            tool: input.request.tool,
+            budgetKeys: budgets.map(budget => budget.key),
+            reservedUnits: input.units,
+            expiresAt,
+            growthCursor: newGrowthCursor(),
+            operationKey,
+            state: 'pending',
+        };
+        if (input.units > 0) {
+            for (const budget of budgets) {
+                this.used.set(budget.key, (this.used.get(budget.key) ?? 0) + input.units);
+            }
+        }
+        this.reservations.set(reservation.id, reservation);
+        this.operations.set(operationKey, reservation.id);
+        this.trackRecoveryAt(reservation.expiresAt);
+        return {
+            accepted: true,
+            reservation: cloneReservationRecord(reservation),
+            remainingByBudget: remainingByBudget.map(balance => ({
+                key: balance.key,
+                remaining: balance.remaining - input.units,
+            })),
+        };
+    }
+    async reserveVector(input) {
+        assertPositiveInteger(input.ttlMs, 'ttlMs');
+        validateRequestIdentity(input.request);
+        const dimensions = canonicalizeUsageDimensions(input.dimensions);
+        const now = Date.now();
+        const expiresAt = safeAdd(now, input.ttlMs, 'reservation expiry');
+        this.recoverExpired(now);
+        const operationKey = operationKeyFor(input.request);
+        if (this.operations.has(operationKey)) {
+            return { accepted: false, reason: 'duplicate_operation' };
+        }
+        const remainingByBudget = [];
+        let limiting;
+        for (const dimension of dimensions) {
+            for (const budget of dimension.budgets) {
+                const remaining = Math.max(0, budget.limit - (this.used.get(budget.key) ?? 0));
+                remainingByBudget.push({
+                    dimensionKey: dimension.key,
+                    budgetKey: budget.key,
+                    remaining,
+                });
+                if (!limiting && dimension.units > remaining) {
+                    limiting = { dimensionKey: dimension.key, budgetKey: budget.key, remaining };
+                }
+            }
+        }
+        if (limiting) {
+            return {
+                accepted: false,
+                reason: 'quota_exceeded',
+                limitingDimensionKey: limiting.dimensionKey,
+                limitingBudgetKey: limiting.budgetKey,
+                remaining: limiting.remaining,
+            };
+        }
+        this.assertOperationCapacity();
+        const nonZeroBudgets = dimensions.flatMap(dimension => dimension.units > 0 ? dimension.budgets : []);
+        if (nonZeroBudgets.length > 0)
+            this.assertBudgetCapacity(nonZeroBudgets);
+        const reservation = {
+            mode: 'vector',
+            id: operationKey,
+            operationId: input.request.operationId,
+            principalId: input.request.principal.id,
+            ...(input.request.principal.tenantId === undefined
+                ? {}
+                : { tenantId: input.request.principal.tenantId }),
+            ...(input.request.principal.plan === undefined ? {} : { plan: input.request.principal.plan }),
+            tool: input.request.tool,
+            dimensions: dimensions.map(dimension => ({
+                key: dimension.key,
+                budgetKeys: dimension.budgets.map(budget => budget.key),
+                reservedUnits: dimension.units,
+            })),
+            expiresAt,
+            growthCursor: newGrowthCursor(),
+            operationKey,
+            state: 'pending',
+        };
+        for (const dimension of dimensions) {
+            if (dimension.units === 0)
+                continue;
+            for (const budget of dimension.budgets) {
+                this.used.set(budget.key, safeAdd(this.used.get(budget.key) ?? 0, dimension.units, `usage (${budget.key})`));
+            }
+        }
+        this.reservations.set(reservation.id, reservation);
+        this.operations.set(operationKey, reservation.id);
+        this.trackRecoveryAt(reservation.expiresAt);
+        const unitsByDimension = new Map(dimensions.map(dimension => [dimension.key, dimension.units]));
+        return {
+            accepted: true,
+            reservation: cloneVectorReservationRecord(reservation),
+            remainingByBudget: remainingByBudget.map(balance => ({
+                ...balance,
+                remaining: balance.remaining - (unitsByDimension.get(balance.dimensionKey) ?? 0),
+            })),
+        };
+    }
+    async growVectorReservation(input) {
+        validateVectorGrowthInput(input);
+        const dimensions = canonicalizeVectorGrowthDimensions(input.dimensions);
+        const fingerprint = vectorGrowthFingerprint(dimensions);
+        const now = Date.now();
+        this.recoverExpired(now);
+        const reservation = this.reservations.get(input.reservationId);
+        if (!reservation)
+            throw new UsageStateError('Reservation not found or expired');
+        if (reservation.mode !== 'vector') {
+            throw new UsageStateError('Vector growth cannot target a scalar reservation');
+        }
+        if (reservation.state === 'settled') {
+            throw new UsageStateError('Cannot grow a settled or expired vector reservation');
+        }
+        const lastGrowth = reservation.lastVectorGrowth;
+        if (lastGrowth?.incrementId === input.incrementId) {
+            if (lastGrowth.expectedGrowthCursor !== input.expectedGrowthCursor ||
+                lastGrowth.fingerprint !== fingerprint) {
+                throw new UsageStateError('Vector growth increment was already attempted with different parameters');
+            }
+            return replayVectorGrowthResult(lastGrowth.result);
+        }
+        if (!reservation.growthCursor) {
+            throw new UsageStateError('Vector reservation does not support progressive growth');
+        }
+        if (reservation.growthCursor !== input.expectedGrowthCursor) {
+            throw new UsageStateError('Vector growth cursor is stale or conflicts with reservation state');
+        }
+        if (!sameVectorTopology(reservation.dimensions, dimensions)) {
+            throw new UsageStateError('Vector growth dimensions and budgets must match the reservation');
+        }
+        const remainingByBudget = [];
+        let limiting;
+        for (const dimension of dimensions) {
+            for (const budget of dimension.budgets) {
+                const remaining = Math.max(0, budget.limit - (this.used.get(budget.key) ?? 0));
+                remainingByBudget.push({
+                    dimensionKey: dimension.key,
+                    budgetKey: budget.key,
+                    remaining,
+                });
+                if (!limiting && dimension.additionalUnits > remaining) {
+                    limiting = { dimensionKey: dimension.key, budgetKey: budget.key, remaining };
+                }
+            }
+        }
+        const nextGrowthCursor = newGrowthCursor();
+        if (limiting) {
+            const result = {
+                accepted: false,
+                reason: 'quota_exceeded',
+                replayed: false,
+                reservationId: reservation.id,
+                incrementId: input.incrementId,
+                growthCursor: nextGrowthCursor,
+                limitingDimensionKey: limiting.dimensionKey,
+                limitingBudgetKey: limiting.budgetKey,
+                remaining: limiting.remaining,
+            };
+            reservation.growthCursor = nextGrowthCursor;
+            reservation.lastVectorGrowth = {
+                incrementId: input.incrementId,
+                expectedGrowthCursor: input.expectedGrowthCursor,
+                fingerprint,
+                result: cloneVectorGrowthResult(result),
+            };
+            return result;
+        }
+        const newlyNonZeroBudgets = dimensions.flatMap(dimension => dimension.additionalUnits > 0 ? dimension.budgets : []);
+        if (newlyNonZeroBudgets.length > 0)
+            this.assertBudgetCapacity(newlyNonZeroBudgets);
+        const previousReservedByDimension = reservation.dimensions.map(dimension => ({
+            key: dimension.key,
+            reservedUnits: dimension.reservedUnits,
+        }));
+        const growthByKey = new Map(dimensions.map(dimension => [dimension.key, dimension]));
+        for (const reservedDimension of reservation.dimensions) {
+            const growth = growthByKey.get(reservedDimension.key);
+            if (growth.additionalUnits > 0) {
+                for (const budget of growth.budgets) {
+                    this.used.set(budget.key, safeAdd(this.used.get(budget.key) ?? 0, growth.additionalUnits, `usage (${budget.key})`));
+                }
+            }
+            reservedDimension.reservedUnits = safeAdd(reservedDimension.reservedUnits, growth.additionalUnits, `reservedUnits (${reservedDimension.key})`);
+        }
+        reservation.growthCursor = nextGrowthCursor;
+        const reservedByDimension = reservation.dimensions.map(dimension => ({
+            key: dimension.key,
+            reservedUnits: dimension.reservedUnits,
+        }));
+        const addedByDimension = new Map(dimensions.map(dimension => [dimension.key, dimension.additionalUnits]));
+        const result = {
+            accepted: true,
+            replayed: false,
+            reservationId: reservation.id,
+            incrementId: input.incrementId,
+            previousReservedByDimension,
+            reservedByDimension,
+            growthCursor: nextGrowthCursor,
+            remainingByBudget: remainingByBudget.map(balance => ({
+                ...balance,
+                remaining: balance.remaining - (addedByDimension.get(balance.dimensionKey) ?? 0),
+            })),
+        };
+        reservation.lastVectorGrowth = {
+            incrementId: input.incrementId,
+            expectedGrowthCursor: input.expectedGrowthCursor,
+            fingerprint,
+            result: cloneVectorGrowthResult(result),
+        };
+        return result;
+    }
+    async settleVector(input) {
+        const now = Date.now();
+        const tombstoneExpiresAt = safeAdd(now, this.idempotencyTtlMs, 'tombstone expiry');
+        this.recoverExpired(now);
+        const reservation = this.reservations.get(input.reservationId);
+        if (!reservation)
+            throw new UsageStateError('Reservation not found or expired');
+        if (reservation.mode !== 'vector') {
+            throw new UsageStateError('Vector settlement cannot target a scalar reservation');
+        }
+        const actualByDimension = canonicalizeVectorActuals(input.actualByDimension, reservation.dimensions);
+        if (reservation.state === 'settled') {
+            if (reservation.outcome !== input.outcome ||
+                !sameVectorActuals(reservation.actualByDimension, actualByDimension)) {
+                throw new UsageStateError('Vector reservation was already settled with a different result');
+            }
+            return toVectorSettlement(reservation);
+        }
+        const actualByKey = new Map(actualByDimension.map(item => [item.key, item.actualUnits]));
+        for (const dimension of reservation.dimensions) {
+            const actualUnits = actualByKey.get(dimension.key);
+            const releasedUnits = dimension.reservedUnits - actualUnits;
+            if (releasedUnits > 0)
+                this.releaseAcrossBudgets(dimension.budgetKeys, releasedUnits);
+        }
+        reservation.state = 'settled';
+        reservation.actualByDimension = actualByDimension.map(item => ({ ...item }));
+        reservation.outcome = input.outcome;
+        reservation.tombstoneExpiresAt = tombstoneExpiresAt;
+        this.trackRecoveryAt(tombstoneExpiresAt);
+        return toVectorSettlement(reservation);
+    }
+    async markLiable(input) {
+        const now = Date.now();
+        this.recoverExpired(now);
+        const reservation = this.reservations.get(input.reservationId);
+        if (!reservation || reservation.state === 'settled') {
+            throw new UsageStateError('Active reservation not found or expired');
+        }
+        reservation.state = 'liable';
+        return { reservationId: reservation.id, expiresAt: reservation.expiresAt };
+    }
+    async growReservation(input) {
+        validateGrowthInput(input);
+        const budgets = canonicalizeBudgets(input.budgets);
+        const fingerprint = growthFingerprint(input.additionalUnits, budgets);
+        const now = Date.now();
+        this.recoverExpired(now);
+        const reservation = this.reservations.get(input.reservationId);
+        if (!reservation)
+            throw new UsageStateError('Reservation not found or expired');
+        if (reservation.mode !== 'scalar') {
+            throw new UsageStateError('Scalar growth cannot target a vector reservation');
+        }
+        if (reservation.state === 'settled') {
+            throw new UsageStateError('Cannot grow a settled or expired reservation');
+        }
+        const lastGrowth = reservation.lastGrowth;
+        if (lastGrowth?.incrementId === input.incrementId) {
+            if (lastGrowth.expectedGrowthCursor !== input.expectedGrowthCursor ||
+                lastGrowth.fingerprint !== fingerprint) {
+                throw new UsageStateError('Growth increment was already attempted with different parameters');
+            }
+            return replayGrowthResult(lastGrowth.result);
+        }
+        if (!reservation.growthCursor) {
+            throw new UsageStateError('Reservation does not support progressive growth');
+        }
+        if (reservation.growthCursor !== input.expectedGrowthCursor) {
+            throw new UsageStateError('Growth cursor is stale or conflicts with reservation state');
+        }
+        if (!sameBudgetKeys(reservation.budgetKeys, budgets)) {
+            throw new UsageStateError('Growth budgets must exactly match the reservation budget set');
+        }
+        const remainingByBudget = budgets.map(budget => ({
+            key: budget.key,
+            remaining: Math.max(0, budget.limit - (this.used.get(budget.key) ?? 0)),
+        }));
+        const limiting = remainingByBudget.find(balance => input.additionalUnits > balance.remaining);
+        const nextGrowthCursor = newGrowthCursor();
+        if (limiting) {
+            const result = {
+                accepted: false,
+                reason: 'quota_exceeded',
+                replayed: false,
+                reservationId: reservation.id,
+                incrementId: input.incrementId,
+                growthCursor: nextGrowthCursor,
+                limitingBudgetKey: limiting.key,
+                remaining: limiting.remaining,
+            };
+            reservation.growthCursor = nextGrowthCursor;
+            reservation.lastGrowth = {
+                incrementId: input.incrementId,
+                expectedGrowthCursor: input.expectedGrowthCursor,
+                fingerprint,
+                result: cloneGrowthResult(result),
+            };
+            return result;
+        }
+        this.assertBudgetCapacity(budgets);
+        const previousReservedUnits = reservation.reservedUnits;
+        const reservedUnits = safeAdd(previousReservedUnits, input.additionalUnits, 'reservedUnits');
+        for (const budget of budgets) {
+            this.used.set(budget.key, safeAdd(this.used.get(budget.key) ?? 0, input.additionalUnits, `usage (${budget.key})`));
+        }
+        reservation.reservedUnits = reservedUnits;
+        reservation.growthCursor = nextGrowthCursor;
+        const result = {
+            accepted: true,
+            replayed: false,
+            reservationId: reservation.id,
+            incrementId: input.incrementId,
+            previousReservedUnits,
+            reservedUnits,
+            growthCursor: nextGrowthCursor,
+            remainingByBudget: remainingByBudget.map(balance => ({
+                key: balance.key,
+                remaining: balance.remaining - input.additionalUnits,
+            })),
+        };
+        reservation.lastGrowth = {
+            incrementId: input.incrementId,
+            expectedGrowthCursor: input.expectedGrowthCursor,
+            fingerprint,
+            result: cloneGrowthResult(result),
+        };
+        return result;
+    }
+    async renew(input) {
+        assertPositiveInteger(input.ttlMs, 'ttlMs');
+        const now = Date.now();
+        const expiresAt = safeAdd(now, input.ttlMs, 'reservation expiry');
+        this.recoverExpired(now);
+        const reservation = this.reservations.get(input.reservationId);
+        if (!reservation || reservation.state === 'settled') {
+            throw new UsageStateError('Active reservation not found or expired');
+        }
+        reservation.expiresAt = expiresAt;
+        this.trackRecoveryAt(expiresAt);
+        return { reservationId: reservation.id, expiresAt };
+    }
+    async settle(input) {
+        assertNonNegativeInteger(input.actualUnits, 'actualUnits');
+        const now = Date.now();
+        const tombstoneExpiresAt = safeAdd(now, this.idempotencyTtlMs, 'tombstone expiry');
+        this.recoverExpired(now);
+        const reservation = this.reservations.get(input.reservationId);
+        if (!reservation)
+            throw new UsageStateError('Reservation not found or expired');
+        if (reservation.mode !== 'scalar') {
+            throw new UsageStateError('Scalar settlement cannot target a vector reservation');
+        }
+        if (input.actualUnits > reservation.reservedUnits) {
+            throw new UsageStateError('actualUnits cannot exceed reservedUnits');
+        }
+        if (reservation.state === 'settled') {
+            if (reservation.actualUnits !== input.actualUnits || reservation.outcome !== input.outcome) {
+                throw new UsageStateError('Reservation was already settled with a different result');
+            }
+            return toSettlement(reservation);
+        }
+        const released = reservation.reservedUnits - input.actualUnits;
+        if (released > 0)
+            this.releaseAcrossBudgets(reservation.budgetKeys, released);
+        reservation.state = 'settled';
+        reservation.actualUnits = input.actualUnits;
+        reservation.outcome = input.outcome;
+        reservation.tombstoneExpiresAt = tombstoneExpiresAt;
+        this.trackRecoveryAt(tombstoneExpiresAt);
+        return toSettlement(reservation);
+    }
+    recoverExpired(now) {
+        if (now < this.nextRecoveryAt)
+            return;
+        // Preflight every liable transition before mutating any authoritative state.
+        // This keeps recovery atomic with respect to unsafe tombstone arithmetic.
+        for (const reservation of this.reservations.values()) {
+            if (reservation.state === 'liable' &&
+                reservation.expiresAt <= now) {
+                safeAdd(now, this.idempotencyTtlMs, 'tombstone expiry');
+            }
+        }
+        let nextRecoveryAt = Number.POSITIVE_INFINITY;
+        for (const [id, reservation] of this.reservations) {
+            if (reservation.state === 'settled') {
+                const tombstoneExpiresAt = reservation.tombstoneExpiresAt ?? Number.POSITIVE_INFINITY;
+                if (tombstoneExpiresAt <= now) {
+                    this.operations.delete(reservation.operationKey);
+                    this.reservations.delete(id);
+                }
+                else {
+                    nextRecoveryAt = Math.min(nextRecoveryAt, tombstoneExpiresAt);
+                }
+                continue;
+            }
+            if (reservation.expiresAt > now) {
+                nextRecoveryAt = Math.min(nextRecoveryAt, reservation.expiresAt);
+                continue;
+            }
+            if (reservation.state === 'pending') {
+                if (reservation.mode === 'scalar') {
+                    this.releaseAcrossBudgets(reservation.budgetKeys, reservation.reservedUnits);
+                    emitUsageEvent(this.observer, {
+                        type: 'reservation.recovered',
+                        timestamp: now,
+                        store: 'memory',
+                        recovery: 'pending_released',
+                        reservationId: reservation.id,
+                        principalId: reservation.principalId,
+                        ...(reservation.tenantId === undefined ? {} : { tenantId: reservation.tenantId }),
+                        tool: reservation.tool,
+                        budgetIdentifiers: [...reservation.budgetKeys],
+                        reservedUnits: reservation.reservedUnits,
+                        count: 1,
+                    });
+                }
+                else {
+                    for (const dimension of reservation.dimensions) {
+                        this.releaseAcrossBudgets(dimension.budgetKeys, dimension.reservedUnits);
+                    }
+                    emitUsageEvent(this.observer, {
+                        type: 'vector.reservation.recovered',
+                        timestamp: now,
+                        store: 'memory',
+                        recovery: 'pending_released',
+                        reservationId: reservation.id,
+                        principalId: reservation.principalId,
+                        ...(reservation.tenantId === undefined ? {} : { tenantId: reservation.tenantId }),
+                        tool: reservation.tool,
+                        dimensionCount: reservation.dimensions.length,
+                        budgetCount: internalReservationBudgetKeys(reservation).length,
+                        count: 1,
+                    });
+                }
+                this.operations.delete(reservation.operationKey);
+                this.reservations.delete(id);
+                continue;
+            }
+            // Once execution has been marked liable, expiry is conservative: retain
+            // the full reservation as consumed so a process crash cannot become a refund.
+            reservation.state = 'settled';
+            reservation.outcome = 'lease_expired_after_execution_started';
+            reservation.tombstoneExpiresAt = safeAdd(now, this.idempotencyTtlMs, 'tombstone expiry');
+            nextRecoveryAt = Math.min(nextRecoveryAt, reservation.tombstoneExpiresAt);
+            if (reservation.mode === 'scalar') {
+                reservation.actualUnits = reservation.reservedUnits;
+                emitUsageEvent(this.observer, {
+                    type: 'reservation.recovered',
+                    timestamp: now,
+                    store: 'memory',
+                    recovery: 'liable_retained',
+                    reservationId: reservation.id,
+                    principalId: reservation.principalId,
+                    ...(reservation.tenantId === undefined ? {} : { tenantId: reservation.tenantId }),
+                    tool: reservation.tool,
+                    budgetIdentifiers: [...reservation.budgetKeys],
+                    reservedUnits: reservation.reservedUnits,
+                    count: 1,
+                });
+            }
+            else {
+                reservation.actualByDimension = reservation.dimensions.map(dimension => ({
+                    key: dimension.key,
+                    actualUnits: dimension.reservedUnits,
+                }));
+                emitUsageEvent(this.observer, {
+                    type: 'vector.reservation.recovered',
+                    timestamp: now,
+                    store: 'memory',
+                    recovery: 'liable_retained',
+                    reservationId: reservation.id,
+                    principalId: reservation.principalId,
+                    ...(reservation.tenantId === undefined ? {} : { tenantId: reservation.tenantId }),
+                    tool: reservation.tool,
+                    dimensionCount: reservation.dimensions.length,
+                    budgetCount: internalReservationBudgetKeys(reservation).length,
+                    count: 1,
+                });
+            }
+        }
+        this.nextRecoveryAt = nextRecoveryAt;
+    }
+    assertOperationCapacity() {
+        if (this.reservations.size >= this.maxRetainedOperations) {
+            throw new MemoryUsageStoreCapacityError('operations', this.maxRetainedOperations);
+        }
+    }
+    assertBudgetCapacity(budgets) {
+        const newBudgetKeys = new Set();
+        for (const budget of budgets) {
+            if (!this.used.has(budget.key))
+                newBudgetKeys.add(budget.key);
+        }
+        if (this.used.size + newBudgetKeys.size > this.maxRetainedBudgetKeys) {
+            throw new MemoryUsageStoreCapacityError('budget_keys', this.maxRetainedBudgetKeys);
+        }
+    }
+    trackRecoveryAt(expiresAt) {
+        this.nextRecoveryAt = Math.min(this.nextRecoveryAt, expiresAt);
+    }
+    releaseAcrossBudgets(budgetKeys, units) {
+        for (const budgetKey of budgetKeys) {
+            const next = Math.max(0, (this.used.get(budgetKey) ?? 0) - units);
+            if (next === 0)
+                this.used.delete(budgetKey);
+            else
+                this.used.set(budgetKey, next);
+        }
+    }
+}
+function internalReservationBudgetKeys(reservation) {
+    return reservation.mode === 'scalar'
+        ? [...reservation.budgetKeys]
+        : reservation.dimensions.flatMap(dimension => [...dimension.budgetKeys]);
+}
+function validateVectorGrowthInput(input) {
+    assertUsageIdentifier(input.reservationId, 'reservationId');
+    assertUsageIdentifier(input.incrementId, 'incrementId');
+    assertUsageIdentifier(input.expectedGrowthCursor, 'expectedGrowthCursor');
+}
+function sameVectorReconciliationTopology(reserved, expected) {
+    return reserved.length === expected.length && reserved.every((dimension, index) => {
+        const candidate = expected[index];
+        return candidate !== undefined &&
+            dimension.key === candidate.key &&
+            dimension.reservedUnits === candidate.units &&
+            sameBudgetKeys(dimension.budgetKeys, candidate.budgets);
+    });
+}
+function sameVectorTopology(reserved, growth) {
+    if (reserved.length !== growth.length)
+        return false;
+    return reserved.every((dimension, index) => {
+        const candidate = growth[index];
+        return (candidate !== undefined &&
+            dimension.key === candidate.key &&
+            sameBudgetKeys(dimension.budgetKeys, candidate.budgets));
+    });
+}
+function cloneVectorGrowthResult(result) {
+    if (!result.accepted)
+        return { ...result };
+    return {
+        ...result,
+        previousReservedByDimension: result.previousReservedByDimension.map(item => ({ ...item })),
+        reservedByDimension: result.reservedByDimension.map(item => ({ ...item })),
+        remainingByBudget: result.remainingByBudget.map(item => ({ ...item })),
+    };
+}
+function replayVectorGrowthResult(result) {
+    return { ...cloneVectorGrowthResult(result), replayed: true };
+}
+function sameVectorActuals(left, right) {
+    return (left !== undefined &&
+        left.length === right.length &&
+        left.every((item, index) => item.key === right[index].key && item.actualUnits === right[index].actualUnits));
+}
+function toVectorSettlement(reservation) {
+    const actual = reservation.actualByDimension ??
+        reservation.dimensions.map(dimension => ({
+            key: dimension.key,
+            actualUnits: dimension.reservedUnits,
+        }));
+    const actualByKey = new Map(actual.map(item => [item.key, item.actualUnits]));
+    return {
+        reservationId: reservation.id,
+        dimensions: reservation.dimensions.map(dimension => {
+            const actualUnits = actualByKey.get(dimension.key) ?? dimension.reservedUnits;
+            return {
+                key: dimension.key,
+                reservedUnits: dimension.reservedUnits,
+                actualUnits,
+                releasedUnits: dimension.reservedUnits - actualUnits,
+            };
+        }),
+        outcome: reservation.outcome ?? 'unknown',
+    };
+}
+function operationKeyFor(request) {
+    return JSON.stringify([
+        request.principal.tenantId ?? null,
+        request.principal.id,
+        request.tool,
+        request.operationId,
+    ]);
+}
+const MAX_POLICY_DENIAL_REASON_LENGTH = 128;
+function normalizeUsagePolicyQuote(value) {
+    const quote = requireRecord(value, 'Usage policy quote');
+    if (quote.decision === 'deny') {
+        return { decision: 'deny', reason: validatePolicyDenialReason(quote.reason) };
+    }
+    if (quote.decision !== 'allow') {
+        throw new TypeError('Usage policy quote decision must be allow or deny');
+    }
+    assertNonNegativeInteger(quote.units, 'units');
+    const hasBudget = hasOwn(quote, 'budget');
+    const hasBudgets = hasOwn(quote, 'budgets');
+    if (hasBudget === hasBudgets) {
+        throw new TypeError('Usage policy allow quote must contain exactly one of budget or budgets');
+    }
+    const budgets = hasBudgets
+        ? canonicalizeBudgets(quote.budgets)
+        : canonicalizeBudgets([quote.budget]);
+    if (quote.reservationTtlMs !== undefined) {
+        assertPositiveInteger(quote.reservationTtlMs, 'reservationTtlMs');
+    }
+    return {
+        decision: 'allow',
+        units: quote.units,
+        budgets,
+        ...(quote.reservationTtlMs === undefined
+            ? {}
+            : { reservationTtlMs: quote.reservationTtlMs }),
+    };
+}
+function normalizeVectorUsagePolicyQuote(value) {
+    const quote = requireRecord(value, 'Vector usage policy quote');
+    if (quote.decision === 'deny') {
+        return { decision: 'deny', reason: validatePolicyDenialReason(quote.reason) };
+    }
+    if (quote.decision !== 'allow') {
+        throw new TypeError('Vector usage policy quote decision must be allow or deny');
+    }
+    if (!Array.isArray(quote.dimensions)) {
+        throw new TypeError('Vector usage policy allow quote dimensions must be an array');
+    }
+    const dimensions = canonicalizeUsageDimensions(quote.dimensions);
+    if (quote.reservationTtlMs !== undefined) {
+        assertPositiveInteger(quote.reservationTtlMs, 'reservationTtlMs');
+    }
+    return {
+        decision: 'allow',
+        dimensions,
+        ...(quote.reservationTtlMs === undefined
+            ? {}
+            : { reservationTtlMs: quote.reservationTtlMs }),
+    };
+}
+function validatePolicyDenialReason(value) {
+    if (typeof value !== 'string' ||
+        value.length === 0 ||
+        value.length > MAX_POLICY_DENIAL_REASON_LENGTH) {
+        throw new TypeError(`Usage policy denial reason must be a non-empty string no longer than ${MAX_POLICY_DENIAL_REASON_LENGTH} characters`);
+    }
+    return value;
+}
+function validateStoreReserveResult(value, request, units, budgets) {
+    const result = requireStoreResult(value, 'reserve');
+    if (result.accepted === false) {
+        validateReserveDenial(result, false);
+        return result;
+    }
+    validateScalarAcceptedReservation(result, request, units, budgets);
+    return result;
+}
+function validateStoreVectorReserveResult(value, request, dimensions) {
+    const result = requireStoreResult(value, 'vector reserve');
+    if (result.accepted === false) {
+        validateReserveDenial(result, true);
+        return result;
+    }
+    validateVectorAcceptedReservation(result, request, dimensions);
+    return result;
+}
+function validateStoreGrowthResult(value, reservation, request) {
+    const result = requireStoreResult(value, 'growth');
+    validateGrowthCommon(result, reservation.id, request.incrementId);
+    if (result.accepted === false) {
+        if (result.reason !== 'quota_exceeded') {
+            throw new TypeError('UsageStore growth denial reason is invalid');
+        }
+        validateNonEmptyString(result.limitingBudgetKey, 'UsageStore growth limitingBudgetKey');
+        assertNonNegativeStoreInteger(result.remaining, 'UsageStore growth remaining');
+        if (!request.budgets.some(budget => budget.key === result.limitingBudgetKey)) {
+            throw new TypeError('UsageStore growth limiting budget did not match the request');
+        }
+        return result;
+    }
+    assertNonNegativeStoreInteger(result.previousReservedUnits, 'UsageStore growth previousReservedUnits');
+    assertNonNegativeStoreInteger(result.reservedUnits, 'UsageStore growth reservedUnits');
+    if (result.previousReservedUnits !== reservation.reservedUnits) {
+        throw new TypeError('UsageStore growth previous reservation units did not match local state');
+    }
+    const expectedReservedUnits = safeAdd(reservation.reservedUnits, request.additionalUnits, 'expected growth reservedUnits');
+    if (result.reservedUnits !== expectedReservedUnits) {
+        throw new TypeError('UsageStore growth reserved units did not match the requested increment');
+    }
+    validateBudgetRemainingTopology(result.remainingByBudget, request.budgets.map(budget => budget.key), 'UsageStore growth remainingByBudget');
+    return result;
+}
+function validateStoreVectorGrowthResult(value, reservation, request) {
+    const result = requireStoreResult(value, 'vector growth');
+    validateGrowthCommon(result, reservation.id, request.incrementId);
+    if (result.accepted === false) {
+        if (result.reason !== 'quota_exceeded') {
+            throw new TypeError('UsageStore vector growth denial reason is invalid');
+        }
+        validateNonEmptyString(result.limitingDimensionKey, 'UsageStore vector growth limitingDimensionKey');
+        validateNonEmptyString(result.limitingBudgetKey, 'UsageStore vector growth limitingBudgetKey');
+        assertNonNegativeStoreInteger(result.remaining, 'UsageStore vector growth remaining');
+        const dimension = request.dimensions.find(item => item.key === result.limitingDimensionKey);
+        if (!dimension?.budgets.some(budget => budget.key === result.limitingBudgetKey)) {
+            throw new TypeError('UsageStore vector growth limiting topology did not match the request');
+        }
+        return result;
+    }
+    validateReservedDimensionTopology(result.previousReservedByDimension, reservation.dimensions.map(dimension => ({
+        key: dimension.key,
+        reservedUnits: dimension.reservedUnits,
+    })), 'UsageStore vector growth previousReservedByDimension');
+    const growthByKey = new Map(request.dimensions.map(dimension => [dimension.key, dimension]));
+    validateReservedDimensionTopology(result.reservedByDimension, reservation.dimensions.map(dimension => ({
+        key: dimension.key,
+        reservedUnits: safeAdd(dimension.reservedUnits, growthByKey.get(dimension.key)?.additionalUnits ?? 0, 'expected vector growth reservedUnits'),
+    })), 'UsageStore vector growth reservedByDimension');
+    validateVectorRemainingTopology(result.remainingByBudget, request.dimensions, 'UsageStore vector growth remainingByBudget');
+    return result;
+}
+function requireStoreResult(value, operation) {
+    const result = requireRecord(value, `UsageStore ${operation} result`);
+    if (typeof result.accepted !== 'boolean') {
+        throw new TypeError(`UsageStore ${operation} result accepted must be a boolean`);
+    }
+    return result;
+}
+function validateGrowthCommon(result, reservationId, incrementId) {
+    if (typeof result.replayed !== 'boolean') {
+        throw new TypeError('UsageStore growth replayed must be a boolean');
+    }
+    if (result.reservationId !== reservationId || result.incrementId !== incrementId) {
+        throw new TypeError('UsageStore growth result identity did not match the request');
+    }
+    validateNonEmptyString(result.growthCursor, 'UsageStore growthCursor');
+}
+function validateReserveDenial(result, vector) {
+    if (result.reason !== 'quota_exceeded' && result.reason !== 'duplicate_operation') {
+        throw new TypeError('UsageStore reserve denial reason is invalid');
+    }
+    if (result.limitingBudgetKey !== undefined) {
+        validateNonEmptyString(result.limitingBudgetKey, 'UsageStore limitingBudgetKey');
+    }
+    if (vector && result.limitingDimensionKey !== undefined) {
+        validateNonEmptyString(result.limitingDimensionKey, 'UsageStore limitingDimensionKey');
+    }
+    if (result.remaining !== undefined) {
+        assertNonNegativeStoreInteger(result.remaining, 'UsageStore remaining');
+    }
+}
+function validateScalarAcceptedReservation(result, request, units, budgets) {
+    const reservation = requireRecord(result.reservation, 'UsageStore accepted reservation');
+    validateNonEmptyString(reservation.id, 'UsageStore reservation id');
+    if (reservation.operationId !== request.operationId ||
+        reservation.principalId !== request.principal.id ||
+        reservation.tenantId !== request.principal.tenantId ||
+        reservation.plan !== request.principal.plan ||
+        reservation.tool !== request.tool) {
+        throw new TypeError('UsageStore accepted reservation identity did not match the request');
+    }
+    assertNonNegativeStoreInteger(reservation.reservedUnits, 'UsageStore reservation reservedUnits');
+    if (reservation.reservedUnits !== units) {
+        throw new TypeError('UsageStore accepted reservation units did not match the request');
+    }
+    assertPositiveStoreInteger(reservation.expiresAt, 'UsageStore reservation expiresAt');
+    validateOptionalNonEmptyString(reservation.growthCursor, 'UsageStore reservation growthCursor');
+    validateStringSet(reservation.budgetKeys, budgets.map(budget => budget.key), 'UsageStore reservation budgetKeys');
+    validateBudgetRemainingTopology(result.remainingByBudget, budgets.map(budget => budget.key), 'UsageStore remainingByBudget');
+}
+function validateVectorAcceptedReservation(result, request, dimensions) {
+    const reservation = requireRecord(result.reservation, 'UsageStore accepted vector reservation');
+    validateNonEmptyString(reservation.id, 'UsageStore vector reservation id');
+    if (reservation.operationId !== request.operationId ||
+        reservation.principalId !== request.principal.id ||
+        reservation.tenantId !== request.principal.tenantId ||
+        reservation.plan !== request.principal.plan ||
+        reservation.tool !== request.tool) {
+        throw new TypeError('UsageStore accepted vector reservation identity did not match the request');
+    }
+    assertPositiveStoreInteger(reservation.expiresAt, 'UsageStore vector reservation expiresAt');
+    validateOptionalNonEmptyString(reservation.growthCursor, 'UsageStore vector reservation growthCursor');
+    if (!Array.isArray(reservation.dimensions) || reservation.dimensions.length !== dimensions.length) {
+        throw new TypeError('UsageStore accepted vector reservation dimensions did not match the request');
+    }
+    const expectedByKey = new Map(dimensions.map(dimension => [dimension.key, dimension]));
+    const seen = new Set();
+    for (const raw of reservation.dimensions) {
+        const dimension = requireRecord(raw, 'UsageStore vector reservation dimension');
+        validateNonEmptyString(dimension.key, 'UsageStore vector reservation dimension key');
+        const expected = expectedByKey.get(dimension.key);
+        if (!expected || seen.has(dimension.key)) {
+            throw new TypeError('UsageStore accepted vector reservation topology did not match the request');
+        }
+        seen.add(dimension.key);
+        assertNonNegativeStoreInteger(dimension.reservedUnits, 'UsageStore vector reservation reservedUnits');
+        if (dimension.reservedUnits !== expected.units) {
+            throw new TypeError('UsageStore accepted vector reservation units did not match the request');
+        }
+        validateStringSet(dimension.budgetKeys, expected.budgets.map(budget => budget.key), 'UsageStore vector reservation budgetKeys');
+    }
+    validateVectorRemainingTopology(result.remainingByBudget, dimensions, 'UsageStore vector remainingByBudget');
+}
+function validateBudgetRemainingTopology(value, expectedKeys, name) {
+    if (!Array.isArray(value) || value.length !== expectedKeys.length) {
+        throw new TypeError(`${name} did not match requested budgets`);
+    }
+    const expected = new Set(expectedKeys);
+    const seen = new Set();
+    for (const raw of value) {
+        const balance = requireRecord(raw, name);
+        validateNonEmptyString(balance.key, `${name} key`);
+        if (!expected.has(balance.key) || seen.has(balance.key)) {
+            throw new TypeError(`${name} did not match requested budgets`);
+        }
+        seen.add(balance.key);
+        assertNonNegativeStoreInteger(balance.remaining, `${name} remaining`);
+    }
+}
+function validateVectorRemainingTopology(value, dimensions, name) {
+    const expected = new Set(dimensions.flatMap(dimension => dimension.budgets.map(budget => `${dimension.key}\u0000${budget.key}`)));
+    if (!Array.isArray(value) || value.length !== expected.size) {
+        throw new TypeError(`${name} did not match requested vector budgets`);
+    }
+    const seen = new Set();
+    for (const raw of value) {
+        const balance = requireRecord(raw, name);
+        validateNonEmptyString(balance.dimensionKey, `${name} dimensionKey`);
+        validateNonEmptyString(balance.budgetKey, `${name} budgetKey`);
+        const key = `${balance.dimensionKey}\u0000${balance.budgetKey}`;
+        if (!expected.has(key) || seen.has(key)) {
+            throw new TypeError(`${name} did not match requested vector budgets`);
+        }
+        seen.add(key);
+        assertNonNegativeStoreInteger(balance.remaining, `${name} remaining`);
+    }
+}
+function validateReservedDimensionTopology(value, expected, name) {
+    if (!Array.isArray(value) || value.length !== expected.length) {
+        throw new TypeError(`${name} did not match reservation dimensions`);
+    }
+    const expectedByKey = new Map(expected.map(dimension => [dimension.key, dimension.reservedUnits]));
+    const seen = new Set();
+    for (const raw of value) {
+        const dimension = requireRecord(raw, name);
+        validateNonEmptyString(dimension.key, `${name} key`);
+        assertNonNegativeStoreInteger(dimension.reservedUnits, `${name} reservedUnits`);
+        if (seen.has(dimension.key) ||
+            expectedByKey.get(dimension.key) !== dimension.reservedUnits) {
+            throw new TypeError(`${name} did not match reservation dimensions`);
+        }
+        seen.add(dimension.key);
+    }
+}
+function validateStringSet(value, expected, name) {
+    if (!Array.isArray(value) || value.length !== expected.length) {
+        throw new TypeError(`${name} did not match requested identifiers`);
+    }
+    const expectedSet = new Set(expected);
+    const seen = new Set();
+    for (const item of value) {
+        validateNonEmptyString(item, name);
+        if (!expectedSet.has(item) || seen.has(item)) {
+            throw new TypeError(`${name} did not match requested identifiers`);
+        }
+        seen.add(item);
+    }
+}
+function requireRecord(value, name) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new TypeError(`${name} must be an object`);
+    }
+    return value;
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function validateNonEmptyString(value, name) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new TypeError(`${name} must be a non-empty string`);
+    }
+}
+function validateOptionalNonEmptyString(value, name) {
+    if (value !== undefined)
+        validateNonEmptyString(value, name);
+}
+function assertNonNegativeStoreInteger(value, name) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(`${name} must be a non-negative safe integer`);
+    }
+}
+function assertPositiveStoreInteger(value, name) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+        throw new TypeError(`${name} must be a positive safe integer`);
+    }
+}
+function canonicalizeBudgets(budgets) {
+    validateUsageBudgetEnvelope(budgets);
+    const normalized = budgets.map(budget => {
+        if (budget === null || typeof budget !== 'object' || Array.isArray(budget)) {
+            throw new TypeError('budget must be an object');
+        }
+        if (typeof budget.key !== 'string' || budget.key.length === 0) {
+            throw new RangeError('budget.key must be a non-empty string');
+        }
+        assertNonNegativeInteger(budget.limit, `budget.limit (${budget.key})`);
+        return { key: budget.key, limit: budget.limit };
+    });
+    normalized.sort((a, b) => a.key.localeCompare(b.key));
+    for (let i = 1; i < normalized.length; i += 1) {
+        if (normalized[i - 1].key === normalized[i].key) {
+            throw new RangeError(`duplicate budget key: ${normalized[i].key}`);
+        }
+    }
+    return normalized;
+}
+function validateRequestIdentity(request) {
+    validateUsageRequestEnvelope(request);
+}
+function cloneReservationRecord(reservation) {
+    if (typeof reservation.id !== 'string' || reservation.id.length === 0) {
+        throw new UsageStateError('Resume reservation id must be non-empty');
+    }
+    if (typeof reservation.operationId !== 'string' || reservation.operationId.length === 0) {
+        throw new UsageStateError('Resume operationId must be non-empty');
+    }
+    if (typeof reservation.principalId !== 'string' || reservation.principalId.length === 0) {
+        throw new UsageStateError('Resume principalId must be non-empty');
+    }
+    if (typeof reservation.tool !== 'string' || reservation.tool.length === 0) {
+        throw new UsageStateError('Resume tool must be non-empty');
+    }
+    if (!Array.isArray(reservation.budgetKeys) || reservation.budgetKeys.length === 0) {
+        throw new UsageStateError('Resume reservation must contain budget keys');
+    }
+    if (reservation.budgetKeys.some(key => typeof key !== 'string' || key.length === 0)) {
+        throw new UsageStateError('Resume budget keys must be non-empty strings');
+    }
+    assertNonNegativeInteger(reservation.reservedUnits, 'reservedUnits');
+    assertPositiveInteger(reservation.expiresAt, 'expiresAt');
+    if (reservation.growthCursor !== undefined &&
+        (typeof reservation.growthCursor !== 'string' || reservation.growthCursor.length === 0)) {
+        throw new UsageStateError('Resume growthCursor must be a non-empty string when present');
+    }
+    return {
+        id: reservation.id,
+        operationId: reservation.operationId,
+        principalId: reservation.principalId,
+        ...(reservation.tenantId === undefined ? {} : { tenantId: reservation.tenantId }),
+        ...(reservation.plan === undefined ? {} : { plan: reservation.plan }),
+        tool: reservation.tool,
+        budgetKeys: [...reservation.budgetKeys],
+        reservedUnits: reservation.reservedUnits,
+        expiresAt: reservation.expiresAt,
+        ...(reservation.growthCursor === undefined
+            ? {}
+            : { growthCursor: reservation.growthCursor }),
+    };
+}
+function isProgressiveUsageStore(store) {
+    return typeof store.growReservation === 'function';
+}
+function isVectorUsageStore(store) {
+    const candidate = store;
+    return (typeof candidate.reserveVector === 'function' &&
+        typeof candidate.growVectorReservation === 'function' &&
+        typeof candidate.settleVector === 'function');
+}
+function canonicalizeUsageDimensions(dimensions) {
+    validateUsageVectorEnvelope(dimensions);
+    const normalized = dimensions.map(dimension => {
+        if (dimension === null || typeof dimension !== 'object' || Array.isArray(dimension)) {
+            throw new TypeError('dimension must be an object');
+        }
+        if (typeof dimension.key !== 'string' || dimension.key.length === 0) {
+            throw new RangeError('dimension.key must be a non-empty string');
+        }
+        assertNonNegativeInteger(dimension.units, `dimension.units (${dimension.key})`);
+        return {
+            key: dimension.key,
+            units: dimension.units,
+            budgets: canonicalizeBudgets(dimension.budgets),
+        };
+    });
+    normalized.sort((a, b) => a.key.localeCompare(b.key));
+    assertUniqueVectorTopology(normalized.map(dimension => ({
+        key: dimension.key,
+        budgets: dimension.budgets,
+    })));
+    return normalized;
+}
+function canonicalizeVectorGrowthDimensions(dimensions) {
+    validateUsageVectorGrowthEnvelope(dimensions);
+    const normalized = dimensions.map(dimension => {
+        if (typeof dimension.key !== 'string' || dimension.key.length === 0) {
+            throw new RangeError('dimension.key must be a non-empty string');
+        }
+        assertNonNegativeInteger(dimension.additionalUnits, `dimension.additionalUnits (${dimension.key})`);
+        return {
+            key: dimension.key,
+            additionalUnits: dimension.additionalUnits,
+            budgets: canonicalizeBudgets(dimension.budgets),
+        };
+    });
+    normalized.sort((a, b) => a.key.localeCompare(b.key));
+    assertUniqueVectorTopology(normalized.map(dimension => ({
+        key: dimension.key,
+        budgets: dimension.budgets,
+    })));
+    if (!normalized.some(dimension => dimension.additionalUnits > 0)) {
+        throw new RangeError('vector growth must add units to at least one dimension');
+    }
+    return normalized;
+}
+function assertUniqueVectorTopology(dimensions) {
+    const dimensionKeys = new Set();
+    const budgetKeys = new Set();
+    for (const dimension of dimensions) {
+        if (dimensionKeys.has(dimension.key)) {
+            throw new RangeError(`duplicate dimension key: ${dimension.key}`);
+        }
+        dimensionKeys.add(dimension.key);
+        for (const budget of dimension.budgets) {
+            if (budgetKeys.has(budget.key)) {
+                throw new RangeError(`budget key cannot appear in multiple vector dimensions: ${budget.key}`);
+            }
+            budgetKeys.add(budget.key);
+        }
+    }
+}
+function cloneVectorReservationRecord(reservation) {
+    if (typeof reservation.id !== 'string' || reservation.id.length === 0) {
+        throw new UsageStateError('Resume vector reservation id must be non-empty');
+    }
+    if (typeof reservation.operationId !== 'string' || reservation.operationId.length === 0) {
+        throw new UsageStateError('Resume vector operationId must be non-empty');
+    }
+    if (typeof reservation.principalId !== 'string' || reservation.principalId.length === 0) {
+        throw new UsageStateError('Resume vector principalId must be non-empty');
+    }
+    if (typeof reservation.tool !== 'string' || reservation.tool.length === 0) {
+        throw new UsageStateError('Resume vector tool must be non-empty');
+    }
+    if (!Array.isArray(reservation.dimensions) || reservation.dimensions.length === 0) {
+        throw new UsageStateError('Resume vector reservation must contain dimensions');
+    }
+    const dimensions = reservation.dimensions.map(dimension => {
+        if (typeof dimension.key !== 'string' || dimension.key.length === 0) {
+            throw new UsageStateError('Resume vector dimension keys must be non-empty strings');
+        }
+        if (!Array.isArray(dimension.budgetKeys) || dimension.budgetKeys.length === 0) {
+            throw new UsageStateError('Resume vector dimension must contain budget keys');
+        }
+        if (dimension.budgetKeys.some(key => typeof key !== 'string' || key.length === 0)) {
+            throw new UsageStateError('Resume vector budget keys must be non-empty strings');
+        }
+        assertNonNegativeInteger(dimension.reservedUnits, `reservedUnits (${dimension.key})`);
+        return {
+            key: dimension.key,
+            budgetKeys: [...dimension.budgetKeys].sort((a, b) => a.localeCompare(b)),
+            reservedUnits: dimension.reservedUnits,
+        };
+    });
+    dimensions.sort((a, b) => a.key.localeCompare(b.key));
+    assertUniqueVectorTopology(dimensions.map(dimension => ({
+        key: dimension.key,
+        budgets: dimension.budgetKeys.map(key => ({ key, limit: 0 })),
+    })));
+    assertPositiveInteger(reservation.expiresAt, 'expiresAt');
+    if (reservation.growthCursor !== undefined &&
+        (typeof reservation.growthCursor !== 'string' || reservation.growthCursor.length === 0)) {
+        throw new UsageStateError('Resume vector growthCursor must be a non-empty string when present');
+    }
+    return {
+        id: reservation.id,
+        operationId: reservation.operationId,
+        principalId: reservation.principalId,
+        ...(reservation.tenantId === undefined ? {} : { tenantId: reservation.tenantId }),
+        ...(reservation.plan === undefined ? {} : { plan: reservation.plan }),
+        tool: reservation.tool,
+        dimensions,
+        expiresAt: reservation.expiresAt,
+        ...(reservation.growthCursor === undefined ? {} : { growthCursor: reservation.growthCursor }),
+    };
+}
+function canonicalizeVectorGrowthRequest(input) {
+    if (typeof input.incrementId !== 'string' || input.incrementId.length === 0) {
+        throw new RangeError('incrementId must be a non-empty string');
+    }
+    return {
+        incrementId: input.incrementId,
+        dimensions: canonicalizeVectorGrowthDimensions(input.dimensions),
+    };
+}
+function cloneVectorGrowthRequest(input) {
+    return {
+        incrementId: input.incrementId,
+        dimensions: input.dimensions.map(dimension => ({
+            key: dimension.key,
+            additionalUnits: dimension.additionalUnits,
+            budgets: dimension.budgets.map(budget => ({ ...budget })),
+        })),
+    };
+}
+function sameVectorGrowthRequest(left, right) {
+    return (left.incrementId === right.incrementId &&
+        vectorGrowthFingerprint(left.dimensions) === vectorGrowthFingerprint(right.dimensions));
+}
+function vectorGrowthFingerprint(dimensions) {
+    return JSON.stringify(dimensions.map(dimension => [
+        dimension.key,
+        dimension.additionalUnits,
+        dimension.budgets.map(budget => [budget.key, budget.limit]),
+    ]));
+}
+function canonicalizeVectorActuals(actualByDimension, reservedDimensions) {
+    if (actualByDimension.length !== reservedDimensions.length) {
+        throw new UsageStateError('Vector settlement must report every reservation dimension exactly once');
+    }
+    const normalized = actualByDimension.map(item => {
+        if (typeof item.key !== 'string' || item.key.length === 0) {
+            throw new RangeError('actual dimension key must be a non-empty string');
+        }
+        assertNonNegativeInteger(item.actualUnits, `actualUnits (${item.key})`);
+        return { key: item.key, actualUnits: item.actualUnits };
+    });
+    normalized.sort((a, b) => a.key.localeCompare(b.key));
+    for (let index = 0; index < normalized.length; index += 1) {
+        const actual = normalized[index];
+        const reserved = reservedDimensions[index];
+        if (actual.key !== reserved.key) {
+            throw new UsageStateError('Vector settlement dimension keys do not match the reservation');
+        }
+        if (actual.actualUnits > reserved.reservedUnits) {
+            throw new UsageStateError(`actualUnits cannot exceed reservedUnits for dimension ${actual.key}`);
+        }
+    }
+    return normalized;
+}
+function canonicalizeGrowthRequest(input) {
+    if (typeof input.incrementId !== 'string' || input.incrementId.length === 0) {
+        throw new RangeError('incrementId must be a non-empty string');
+    }
+    assertPositiveInteger(input.additionalUnits, 'additionalUnits');
+    return {
+        incrementId: input.incrementId,
+        additionalUnits: input.additionalUnits,
+        budgets: canonicalizeBudgets(input.budgets),
+    };
+}
+function cloneGrowthRequest(input) {
+    return {
+        incrementId: input.incrementId,
+        additionalUnits: input.additionalUnits,
+        budgets: input.budgets.map(budget => ({ ...budget })),
+    };
+}
+function sameGrowthRequest(left, right) {
+    return (left.incrementId === right.incrementId &&
+        growthFingerprint(left.additionalUnits, left.budgets) ===
+            growthFingerprint(right.additionalUnits, right.budgets));
+}
+function validateGrowthInput(input) {
+    assertUsageIdentifier(input.reservationId, 'reservationId');
+    assertUsageIdentifier(input.incrementId, 'incrementId');
+    assertUsageIdentifier(input.expectedGrowthCursor, 'expectedGrowthCursor');
+    assertPositiveInteger(input.additionalUnits, 'additionalUnits');
+}
+function growthFingerprint(additionalUnits, budgets) {
+    return JSON.stringify([additionalUnits, budgets.map(budget => [budget.key, budget.limit])]);
+}
+function sameBudgetKeys(reservationBudgetKeys, budgets) {
+    return (reservationBudgetKeys.length === budgets.length &&
+        reservationBudgetKeys.every((key, index) => key === budgets[index].key));
+}
+function newGrowthCursor() {
+    return `g1.${randomUUID()}`;
+}
+function replayGrowthResult(result) {
+    return { ...cloneGrowthResult(result), replayed: true };
+}
+function cloneGrowthResult(result) {
+    if (result.accepted) {
+        return {
+            ...result,
+            remainingByBudget: result.remainingByBudget.map(balance => ({ ...balance })),
+        };
+    }
+    return { ...result };
+}
+function safeAdd(left, right, name) {
+    const result = left + right;
+    if (!Number.isSafeInteger(result) || result < 0) {
+        throw new RangeError(`${name} exceeds safe integer range`);
+    }
+    return result;
+}
+function requestIdentity(request) {
+    return {
+        principalId: request.principal.id,
+        ...(request.principal.tenantId === undefined ? {} : { tenantId: request.principal.tenantId }),
+        ...(request.principal.plan === undefined ? {} : { plan: request.principal.plan }),
+        tool: request.tool,
+        operationId: request.operationId,
+    };
+}
+function vectorReservationIdentity(reservation) {
+    return {
+        principalId: reservation.principalId,
+        ...(reservation.tenantId === undefined ? {} : { tenantId: reservation.tenantId }),
+        ...(reservation.plan === undefined ? {} : { plan: reservation.plan }),
+        tool: reservation.tool,
+        operationId: reservation.operationId,
+    };
+}
+function reservationIdentity(reservation) {
+    return {
+        principalId: reservation.principalId,
+        ...(reservation.tenantId === undefined ? {} : { tenantId: reservation.tenantId }),
+        ...(reservation.plan === undefined ? {} : { plan: reservation.plan }),
+        tool: reservation.tool,
+        operationId: reservation.operationId,
+    };
+}
+function resolveMetadata(metadata, request) {
+    if (!metadata)
+        return undefined;
+    if (typeof metadata !== 'function')
+        return metadata;
+    try {
+        return metadata(request);
+    }
+    catch {
+        return undefined;
+    }
+}
+function toSettlement(reservation) {
+    const actualUnits = reservation.actualUnits ?? reservation.reservedUnits;
+    return {
+        reservationId: reservation.id,
+        reservedUnits: reservation.reservedUnits,
+        actualUnits,
+        releasedUnits: reservation.reservedUnits - actualUnits,
+        outcome: reservation.outcome ?? 'unknown',
+    };
+}
+function assertNonNegativeInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError(`${name} must be a non-negative safe integer`);
+    }
+}
+function assertPositiveInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RangeError(`${name} must be a positive safe integer`);
+    }
+}
+//# sourceMappingURL=index.js.map