@cortexkit/antigravity-auth-core 3.0.9 → 3.0.11

package/dist/common-auth-embedded/claustrum/roster.js

@@ -1,9 +1,12 @@
 import { createHash } from 'node:crypto';
-import { acquireRefreshFileLock, withLock, writeJsonAtomic, } from '../fs/index.js';
+import { resolve } from 'node:path';
+import { acquireRefreshFileLock, LockContentionError, withLock, writeJsonAtomic, } from '../fs/index.js';
 import { readPrivateText, windowsPrivateFiles } from '../fs/private-files.js';
-import { decodeQuotaMap, mergeQuotaObservation, } from '../quota/index.js';
+import { decodeQuotaMap, isQuotaObservation, mergeQuotaObservation, } from '../quota/index.js';
 import { ClaustrumConsumerError } from './errors.js';
 import { acceptAccount, declineAccount, isDeclined, } from './interlock.js';
+import { enqueueVaultQuota, pendingVaultQuota, } from './quota-writer.js';
+export { drainVaultQuota } from './quota-writer.js';
 export const DEFAULT_ROUTE_PREFIX = 'vault:';
 function hash(value) {
     return createHash('sha256').update(value).digest('hex');
@@ -313,6 +316,7 @@ const WRITE_LOCK = {
     name: 'claustrum-roster-write',
     ttlMs: 10_000,
     timeoutMs: 5_000,
+    renew: true,
 };
 const DISCOVERY_LEASE = { name: 'claustrum-roster', ttlMs: 30_000 };
 /**
@@ -321,7 +325,7 @@ const DISCOVERY_LEASE = { name: 'claustrum-roster', ttlMs: 30_000 };
  * before any rename performed inside `change`; if it throws, do not rename.
  */
 export async function mutateVaultRoster(path, change, options = {}) {
-    return withLock(path, WRITE_LOCK, async (lock) => {
+    return withLock(path, { ...WRITE_LOCK, signal: options.signal }, async (lock) => {
         const current = await readVaultRoster(path);
         const { next, result } = await change(current, {
             assertOwned: () => lock.assertOwned(),
@@ -333,6 +337,7 @@ export async function mutateVaultRoster(path, change, options = {}) {
             await writeJsonAtomic(path, next, {
                 beforeRename: async () => {
                     await options.beforePublish?.();
+                    options.signal?.throwIfAborted();
                     await lock.assertOwned();
                 },
             });
@@ -415,55 +420,73 @@ function receiptFence(row, receipt) {
  * write is fenced on the receipt the reading was taken with: it lands only
  * while the row still holds that receipt's credential (as representative or
  * alias) and account, so a slow read for a replaced account can never land on
- * its successor. Returns whether the observation was kept.
+ * its successor. Resolves false when the fence refuses the reading against the
+ * roster as it stands now (on disk, plus readings this process has not
+ * written yet), and true once the reading is queued for the next write. The
+ * write applies the fence again, so a rebind between the two still refuses.
  */
-export function recordVaultQuota(path, input) {
-    return mutateVaultRoster(path, (current) => {
-        const row = current?.rows.find((entry) => entry.routeId === input.routeId);
-        const fence = !current || !row ? 'refuse' : receiptFence(row, input);
-        if (!current || !row || fence === 'refuse')
-            return { result: false };
-        const quota = mergeQuotaObservation(row.quota, input.observation);
-        // A bound account is `unclaimed`: the vault's list has not named it, and
-        // the next projection keeps it as the account this credential last
-        // logged into until the vault names one.
-        const bound = fence === 'bind'
-            ? { accountIdentity: input.accountIdentity, unclaimed: true }
-            : {};
-        return {
-            next: {
-                ...current,
-                rows: current.rows.map((entry) => entry === row ? { ...entry, ...bound, quota } : entry),
-            },
-            result: true,
-        };
+export async function recordVaultQuota(path, input) {
+    const { routeId, observation, ...receipt } = input;
+    return enqueueFencedVaultQuota(path, {
+        routeId,
+        observation,
+        accountIdentity: receipt.accountIdentity,
+        receipt,
     });
 }
+// The answer callers rely on (false for a replaced account) comes from the
+// fence, so it runs here against the current roster before anything is
+// queued. The read takes no lock: the roster file is replaced atomically.
+async function enqueueFencedVaultQuota(path, publication) {
+    if (!isQuotaObservation(publication.observation))
+        return false;
+    const current = pendingVaultQuota(path, await readVaultRoster(path));
+    if (!applyVaultQuota(current, publication).kept)
+        return false;
+    return enqueueVaultQuota(path, publication);
+}
 /**
  * Merge a quota observation that belongs to an account rather than to a
  * served credential, such as a background reading from insula. The write
  * lands only while the row is still bound to that exact known account, so a
  * reading taken before a replacement never reaches the successor. Unlike
  * `recordVaultQuota` it never binds an account: a row without a known account
- * is refused. Returns whether the observation was kept.
+ * is refused. Resolves false when the row is not bound to that account now,
+ * and true once the reading is queued, as `recordVaultQuota` does.
  */
 export function recordVaultAccountQuota(path, input) {
-    return mutateVaultRoster(path, (current) => {
-        const row = current?.rows.find((entry) => entry.routeId === input.routeId);
-        if (!current ||
-            !row ||
-            row.accountIdentity === undefined ||
-            row.accountIdentity !== input.accountIdentity)
-            return { result: false };
-        const quota = mergeQuotaObservation(row.quota, input.observation);
-        return {
-            next: {
-                ...current,
-                rows: current.rows.map((entry) => entry === row ? { ...entry, quota } : entry),
-            },
-            result: true,
-        };
-    });
+    return enqueueFencedVaultQuota(path, input);
+}
+/** Apply the same identity fence to memory overlays and durable quota batches. */
+export function applyVaultQuota(current, input) {
+    const row = current?.rows.find((entry) => entry.routeId === input.routeId);
+    const fence = !row
+        ? 'refuse'
+        : input.receipt
+            ? receiptFence(row, input.receipt)
+            : row.accountIdentity !== undefined &&
+                row.accountIdentity === input.accountIdentity
+                ? 'hold'
+                : 'refuse';
+    if (!current || !row || fence === 'refuse')
+        return { roster: current, kept: false };
+    const quota = mergeQuotaObservation(row.quota, input.observation);
+    // Binding remembers which account this credential proved, without claiming
+    // that the vault's discovery has named that account yet.
+    const bound = fence === 'bind'
+        ? { accountIdentity: input.accountIdentity, unclaimed: true }
+        : {};
+    return {
+        roster: {
+            ...current,
+            rows: current.rows.map((entry) => entry === row ? { ...entry, ...bound, quota } : entry),
+        },
+        kept: true,
+    };
+}
+const pendingDiscoveries = new Map();
+export function forgetPendingVaultDiscovery(path) {
+    pendingDiscoveries.delete(resolve(path));
 }
 /**
  * Discover and commit the roster. The lease covers the list call and the
@@ -471,12 +494,16 @@ export function recordVaultAccountQuota(path, input) {
  * from a newer one, so a run that lost its lease is refused at commit. A
  * failed list, or custody switching off mid-run, never writes anything; a
  * peer holding the lease means its last committed roster is served instead.
+ * A write-lock timeout keeps the discovered inventory for the next poll,
+ * unless a peer has superseded its base view in the meantime.
  */
 export async function refreshVaultRoster(options) {
     options.signal?.throwIfAborted();
     const active = async () => (await options.isActive?.()) ?? true;
-    if (!(await active()))
+    if (!(await active())) {
+        forgetPendingVaultDiscovery(options.path);
         return undefined;
+    }
     const lease = await acquireRefreshFileLock({
         ...DISCOVERY_LEASE,
         path: options.path,
@@ -489,8 +516,25 @@ export async function refreshVaultRoster(options) {
             throw new ClaustrumConsumerError('roster-busy', 'Claustrum account discovery is already in progress');
         return persisted;
     }
+    const key = resolve(options.path);
+    let discovered;
     try {
-        const inventory = await options.custody.discover(options.signal);
+        const previous = await readVaultRoster(options.path);
+        const pending = pendingDiscoveries.get(key);
+        // Opaque view cursors cannot be ordered. Reuse a discovery only while no
+        // peer has committed a different view since it was read.
+        discovered =
+            pending &&
+                (pending.previousView === previous?.view ||
+                    pending.inventory.view === previous?.view)
+                ? pending
+                : {
+                    inventory: await options.custody.discover(options.signal),
+                    previousView: previous?.view,
+                };
+        pendingDiscoveries.delete(key);
+        const { inventory } = discovered;
+        options.onInventory?.(inventory);
         options.signal?.throwIfAborted();
         return await mutateVaultRoster(options.path, async (current) => {
             if (!(await active()))
@@ -503,8 +547,21 @@ export async function refreshVaultRoster(options) {
             const next = projectVaultRoster(current, inventory, projection);
             const changed = JSON.stringify(current) !== JSON.stringify(next);
             return { ...(changed && { next }), result: next };
+        }, {
+            beforePublish: async () => {
+                options.signal?.throwIfAborted();
+                await lease.assertOwned();
+            },
         });
     }
+    catch (error) {
+        if (error instanceof LockContentionError &&
+            discovered &&
+            !options.signal?.aborted &&
+            (await active()))
+            pendingDiscoveries.set(key, discovered);
+        throw error;
+    }
     finally {
         await lease.release();
     }

package/dist/common-auth-embedded/fs/private-files.d.ts

@@ -5,6 +5,8 @@ type Backend = typeof import('@cortexkit/private-files');
 type Kind = 'file' | 'directory';
 /** Tests inject a backend here; production always imports the private-files package. */
 export declare function setPrivateFilesBackendForTest(api?: Backend): void;
+/** The fixed `reason` of a refusal because the Windows native addon did not load. */
+export declare const PRIVATE_FILES_UNAVAILABLE_REASON = "native-addon-unavailable";
 export declare class PrivateFileError extends Error {
     readonly path: string;
     readonly stage: string;

package/dist/common-auth-embedded/fs/private-files.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { lstat, readFile, rename, unlink } from 'node:fs/promises';
-import { dirname, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
 export const windowsPrivateFiles = process.platform === 'win32';
 const migrationNotices = new Set();
 function ioCode(detail) {
@@ -20,8 +21,51 @@ let backend;
 export function setPrivateFilesBackendForTest(api) {
     backend = api ? Promise.resolve(api) : undefined;
 }
+/** The fixed `reason` of a refusal because the Windows native addon did not load. */
+export const PRIVATE_FILES_UNAVAILABLE_REASON = 'native-addon-unavailable';
+function privateFilesUnavailable(cause) {
+    return Object.assign(new Error('Windows private-files native addon is unavailable', { cause }), {
+        code: 'ERR_PRIVATE_FILES_UNAVAILABLE',
+        reason: PRIVATE_FILES_UNAVAILABLE_REASON,
+    });
+}
+function isUnavailable(api, error) {
+    return (error instanceof api.PrivateFilesUnavailableError ||
+        error?.code ===
+            'ERR_PRIVATE_FILES_UNAVAILABLE');
+}
+/**
+ * Importing @cortexkit/private-files succeeds even when its Windows addon
+ * cannot load: the package loads the addon on first use, and some of its
+ * checks then report the failure as an ordinary refusal such as
+ * `unsupported-filesystem`. So prove the addon loads before handing the
+ * package out. Verifying a path that does not exist loads the addon first and
+ * then fails harmlessly; only the package's own "unavailable" error means the
+ * addon is missing.
+ */
+async function assertNativeAddonLoads(api) {
+    try {
+        await api.verifyPrivatePath(join(tmpdir(), `.common-auth-private-files-probe-${randomUUID()}`), 'file');
+    }
+    catch (error) {
+        if (isUnavailable(api, error))
+            throw privateFilesUnavailable(error);
+    }
+}
+/**
+ * Load the package once per process. On Windows a failed import or addon load
+ * is kept, so every later private-file operation refuses at once with
+ * ERR_PRIVATE_FILES_UNAVAILABLE. There is no fallback to permission bits:
+ * they do not protect files on Windows.
+ */
 function loadBackend() {
-    backend ??= import('@cortexkit/private-files');
+    backend ??= import('@cortexkit/private-files').then(async (api) => {
+        if (windowsPrivateFiles)
+            await assertNativeAddonLoads(api);
+        return api;
+    }, (cause) => {
+        throw windowsPrivateFiles ? privateFilesUnavailable(cause) : cause;
+    });
     return backend;
 }
 export class PrivateFileError extends Error {
@@ -38,7 +82,9 @@ export class PrivateFileError extends Error {
     orphanPath;
     constructor(path, stage, cause) {
         const detail = cause;
-        super(`Private file refused at ${stage}: ${path} (${detail?.reason ?? detail?.code ?? 'io-error'}). Use a safe parent directory. Repair only a named secret file in safe ancestry whose owner the published policy trusts, without changing its owner or any existing directory. Previously exposed credentials may need rotation. Windows requires the private-files native prebuild and an ACL-persisting local filesystem such as NTFS.`, { cause });
+        super(detail?.code === 'ERR_PRIVATE_FILES_UNAVAILABLE'
+            ? `Private file refused at ${stage}: ${path} (${PRIVATE_FILES_UNAVAILABLE_REASON}). The Windows native addon of @cortexkit/private-files could not be loaded, so owner-only access cannot be enforced and nothing was read or written. Reinstall the plugin so the private-files Windows prebuild for this architecture is present; Windows has no safe fallback to permission bits.`
+            : `Private file refused at ${stage}: ${path} (${detail?.reason ?? detail?.code ?? 'io-error'}). Keep this file in a folder that only you, the system or administrators can change, such as a folder in your home directory. If other users could read the file before, sign in again to replace the credentials it held. On Windows the file must also be on a local drive that keeps Windows file permissions, such as NTFS.`, { cause });
         this.path = path;
         this.stage = stage;
         this.name = 'PrivateFileError';

package/dist/common-auth-embedded/fs/with-lock.d.ts

@@ -28,6 +28,7 @@ export interface LockOptions {
     ttlMs: number;
     timeoutMs: number;
     renew?: boolean;
+    signal?: AbortSignal;
     onStep?: Parameters<typeof acquireRefreshFileLock>[0]['onStep'];
     onRenewalTimer?: Parameters<typeof acquireRefreshFileLock>[0]['onRenewalTimer'];
 }

package/dist/common-auth-embedded/fs/with-lock.js

@@ -21,6 +21,7 @@ export class LockOwnershipError extends Error {
 export async function withLock(target, options, fn) {
     const started = performance.now();
     for (;;) {
+        options.signal?.throwIfAborted();
         const lock = await acquireRefreshFileLock({
             path: target,
             name: options.name,
@@ -33,6 +34,7 @@ export async function withLock(target, options, fn) {
         });
         if (lock) {
             try {
+                options.signal?.throwIfAborted();
                 return await fn(lock);
             }
             finally {

package/dist/common-auth-embedded/quota/format.d.ts

@@ -1,3 +1,4 @@
+import { type QuotaCredits } from './map.js';
 import type { ProjectedLimit, ProjectedQuota } from './projection.js';
 /** A reading older than this is marked with its age. */
 export declare const QUOTA_STALE_AFTER_MS: number;
@@ -31,6 +32,13 @@ export interface QuotaWindowPart {
     kind: 'window' | 'budget';
     /** The display name of a quota window, or `credits` for the budget. */
     name: string;
+    /**
+     * The label the narrow line gives this item: an account-wide window keeps
+     * its name (`5h`), a model-scoped window reads as its model's short name
+     * (`Fa` for Fable, extended until names in the same reading differ), and
+     * the budget reads `cr`. For layouts too narrow for the full name.
+     */
+    short: string;
     /** The shared figure wording, including `credits` for budget figures. */
     figure: string;
     /** The unrounded remaining percentage, clamped to 0–100, when known. */
@@ -84,3 +92,14 @@ export declare function quotaTextParts(quota: ProjectedQuota | undefined, option
  * provider answered without a limit for any window.
  */
 export declare function formatQuota(quota: ProjectedQuota | undefined, options: QuotaTextOptions): string;
+/**
+ * Prepaid credits as one short value, worded as the official Codex client's
+ * status view words them: `Unlimited` for unlimited credits, `<n> credits`
+ * for a finite positive balance (rounded to a whole number), `Available` when
+ * the account has credits but no usable balance was reported, and undefined
+ * when the account has no credits (or `credits` is undefined), so a caller
+ * shows no credits row at all. Unlimited wins even when `hasCredits` is false.
+ * No other formatter adds this text; a caller that wants a credits row asks
+ * for it.
+ */
+export declare function quotaCreditsText(credits: Pick<QuotaCredits, 'hasCredits' | 'unlimited' | 'balance'> | undefined): string | undefined;

package/dist/common-auth-embedded/quota/format.js

@@ -106,6 +106,25 @@ export function quotaWindowParts(quota, options) {
     const parts = windows.map(({ part }) => part);
     return age === undefined ? { windows: parts } : { windows: parts, age };
 }
+/**
+ * The narrow label of each scoped window part, as `narrowTextParts` names
+ * them: model short names are worked out over every model-scoped window in
+ * the reading, so two models never share a short name.
+ */
+function withShortNames(windows) {
+    const abbreviations = scopeAbbreviations(windows
+        .filter(({ part, scope }) => part.kind === 'window' && scope !== ALL_SCOPE)
+        .map(({ scope }) => scope));
+    for (const window of windows) {
+        window.part.short =
+            window.part.kind === 'budget'
+                ? 'cr'
+                : window.scope === ALL_SCOPE
+                    ? window.part.name
+                    : (abbreviations.get(window.scope) ?? window.scope);
+    }
+    return windows;
+}
 /**
  * `quotaWindowParts` with each window's scope kept beside it. The narrow form
  * needs the scope to name and pick model-scoped windows; the public parts do
@@ -128,6 +147,7 @@ function scopedWindowParts(quota, options) {
             part: {
                 kind: 'window',
                 name: quotaWindowName(limit),
+                short: '',
                 figure: percentLeft(limit.remainingPercent ?? 0),
                 remainingPercent,
                 checkedAt: limit.checkedAt,
@@ -149,6 +169,7 @@ function scopedWindowParts(quota, options) {
             part: {
                 kind: 'budget',
                 name: 'credits',
+                short: '',
                 figure,
                 ...(remainingPercent === undefined
                     ? {}
@@ -158,6 +179,7 @@ function scopedWindowParts(quota, options) {
             },
         });
     }
+    withShortNames(windows);
     if (windows.length > 0) {
         const age = now - Math.min(...windows.map(({ part }) => part.checkedAt));
         if (age > (options.staleAfterMs ?? QUOTA_STALE_AFTER_MS)) {
@@ -298,20 +320,21 @@ function narrowTextParts(quota, options) {
         return grouped;
     const general = windows.filter(({ part, scope }) => part.kind === 'window' && scope === ALL_SCOPE);
     const scoped = windows.filter(({ part, scope }) => part.kind === 'window' && scope !== ALL_SCOPE);
-    const abbreviations = scopeAbbreviations(scoped.map(({ scope }) => scope));
     // The items competing for the one slot after the account-wide windows, in
     // tie-break order: scoped windows in display order, then the budget. A
     // spent budget counts as 0% left; one without a percentage cannot compete.
+    // Their labels are the parts' short names, so the narrow line and a layout
+    // reading `short` always agree.
     const budget = windows.find(({ part }) => part.kind === 'budget');
     const budgetLeft = budget?.spent ? 0 : budget?.part.remainingPercent;
     const extras = [
-        ...scoped.map(({ scope, part }) => ({
-            label: abbreviations.get(scope) ?? scope,
+        ...scoped.map(({ part }) => ({
+            label: part.short,
             remaining: part.remainingPercent ?? 0,
         })),
-        ...(budgetLeft === undefined
+        ...(budgetLeft === undefined || budget === undefined
             ? []
-            : [{ label: 'cr', remaining: budgetLeft }]),
+            : [{ label: budget.part.short, remaining: budgetLeft }]),
     ];
     // Strictly lower wins, so on a tie the earlier item keeps the slot.
     const tightest = extras.reduce((best, item) => best === undefined || item.remaining < best.remaining ? item : best, undefined);
@@ -357,3 +380,25 @@ export function formatQuota(quota, options) {
         ? NO_LIMITS_REPORTED
         : NO_QUOTA_READING;
 }
+/**
+ * Prepaid credits as one short value, worded as the official Codex client's
+ * status view words them: `Unlimited` for unlimited credits, `<n> credits`
+ * for a finite positive balance (rounded to a whole number), `Available` when
+ * the account has credits but no usable balance was reported, and undefined
+ * when the account has no credits (or `credits` is undefined), so a caller
+ * shows no credits row at all. Unlimited wins even when `hasCredits` is false.
+ * No other formatter adds this text; a caller that wants a credits row asks
+ * for it.
+ */
+export function quotaCreditsText(credits) {
+    if (credits === undefined)
+        return undefined;
+    if (credits.unlimited)
+        return 'Unlimited';
+    if (!credits.hasCredits)
+        return undefined;
+    const { balance } = credits;
+    return typeof balance === 'number' && Number.isFinite(balance) && balance > 0
+        ? `${Math.round(balance)} credits`
+        : 'Available';
+}

package/dist/common-auth-embedded/quota/index.d.ts

@@ -1,9 +1,9 @@
 export type { QuotaCodec } from './codec.js';
 export { quotaCodec } from './codec.js';
 export type { QuotaParts, QuotaTextForm, QuotaTextOptions, QuotaWindowPart, } from './format.js';
-export { formatQuota, isQuotaStale, NO_LIMITS_REPORTED, NO_QUOTA_READING, QUOTA_STALE_AFTER_MS, quotaTextParts, quotaWindowName, quotaWindowParts, } from './format.js';
-export type { CreditBudgetCleared, CreditBudgetEntry, CreditBudgetReading, QuotaAbsentEntry, QuotaCounter, QuotaEntry, QuotaMap, QuotaReadingEntry, QuotaRetiredEntry, } from './map.js';
-export { ALL_SCOPE, DEFAULT_REQUIRED_LABELS, decodeQuotaMap, emptyQuotaMap, isQuotaMap, } from './map.js';
+export { formatQuota, isQuotaStale, NO_LIMITS_REPORTED, NO_QUOTA_READING, QUOTA_STALE_AFTER_MS, quotaCreditsText, quotaTextParts, quotaWindowName, quotaWindowParts, } from './format.js';
+export type { CreditBudgetCleared, CreditBudgetEntry, CreditBudgetReading, QuotaAbsentEntry, QuotaCounter, QuotaCredits, QuotaEntry, QuotaMap, QuotaReadingEntry, QuotaRetiredEntry, } from './map.js';
+export { ALL_SCOPE, DEFAULT_REQUIRED_LABELS, decodeQuotaMap, emptyQuotaMap, isQuotaCredits, isQuotaMap, } from './map.js';
 export type { ObservedBudget, ObservedPair, ObservedReading, QuotaObservation, } from './merge.js';
 export { isQuotaObservation, mergeQuotaObservation, QuotaCodecError, } from './merge.js';
 export type { ExhaustionReset, ProjectedBudget, ProjectedLimit, ProjectedQuota, QuotaGroup, } from './projection.js';

package/dist/common-auth-embedded/quota/index.js

@@ -1,5 +1,5 @@
 export { quotaCodec } from './codec.js';
-export { formatQuota, isQuotaStale, NO_LIMITS_REPORTED, NO_QUOTA_READING, QUOTA_STALE_AFTER_MS, quotaTextParts, quotaWindowName, quotaWindowParts, } from './format.js';
-export { ALL_SCOPE, DEFAULT_REQUIRED_LABELS, decodeQuotaMap, emptyQuotaMap, isQuotaMap, } from './map.js';
+export { formatQuota, isQuotaStale, NO_LIMITS_REPORTED, NO_QUOTA_READING, QUOTA_STALE_AFTER_MS, quotaCreditsText, quotaTextParts, quotaWindowName, quotaWindowParts, } from './format.js';
+export { ALL_SCOPE, DEFAULT_REQUIRED_LABELS, decodeQuotaMap, emptyQuotaMap, isQuotaCredits, isQuotaMap, } from './map.js';
 export { isQuotaObservation, mergeQuotaObservation, QuotaCodecError, } from './merge.js';
 export { budgetExhaustedResetAt, futureResetAt, projectQuota, readsExhausted, } from './projection.js';

package/dist/common-auth-embedded/quota/map.d.ts

@@ -48,12 +48,30 @@ export interface QuotaCounter {
     value: number;
     checkedAt: number;
 }
+/**
+ * Prepaid credits a provider account holds beside its rate-limit windows (for
+ * example a ChatGPT workspace's credits, which keep requests working after a
+ * window is used up). This is a state, not a count or the spend budget: the
+ * account has credits or not, they may be unlimited, and the provider may
+ * report a balance. It carries its own observation time.
+ */
+export interface QuotaCredits {
+    hasCredits: boolean;
+    unlimited: boolean;
+    /** The balance the provider reported, when it reported one. */
+    balance?: number;
+    /** The provider's verdict that the overage allowance is used up. */
+    overageLimitReached?: boolean;
+    checkedAt: number;
+}
 export interface QuotaMap {
     limits: QuotaEntry[];
     /** Absent means no observation has reported on the budget yet. */
     budget?: CreditBudgetEntry;
     /** Provider-named counts, each with its own observation time. */
     counters?: Record<string, QuotaCounter>;
+    /** Absent means no observation has reported on prepaid credits yet. */
+    credits?: QuotaCredits;
 }
 export declare function emptyQuotaMap(): QuotaMap;
 /** The time an entry speaks for: its reading, retirement or absence time. */
@@ -61,9 +79,14 @@ export declare function entryTime(entry: QuotaEntry): number;
 export declare function limitKey(scope: string, label: string): string;
 export declare function isCreditBudgetEntry(value: unknown): value is CreditBudgetEntry;
 export declare function isQuotaCounters(value: unknown): value is Record<string, QuotaCounter>;
+/** True when `value` is a well-formed prepaid-credits record. */
+export declare function isQuotaCredits(value: unknown): value is QuotaCredits;
 /** Keep usable counters without letting one malformed count hide a quota map. */
 export declare function readQuotaCounters(value: unknown): Record<string, QuotaCounter> | undefined;
-/** Decode persisted quota, dropping malformed counters but not limit evidence. */
+/**
+ * Decode persisted quota, dropping malformed counters or a malformed credits
+ * record but not limit or budget evidence.
+ */
 export declare function decodeQuotaMap(value: unknown): QuotaMap | undefined;
 /**
  * True when `value` is a well-formed quota map. Unrecognised top-level keys

package/dist/common-auth-embedded/quota/map.js

@@ -14,6 +14,9 @@
 // reset clock. It is a tri-state: absent (never reported), a reading, or
 // cleared (the provider reported that no budget exists).
 //
+// Provider-named counters and the prepaid credits record sit beside them too,
+// each judged by its own observation time rather than the limits'.
+//
 // The map is plain JSON so the store can persist it without interpreting it.
 /** The scope of a limit that binds every request regardless of model. */
 export const ALL_SCOPE = 'all';
@@ -93,6 +96,18 @@ function isQuotaCounter(value) {
 export function isQuotaCounters(value) {
     return isRecord(value) && Object.values(value).every(isQuotaCounter);
 }
+function isBoolean(value) {
+    return typeof value === 'boolean';
+}
+/** True when `value` is a well-formed prepaid-credits record. */
+export function isQuotaCredits(value) {
+    return (isRecord(value) &&
+        typeof value.hasCredits === 'boolean' &&
+        typeof value.unlimited === 'boolean' &&
+        optional(value, 'balance', isFiniteNumber) &&
+        optional(value, 'overageLimitReached', isBoolean) &&
+        isFiniteNumber(value.checkedAt));
+}
 /** Keep usable counters without letting one malformed count hide a quota map. */
 export function readQuotaCounters(value) {
     if (!isRecord(value))
@@ -102,20 +117,29 @@ export function readQuotaCounters(value) {
         ? undefined
         : Object.fromEntries(entries);
 }
-/** Decode persisted quota, dropping malformed counters but not limit evidence. */
+/**
+ * Decode persisted quota, dropping malformed counters or a malformed credits
+ * record but not limit or budget evidence.
+ */
 export function decodeQuotaMap(value) {
     // A valid map is returned as the same object, so stored quota keeps the
-    // identity it had before counters existed; only a map with a malformed
-    // counter is copied without it.
+    // identity it had before counters and credits existed. A map with a
+    // malformed counter or credits record is copied with those malformed
+    // fields left out.
     if (isQuotaMap(value))
         return value;
     if (!isRecord(value))
         return undefined;
-    const { counters: rawCounters, ...rest } = value;
+    const { counters: rawCounters, credits: rawCredits, ...rest } = value;
     if (!isQuotaMap(rest))
         return undefined;
     const counters = readQuotaCounters(rawCounters);
-    return { ...rest, ...(counters === undefined ? {} : { counters }) };
+    const credits = isQuotaCredits(rawCredits) ? rawCredits : undefined;
+    return {
+        ...rest,
+        ...(counters === undefined ? {} : { counters }),
+        ...(credits === undefined ? {} : { credits }),
+    };
 }
 /**
  * True when `value` is a well-formed quota map. Unrecognised top-level keys
@@ -136,5 +160,6 @@ export function isQuotaMap(value) {
         seen.add(key);
     }
     return (optional(value, 'budget', isCreditBudgetEntry) &&
-        optional(value, 'counters', isQuotaCounters));
+        optional(value, 'counters', isQuotaCounters) &&
+        optional(value, 'credits', isQuotaCredits));
 }

package/dist/common-auth-embedded/quota/merge.d.ts

@@ -1,4 +1,4 @@
-import { type QuotaCounter, type QuotaMap } from './map.js';
+import { type QuotaCounter, type QuotaCredits, type QuotaMap } from './map.js';
 export interface ObservedReading {
     /** Defaults to `all`. */
     scope?: string;
@@ -34,6 +34,11 @@ export interface QuotaObservation {
     budget?: ObservedBudget;
     /** Each named count uses its own time, independently of limits and budget. */
     counters?: Record<string, QuotaCounter>;
+    /**
+     * Prepaid credits, judged by their own time independently of limits, budget
+     * and counters. Absent means the observation says nothing about credits.
+     */
+    credits?: QuotaCredits;
 }
 /** Thrown by `mergeQuotaObservation` when either argument is malformed. */
 export declare class QuotaCodecError extends TypeError {