@cortexkit/opencode-antigravity-auth 2.2.1 → 3.0.0

package/dist/src/common-auth-embedded/pi-slot/slot.js

@@ -0,0 +1,383 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, unlink } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { writeJsonAtomic } from '../fs/atomic-write.js';
+import { acquirePiLock } from './lock.js';
+/** Errors deliberately contain neither paths nor credentials nor underlying error messages. */
+export class PiSlotError extends Error {
+    code;
+    constructor(code) {
+        super(`Pi slot: ${code}`);
+        this.code = code;
+        this.name = 'PiSlotError';
+    }
+}
+// JSON.parse validates grammar first. This scan only locates top-level value text ranges.
+function rootSpans(text) {
+    let i = text.indexOf('{') + 1;
+    const root = { offset: i - 1, children: [] };
+    const whitespace = () => {
+        while (/\s/.test(text[i] ?? '') && i < text.length)
+            i++;
+    };
+    const stringEnd = () => {
+        i++;
+        while (i < text.length) {
+            if (text[i++] === '"')
+                return;
+            if (text[i - 1] === '\\')
+                i++;
+        }
+    };
+    whitespace();
+    while (text[i] !== '}') {
+        const start = i;
+        stringEnd();
+        const key = JSON.parse(text.slice(start, i));
+        whitespace();
+        i++; // colon
+        whitespace();
+        const offset = i;
+        let depth = 0;
+        while (i < text.length) {
+            const char = text[i];
+            if (char === '"') {
+                stringEnd();
+                continue;
+            }
+            if (char === '{' || char === '[')
+                depth++;
+            if (char === '}' || char === ']') {
+                if (depth === 0)
+                    break;
+                depth--;
+            }
+            if (char === ',' && depth === 0)
+                break;
+            i++;
+        }
+        let end = i;
+        while (/\s/.test(text[end - 1] ?? ''))
+            end--;
+        root.children.push({
+            key,
+            offset: start,
+            length: end - start,
+            value: { offset, length: end - offset },
+        });
+        whitespace();
+        if (text[i] === '}')
+            break;
+        i++; // comma
+        whitespace();
+    }
+    return root;
+}
+function object(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (object(value)) {
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function digest(value) {
+    return createHash('sha256').update(canonical(value)).digest('hex');
+}
+function code(error) {
+    return object(error) ? error.code : undefined;
+}
+async function safeRead(path, privateFile = false, afterReadCheck) {
+    let file;
+    try {
+        file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const stat = await file.stat();
+        if (!stat.isFile() || (privateFile && (stat.mode & 0o777) !== 0o600)) {
+            throw new PiSlotError('unsafe-path');
+        }
+        await afterReadCheck?.(path);
+        // Refuse a replaced pathname even though the descriptor still pins the checked file.
+        const current = await lstat(path);
+        if (!current.isFile() ||
+            current.dev !== stat.dev ||
+            current.ino !== stat.ino) {
+            throw new PiSlotError('unsafe-path');
+        }
+        const bytes = await file.readFile();
+        const text = bytes.toString('utf8');
+        if (!bytes.equals(Buffer.from(text))) {
+            throw new PiSlotError(privateFile ? 'invalid-stash' : 'invalid-auth');
+        }
+        return text;
+    }
+    catch (error) {
+        if (code(error) === 'ENOENT' && !file)
+            return undefined;
+        if (code(error) === 'ELOOP' || code(error) === 'ENOENT') {
+            throw new PiSlotError('unsafe-path');
+        }
+        throw error;
+    }
+    finally {
+        await file?.close();
+    }
+}
+function parseAuth(text, provider) {
+    try {
+        const data = JSON.parse(text);
+        if (!object(data))
+            throw new Error();
+        const root = rootSpans(text);
+        const properties = root.children;
+        // Duplicate provider keys have ambiguous byte ownership, even though JSON.parse accepts them.
+        const names = properties.map((node) => node.key);
+        if (new Set(names).size !== names.length)
+            throw new Error();
+        const property = properties.find((node) => node.key === provider);
+        const entry = property ? data[provider] : null;
+        if (entry !== null && !object(entry))
+            throw new Error();
+        if (property && entry === null)
+            throw new Error();
+        return { text, root, property, entry: entry };
+    }
+    catch {
+        throw new PiSlotError('invalid-auth');
+    }
+}
+function entryText(auth) {
+    const value = auth.property?.value;
+    return value
+        ? auth.text.slice(value.offset, value.offset + value.length)
+        : null;
+}
+function replaceEntry(auth, provider, next) {
+    const { text, root, property } = auth;
+    const properties = root.children ?? [];
+    if (property) {
+        const value = property.value;
+        if (!value)
+            throw new PiSlotError('invalid-auth');
+        if (next !== null) {
+            return (text.slice(0, value.offset) +
+                next +
+                text.slice(value.offset + value.length));
+        }
+        const index = properties.indexOf(property);
+        const previous = properties[index - 1];
+        const following = properties[index + 1];
+        const start = previous ? previous.offset + previous.length : property.offset;
+        const end = !previous && following
+            ? following.offset
+            : property.offset + property.length;
+        return text.slice(0, start) + text.slice(end);
+    }
+    if (next === null)
+        return text;
+    const last = properties.at(-1);
+    // Insert next to the last value, not after its whitespace, so deletion reverses an empty-slot swap.
+    const offset = last ? last.offset + last.length : root.offset + 1;
+    return `${text.slice(0, offset)}${last ? ',' : ''}${JSON.stringify(provider)}:${next}${text.slice(offset)}`;
+}
+async function syncDir(path) {
+    const dir = await open(path, 'r');
+    try {
+        await dir.sync();
+    }
+    finally {
+        await dir.close();
+    }
+}
+async function atomicWrite(path, text, assertLock, beforeRename) {
+    await writeJsonAtomic(path, null, {
+        serialize: () => text,
+        durable: true,
+        beforeRename: async () => {
+            await beforeRename?.(path);
+            assertLock();
+        },
+    });
+}
+/**
+ * Production entry point. Pi caches which models are usable; after a
+ * successful transition the extension calls `ctx.modelRegistry.refresh()` so
+ * Pi re-reads the slot it just changed.
+ */
+export function openPiSlot(options) {
+    return createPiSlot(options);
+}
+/**
+ * Internal test entry point: pause reads, renewals, or renames to simulate races,
+ * and observe durable writes/deletion to simulate crashes. Not a public export.
+ */
+export function createPiSlot(options, onStep, hooks) {
+    const { provider, placeholderKey } = options;
+    const timeout = options.lockTimeoutMs ?? 30_000;
+    if (!provider ||
+        !options.authPath ||
+        !options.stashPath ||
+        !placeholderKey ||
+        placeholderKey.startsWith('!') ||
+        placeholderKey.includes('$') ||
+        !Number.isFinite(timeout) ||
+        timeout < 0) {
+        throw new PiSlotError('invalid-options');
+    }
+    const authPath = resolve(options.authPath);
+    const stashPath = resolve(options.stashPath);
+    if (authPath === stashPath || stashPath === `${authPath}.lock`) {
+        throw new PiSlotError('invalid-options');
+    }
+    const authIdentity = digest(authPath);
+    const placeholderIdentity = digest(placeholderKey);
+    const placeholder = { type: 'api_key', key: placeholderKey };
+    const isPlaceholder = (entry) => digest(entry) === digest(placeholder);
+    async function loadStash() {
+        const text = await safeRead(stashPath, true, hooks?.afterReadCheck);
+        if (text === undefined)
+            return undefined;
+        try {
+            const stash = JSON.parse(text);
+            if (stash.version !== 1 ||
+                stash.provider !== provider ||
+                stash.authIdentity !== authIdentity ||
+                stash.placeholderIdentity !== placeholderIdentity ||
+                (stash.entry !== null && !object(stash.entry)) ||
+                stash.sha256 !== digest(stash.entry) ||
+                (stash.entry === null
+                    ? stash.entryJson !== null
+                    : typeof stash.entryJson !== 'string' ||
+                        digest(JSON.parse(stash.entryJson)) !== stash.sha256)) {
+                throw new Error();
+            }
+            return stash;
+        }
+        catch {
+            throw new PiSlotError('invalid-stash');
+        }
+    }
+    async function locked(fn) {
+        let release;
+        let assertFresh;
+        let compromised = false;
+        const assertLock = () => {
+            assertFresh?.();
+            if (compromised)
+                throw new PiSlotError('lock-compromised');
+        };
+        try {
+            await mkdir(dirname(authPath), { recursive: true, mode: 0o700 });
+            const deadline = Date.now() + timeout;
+            let retry = 0;
+            while (!release) {
+                try {
+                    const lease = await acquirePiLock(authPath, () => {
+                        compromised = true;
+                    }, hooks?.onRenew);
+                    release = lease.release;
+                    assertFresh = lease.assertFresh;
+                }
+                catch (error) {
+                    if (code(error) !== 'ELOCKED')
+                        throw error;
+                    const remaining = deadline - Date.now();
+                    if (remaining <= 0)
+                        throw new PiSlotError('lock-timeout');
+                    await sleep(Math.min(Math.round(Math.min(10 * 2 ** retry++, 1_000) * (1 + Math.random())), remaining));
+                }
+            }
+            assertLock();
+            const result = await fn(assertLock);
+            assertLock();
+            return result;
+        }
+        catch (error) {
+            if (error instanceof PiSlotError)
+                throw error;
+            throw new PiSlotError('io');
+        }
+        finally {
+            await release?.().catch(() => { });
+            assertLock();
+        }
+    }
+    async function load() {
+        const auth = parseAuth((await safeRead(authPath, false, hooks?.afterReadCheck)) ?? '{}', provider);
+        const stash = await loadStash();
+        return { auth, stash };
+    }
+    async function deleteStash(assertLock) {
+        assertLock();
+        await unlink(stashPath);
+        await syncDir(dirname(stashPath));
+        onStep?.('stash-deleted');
+    }
+    return {
+        inspect: () => locked(async () => {
+            const { auth, stash } = await load();
+            const slot = isPlaceholder(auth.entry)
+                ? 'placeholder'
+                : auth.entry === null
+                    ? 'empty'
+                    : !stash || digest(auth.entry) === stash.sha256
+                        ? 'original'
+                        : 'foreign';
+            return { slot, stash: stash ? 'valid' : 'missing' };
+        }),
+        enterVault: () => locked(async (assertLock) => {
+            const { auth, stash } = await load();
+            if (isPlaceholder(auth.entry)) {
+                if (!stash)
+                    throw new PiSlotError('missing-stash');
+                return;
+            }
+            if (stash && digest(auth.entry) !== stash.sha256)
+                throw new PiSlotError('conflict');
+            if (!stash) {
+                await mkdir(dirname(stashPath), { recursive: true, mode: 0o700 });
+                const dir = await lstat(dirname(stashPath));
+                if (!dir.isDirectory() || (dir.mode & 0o777) !== 0o700)
+                    throw new PiSlotError('unsafe-path');
+                const saved = {
+                    version: 1,
+                    provider,
+                    authIdentity,
+                    placeholderIdentity,
+                    entry: auth.entry,
+                    entryJson: entryText(auth),
+                    sha256: digest(auth.entry),
+                };
+                await atomicWrite(stashPath, JSON.stringify(saved), assertLock, hooks?.beforeRename);
+                onStep?.('stash-written');
+            }
+            await atomicWrite(authPath, replaceEntry(auth, provider, JSON.stringify(placeholder)), assertLock, hooks?.beforeRename);
+            onStep?.('auth-written');
+        }),
+        exitVault: () => locked(async (assertLock) => {
+            const { auth, stash } = await load();
+            if (!stash) {
+                if (isPlaceholder(auth.entry))
+                    throw new PiSlotError('missing-stash');
+                return 'nothing-to-do';
+            }
+            if (isPlaceholder(auth.entry)) {
+                await atomicWrite(authPath, replaceEntry(auth, provider, stash.entryJson), assertLock, hooks?.beforeRename);
+                onStep?.('auth-written');
+            }
+            else if (digest(auth.entry) !== stash.sha256) {
+                return 'conflict';
+            }
+            // Also completes a restore interrupted between the auth rename and stash deletion.
+            await deleteStash(assertLock);
+            return 'restored';
+        }),
+    };
+}

package/dist/src/common-auth-embedded/quota/codec.d.ts

@@ -0,0 +1,11 @@
+export interface QuotaCodec {
+    readonly validate: (value: unknown) => boolean;
+    readonly merge: (stored: unknown, observation: unknown) => unknown;
+}
+/**
+ * The quota codec the account-pool store (the `/store` subpath) takes when it
+ * is opened: `validate` checks a stored per-row quota map and `merge` applies
+ * an observation to one, so the store persists the map without interpreting
+ * it.
+ */
+export declare const quotaCodec: QuotaCodec;

package/dist/src/common-auth-embedded/quota/codec.js

@@ -0,0 +1,12 @@
+import { isQuotaMap } from './map.js';
+import { mergeQuotaObservation } from './merge.js';
+/**
+ * The quota codec the account-pool store (the `/store` subpath) takes when it
+ * is opened: `validate` checks a stored per-row quota map and `merge` applies
+ * an observation to one, so the store persists the map without interpreting
+ * it.
+ */
+export const quotaCodec = Object.freeze({
+    validate: isQuotaMap,
+    merge: mergeQuotaObservation,
+});

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

@@ -0,0 +1,46 @@
+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;
+/** What `formatQuota` returns when there is no reading at all. */
+export declare const NO_QUOTA_READING = "no quota reading yet";
+/**
+ * What `formatQuota` returns when the provider answered but reported no
+ * limit for any window (every window is an absence record or a tombstone).
+ */
+export declare const NO_LIMITS_REPORTED = "no limits reported";
+/**
+ * `compact` fits a footer or a sidebar row: each window's figure, the credit
+ * budget and the stale marker, without reset times. `full` adds each reset.
+ */
+export type QuotaTextForm = 'compact' | 'full';
+export interface QuotaTextOptions {
+    /** The current time in ms, for reset countdowns and the stale marker. */
+    now: number;
+    /** Defaults to `full`. */
+    form?: QuotaTextForm;
+    /** Defaults to `QUOTA_STALE_AFTER_MS`. */
+    staleAfterMs?: number;
+}
+/**
+ * The name a window is shown under. A general window (scope `all`) is named
+ * by its stored length; a model-scoped window keeps the label the plugin
+ * stored it under, which already names the model (`seven_day_opus`). A
+ * general window stored without a length (a snapshot from before lengths
+ * were recorded) falls back to its label.
+ */
+export declare function quotaWindowName(limit: Pick<ProjectedLimit, 'scope' | 'label' | 'windowMinutes'>): string;
+/**
+ * The pieces of a quota text, in order: one per reported window
+ * (`5h 58% left, resets 2h`), then the credit budget when there is one, then
+ * `checked 3h ago` when the oldest piece shown is stale. Empty when nothing
+ * was reported; `formatQuota` turns that into a sentence. A caller printing
+ * one line per window (the terminal auth menu) uses these directly.
+ */
+export declare function quotaTextParts(quota: ProjectedQuota | undefined, options: QuotaTextOptions): string[];
+/**
+ * A row's quota as one line: `5h 58% left · 7d 90% left` in the compact
+ * form, with `, resets 2h` after each window in the full form. With nothing
+ * reported it is `NO_QUOTA_READING`, or `NO_LIMITS_REPORTED` when the
+ * provider answered without a limit for any window.
+ */
+export declare function formatQuota(quota: ProjectedQuota | undefined, options: QuotaTextOptions): string;

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

@@ -0,0 +1,138 @@
+// The one quota wording every surface shows: the command menu's dialogs on
+// OpenCode and Pi, the terminal auth menu, and the plugins' sidebars. Each of
+// them calls `formatQuota` (or `quotaTextParts` for one line per window), so
+// the wording cannot drift between plugins or between a dialog and a sidebar.
+//
+// The rules: a window is named by its length (`5h`, `7d`), or, for a window
+// that binds only one model family, by the label the plugin stored it under.
+// Every figure is "% left". A window the provider did not report (an absence
+// record or a retirement tombstone) is left out rather than written as "not
+// reported". A reset is a short time from now (`resets 2h`). A reading older
+// than fifteen minutes says how old it is (`checked 3h ago`).
+//
+// Like the rest of this module it reads no clock: `now` is a parameter.
+import { ALL_SCOPE } from './map.js';
+/** A reading older than this is marked with its age. */
+export const QUOTA_STALE_AFTER_MS = 15 * 60_000;
+/** What `formatQuota` returns when there is no reading at all. */
+export const NO_QUOTA_READING = 'no quota reading yet';
+/**
+ * What `formatQuota` returns when the provider answered but reported no
+ * limit for any window (every window is an absence record or a tombstone).
+ */
+export const NO_LIMITS_REPORTED = 'no limits reported';
+/**
+ * A length or a time span in its largest whole-ish unit: `45m`, `5h`, `3d`.
+ * Spans under an hour are minutes, under a day hours, otherwise days, each
+ * rounded to the nearest unit and never shown as zero.
+ */
+function shortSpan(ms) {
+    const minutes = Math.max(1, Math.round(ms / 60_000));
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 24)
+        return `${hours}h`;
+    return `${Math.max(1, Math.round(minutes / 1440))}d`;
+}
+/** A stored window length in minutes as its exact name: `5h`, `7d`, `90m`. */
+function lengthName(minutes) {
+    if (minutes % 1440 === 0)
+        return `${minutes / 1440}d`;
+    if (minutes % 60 === 0)
+        return `${minutes / 60}h`;
+    return `${minutes}m`;
+}
+/**
+ * The name a window is shown under. A general window (scope `all`) is named
+ * by its stored length; a model-scoped window keeps the label the plugin
+ * stored it under, which already names the model (`seven_day_opus`). A
+ * general window stored without a length (a snapshot from before lengths
+ * were recorded) falls back to its label.
+ */
+export function quotaWindowName(limit) {
+    if (limit.scope !== ALL_SCOPE || limit.windowMinutes === undefined)
+        return limit.label;
+    return lengthName(limit.windowMinutes);
+}
+function percentLeft(remaining) {
+    return `${Math.round(Math.min(100, Math.max(0, remaining)))}% left`;
+}
+function resetText(resetsAt, now) {
+    if (resetsAt === undefined)
+        return '';
+    const at = Date.parse(resetsAt);
+    // A reset already passed says nothing about the future; leave it out.
+    if (!Number.isFinite(at) || at <= now)
+        return '';
+    return `, resets ${shortSpan(at - now)}`;
+}
+/** Shortest window first, so `5h` reads before `7d`; unknown lengths last. */
+function displayOrder(left, right) {
+    const l = left.windowMinutes;
+    const r = right.windowMinutes;
+    if (l !== undefined && r !== undefined && l !== r)
+        return l - r;
+    if ((l === undefined) !== (r === undefined))
+        return l === undefined ? 1 : -1;
+    if (left.scope !== right.scope) {
+        if (left.scope === ALL_SCOPE)
+            return -1;
+        if (right.scope === ALL_SCOPE)
+            return 1;
+        return left.scope < right.scope ? -1 : 1;
+    }
+    return left.label < right.label ? -1 : left.label > right.label ? 1 : 0;
+}
+/**
+ * The pieces of a quota text, in order: one per reported window
+ * (`5h 58% left, resets 2h`), then the credit budget when there is one, then
+ * `checked 3h ago` when the oldest piece shown is stale. Empty when nothing
+ * was reported; `formatQuota` turns that into a sentence. A caller printing
+ * one line per window (the terminal auth menu) uses these directly.
+ */
+export function quotaTextParts(quota, options) {
+    if (!quota)
+        return [];
+    const { now } = options;
+    const full = (options.form ?? 'full') === 'full';
+    const parts = [];
+    const times = [];
+    const readings = quota.limits
+        .filter((limit) => limit.kind === 'reading' && limit.remainingPercent !== undefined)
+        .sort(displayOrder);
+    for (const limit of readings) {
+        times.push(limit.checkedAt);
+        parts.push(`${quotaWindowName(limit)} ${percentLeft(limit.remainingPercent ?? 0)}${full ? resetText(limit.resetsAt, now) : ''}`);
+    }
+    const budget = quota.budget;
+    if (budget) {
+        times.push(budget.checkedAt);
+        const figure = budget.reached
+            ? 'credits spent'
+            : budget.remainingPercent !== undefined
+                ? `credits ${percentLeft(budget.remainingPercent)}`
+                : 'credits available';
+        parts.push(`${figure}${full ? resetText(budget.resetsAt, now) : ''}`);
+    }
+    if (times.length > 0) {
+        const age = now - Math.min(...times);
+        if (age > (options.staleAfterMs ?? QUOTA_STALE_AFTER_MS))
+            parts.push(`checked ${shortSpan(age)} ago`);
+    }
+    return parts;
+}
+/**
+ * A row's quota as one line: `5h 58% left · 7d 90% left` in the compact
+ * form, with `, resets 2h` after each window in the full form. With nothing
+ * reported it is `NO_QUOTA_READING`, or `NO_LIMITS_REPORTED` when the
+ * provider answered without a limit for any window.
+ */
+export function formatQuota(quota, options) {
+    const parts = quotaTextParts(quota, options);
+    if (parts.length > 0)
+        return parts.join(' · ');
+    return quota && quota.limits.length > 0
+        ? NO_LIMITS_REPORTED
+        : NO_QUOTA_READING;
+}

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

@@ -0,0 +1,10 @@
+export type { QuotaCodec } from './codec.js';
+export { quotaCodec } from './codec.js';
+export type { QuotaTextForm, QuotaTextOptions } from './format.js';
+export { formatQuota, NO_LIMITS_REPORTED, NO_QUOTA_READING, QUOTA_STALE_AFTER_MS, quotaTextParts, quotaWindowName, } from './format.js';
+export type { CreditBudgetCleared, CreditBudgetEntry, CreditBudgetReading, QuotaAbsentEntry, QuotaEntry, QuotaMap, QuotaReadingEntry, QuotaRetiredEntry, } from './map.js';
+export { ALL_SCOPE, DEFAULT_REQUIRED_LABELS, emptyQuotaMap, 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, } from './projection.js';
+export { budgetExhaustedResetAt, futureResetAt, projectQuota, readsExhausted, } from './projection.js';

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

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

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

@@ -0,0 +1,63 @@
+/** The scope of a limit that binds every request regardless of model. */
+export declare const ALL_SCOPE = "all";
+/** The window label required when an admission call supplies none. */
+export declare const DEFAULT_REQUIRED_LABELS: readonly string[];
+export interface QuotaReadingEntry {
+    scope: string;
+    label: string;
+    kind: 'reading';
+    checkedAt: number;
+    usedPercent: number;
+    /** ISO timestamp at which the window resets, as the provider reported it. */
+    resetsAt?: string;
+    /** Window length in minutes, when the provider reported one. */
+    windowMinutes?: number;
+}
+export interface QuotaRetiredEntry {
+    scope: string;
+    label: string;
+    kind: 'retired';
+    retiredAt: number;
+}
+export interface QuotaAbsentEntry {
+    scope: string;
+    label: string;
+    kind: 'absent';
+    checkedAt: number;
+}
+export type QuotaEntry = QuotaReadingEntry | QuotaRetiredEntry | QuotaAbsentEntry;
+export interface CreditBudgetReading {
+    kind: 'reading';
+    checkedAt: number;
+    /** The provider's own verdict that the budget is spent. */
+    reached: boolean;
+    remainingPercent?: number;
+    usedPercent?: number;
+    resetsAt?: string;
+    limit?: number;
+    used?: number;
+    remaining?: number;
+    unit?: string;
+}
+export interface CreditBudgetCleared {
+    kind: 'cleared';
+    checkedAt: number;
+}
+export type CreditBudgetEntry = CreditBudgetReading | CreditBudgetCleared;
+export interface QuotaMap {
+    limits: QuotaEntry[];
+    /** Absent means no observation has reported on the budget yet. */
+    budget?: CreditBudgetEntry;
+}
+export declare function emptyQuotaMap(): QuotaMap;
+/** The time an entry speaks for: its reading, retirement or absence time. */
+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;
+/**
+ * True when `value` is a well-formed quota map. Unrecognised top-level keys
+ * are tolerated (and preserved by merge) so a newer writer's additions
+ * survive; a malformed entry, a duplicated (scope, label) key or a malformed
+ * budget makes the whole map invalid.
+ */
+export declare function isQuotaMap(value: unknown): value is QuotaMap;