@cortexkit/antigravity-auth-core 3.0.8 → 3.0.10

package/dist/common-auth-embedded/claustrum/quota-writer.js

@@ -0,0 +1,253 @@
+import { resolve } from 'node:path';
+import { createLogger } from '../logger/index.js';
+import { isQuotaObservation } from '../quota/index.js';
+import { applyVaultQuota, mutateVaultRoster, } from './roster.js';
+// Every consumer of the same file shares one mailbox and one lock waiter.
+const writers = new Map();
+const logger = createLogger('claustrum');
+const COALESCE_MS = 100;
+function writerFor(path) {
+    const key = resolve(path);
+    let writer = writers.get(key);
+    if (!writer) {
+        writer = {
+            path: key,
+            pending: new Map(),
+            listeners: new Set(),
+            wake: new Set(),
+            abort: new AbortController(),
+            failures: 0,
+            draining: false,
+            order: 0,
+        };
+        writers.set(key, writer);
+    }
+    return writer;
+}
+/** Retain the shared writer; the last consumer's close drains it. */
+export function retainVaultQuotaWriter(path, listener) {
+    const writer = writerFor(path);
+    writer.listeners.add(listener);
+    let released;
+    return () => (released ??= (() => {
+        writer.listeners.delete(listener);
+        return writer.listeners.size ? Promise.resolve() : drainVaultQuota(path);
+    })());
+}
+// Split one observation into its independently dated parts: each rate-limit
+// window (scope and label), each covered-but-unread window, the budget, each
+// counter and the credits record. The mailbox keeps the newest of each part on
+// its own, so a later observation that carries only some parts can't erase an
+// older but still newest reading of another part, which is how
+// mergeQuotaObservation treats them on disk. Each key also carries the
+// receipt's identity, so the identity fence still applies to every part.
+function fields(publication) {
+    const result = new Map();
+    const { observation } = publication;
+    const witness = JSON.stringify([
+        publication.routeId,
+        publication.receipt?.credentialId,
+        publication.receipt?.accountIdentitySource,
+        publication.receipt?.expectedAccountIdentity,
+    ]);
+    const add = (key, at, part) => result.set(`${witness}:${key}`, {
+        at,
+        order: 0,
+        publication: { ...publication, observation: part },
+    });
+    const keyFor = (scope, label) => JSON.stringify([scope ?? 'all', label]);
+    const read = new Set();
+    for (const reading of observation.readings ?? []) {
+        const key = keyFor(reading.scope, reading.label);
+        read.add(key);
+        add(key, observation.checkedAt, {
+            checkedAt: observation.checkedAt,
+            readings: [{ ...reading }],
+        });
+    }
+    for (const pair of observation.coverage ?? []) {
+        const key = keyFor(pair.scope, pair.label);
+        if (!read.has(key))
+            add(key, observation.checkedAt, {
+                checkedAt: observation.checkedAt,
+                coverage: [{ ...pair }],
+            });
+    }
+    if (observation.budget)
+        add('budget', observation.checkedAt, {
+            checkedAt: observation.checkedAt,
+            budget: { ...observation.budget },
+        });
+    for (const [name, counter] of Object.entries(observation.counters ?? {})) {
+        add(`counter:${name}`, counter.checkedAt, {
+            checkedAt: observation.checkedAt,
+            counters: { [name]: { ...counter } },
+        });
+    }
+    if (observation.credits)
+        add('credits', observation.credits.checkedAt, {
+            checkedAt: observation.checkedAt,
+            credits: { ...observation.credits },
+        });
+    // Even an empty observation can bind an account proved by its receipt.
+    if (!result.size)
+        add('empty', observation.checkedAt, { checkedAt: observation.checkedAt });
+    return result;
+}
+/** Enqueue without filesystem work; each quota field retains its own receipt fence. */
+export function enqueueVaultQuota(path, publication) {
+    if (!isQuotaObservation(publication.observation))
+        return Promise.resolve(false);
+    const writer = writerFor(path);
+    const account = JSON.stringify([
+        publication.accountIdentity ?? null,
+        publication.accountIdentity === undefined ? publication.routeId : null,
+    ]);
+    const pending = writer.pending.get(account) ?? new Map();
+    for (const [key, field] of fields(publication)) {
+        const previous = pending.get(key);
+        if (!previous || field.at >= previous.at) {
+            field.order = ++writer.order;
+            // A covered disappearance after an unflushed reading is a retirement,
+            // not an absence. Retain just enough history to preserve that distinction.
+            if (field.publication.observation.coverage)
+                field.priorReading = previous?.publication.observation.readings
+                    ? previous.publication
+                    : previous?.priorReading;
+            pending.set(key, field);
+        }
+    }
+    if (pending.size)
+        writer.pending.set(account, pending);
+    for (const listener of writer.listeners)
+        listener(publication);
+    schedule(writer, COALESCE_MS);
+    return Promise.resolve(true);
+}
+function orderedFields(pending) {
+    // Equal observation times are last-enqueue-wins even across different
+    // credentials or account-only readings. Map insertion order cannot prove it.
+    return [...pending.values()]
+        .flatMap((account) => [...account.values()])
+        .sort((a, b) => a.order - b.order);
+}
+/** Overlay uncommitted observations when a consumer reloads the durable roster. */
+export function pendingVaultQuota(path, roster) {
+    const writer = writers.get(resolve(path));
+    if (writer) {
+        for (const field of orderedFields(writer.pending)) {
+            if (field.priorReading)
+                roster = applyVaultQuota(roster, field.priorReading).roster;
+            roster = applyVaultQuota(roster, field.publication).roster;
+        }
+    }
+    return roster;
+}
+function schedule(writer, delay) {
+    if (writer.running ||
+        writer.timer ||
+        !writer.pending.size ||
+        writer.abort.signal.aborted)
+        return;
+    writer.timer = setTimeout(() => {
+        writer.timer = undefined;
+        flush(writer);
+    }, delay);
+    if (!writer.draining)
+        writer.timer.unref?.();
+}
+function flush(writer) {
+    if (writer.running || writer.abort.signal.aborted)
+        return;
+    const batch = new Map([...writer.pending].map(([account, pending]) => [
+        account,
+        new Map(pending),
+    ]));
+    writer.running = (async () => {
+        try {
+            await mutateVaultRoster(writer.path, (current) => {
+                let next = current;
+                for (const field of orderedFields(batch)) {
+                    if (field.priorReading)
+                        next = applyVaultQuota(next, field.priorReading).roster;
+                    next = applyVaultQuota(next, field.publication).roster;
+                }
+                return { ...(next !== current && { next }), result: undefined };
+            }, { signal: writer.abort.signal });
+            for (const [account, fields] of batch) {
+                const pending = writer.pending.get(account);
+                for (const [key, field] of fields) {
+                    // A newer enqueue must survive completion of an older flush.
+                    if (pending?.get(key) === field)
+                        pending.delete(key);
+                }
+                if (!pending?.size)
+                    writer.pending.delete(account);
+            }
+            writer.failures = 0;
+        }
+        catch (error) {
+            if (!writer.abort.signal.aborted && writer.failures++ === 0) {
+                logger.warn('vault quota publication delayed; retrying', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            // Keep the batch in the mailbox, including any fresher fields enqueued meanwhile.
+        }
+        finally {
+            writer.running = undefined;
+            for (const wake of writer.wake)
+                wake();
+            const backoff = writer.failures
+                ? Math.min(5_000, 100 * 2 ** Math.min(writer.failures, 6)) *
+                    (0.5 + Math.random())
+                : COALESCE_MS;
+            schedule(writer, backoff);
+        }
+    })();
+}
+/** Wait at most timeoutMs for detached publication; shutdown loss is acceptable. */
+export async function drainVaultQuota(path, timeoutMs = 1_000) {
+    const key = resolve(path);
+    const writer = writers.get(key);
+    if (!writer)
+        return;
+    writer.draining = true;
+    clearTimeout(writer.timer);
+    writer.timer = undefined;
+    let deadline;
+    let wake;
+    const drained = new Promise((done) => {
+        wake = () => {
+            if (!writer.pending.size || writer.abort.signal.aborted)
+                done();
+        };
+        writer.wake.add(wake);
+        wake();
+    });
+    try {
+        if (writer.pending.size)
+            flush(writer);
+        await Promise.race([
+            drained,
+            new Promise((done) => {
+                deadline = setTimeout(done, Math.max(0, timeoutMs));
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(deadline);
+        if (wake)
+            writer.wake.delete(wake);
+        writer.draining = false;
+        // A still-open consumer owns the mailbox, so another consumer's disposal
+        // must not discard its observations or stop its retries.
+        if (!writer.listeners.size) {
+            writer.abort.abort();
+            clearTimeout(writer.timer);
+            writer.pending.clear();
+            if (writers.get(key) === writer)
+                writers.delete(key);
+        }
+    }
+}

package/dist/common-auth-embedded/claustrum/roster.d.ts

@@ -2,6 +2,8 @@ import { type QuotaMap, type QuotaObservation } from '../quota/index.js';
 import type { RoutingRow } from '../routing/index.js';
 import type { ClaustrumScopedAttempt, ClaustrumScopedCustody, SkippedVaultRecord, VaultCredential, VaultCredentialType, VaultInventory } from './custody.js';
 import { type DeclinedAccount } from './interlock.js';
+import { type VaultQuotaPublication } from './quota-writer.js';
+export { drainVaultQuota } from './quota-writer.js';
 /**
  * One vault account as the pool sees it. It carries no bearer material: the
  * access token is fetched from the vault for every send. Several vault
@@ -91,6 +93,7 @@ export interface VaultRosterLockContext {
     assertOwned: () => Promise<void>;
 }
 export interface MutateVaultRosterOptions {
+    signal?: AbortSignal;
     /**
      * Runs when the new roster is fully staged on disk, immediately before the
      * rename that publishes it, so a caller can confirm a lease of its own at
@@ -127,7 +130,10 @@ export type QuotaReceipt = Pick<ClaustrumScopedAttempt, 'credentialId' | 'accoun
  * 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 declare function recordVaultQuota(path: string, input: QuotaReceipt & {
     routeId: string;
@@ -139,19 +145,28 @@ export declare function recordVaultQuota(path: string, input: QuotaReceipt & {
  * 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 declare function recordVaultAccountQuota(path: string, input: {
     routeId: string;
     accountIdentity: string;
     observation: QuotaObservation;
 }): Promise<boolean>;
+/** Apply the same identity fence to memory overlays and durable quota batches. */
+export declare function applyVaultQuota(current: VaultRosterFile | undefined, input: VaultQuotaPublication): {
+    roster: VaultRosterFile | undefined;
+    kept: boolean;
+};
+export declare function forgetPendingVaultDiscovery(path: string): void;
 /**
  * Discover and commit the roster. The lease covers the list call and the
  * commit, not just the write: an opaque view cannot tell a delayed old reply
  * 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 declare function refreshVaultRoster(options: {
     path: string;
@@ -159,6 +174,7 @@ export declare function refreshVaultRoster(options: {
     isActive?: () => boolean | Promise<boolean>;
     signal?: AbortSignal;
     projection?: ProjectionOptions | (() => ProjectionOptions);
+    onInventory?: (inventory: VaultInventory) => void;
 }): Promise<VaultRosterFile | undefined>;
 /**
  * A host-owned main account as last verified from the vault: the plugin's

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/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;