@cortexkit/antigravity-auth-core 3.0.9 → 3.0.11

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

@@ -169,8 +169,10 @@ export declare class ClaustrumConsumer<Q = QuotaObservation> {
      * a served credential (an insula reading from `cachedInsulaQuotaForRoute`).
      * It lands only while the route is still bound to that known account, so no
      * credential fetch is needed and a replaced account's reading is dropped.
-     * The in-memory roster is reloaded from the file, without a vault call.
+     * Memory updates immediately; durable publication is detached and coalesced.
      */
     recordAccountQuota(routeId: string, accountIdentity: string, observation: QuotaObservation): Promise<boolean>;
     close(): void;
+    /** Close immediately; the last consumer also waits for the writer's bounded drain. */
+    dispose(): Promise<void>;
 }

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

@@ -4,7 +4,8 @@ import { ClaustrumScopedCustody, decideScopedRetryAfter401, } from './custody.js
 import { readClaustrumEnrollmentToken } from './enrollment.js';
 import { ClaustrumConsumerError } from './errors.js';
 import { acquireInsulaQuotaSource, } from './insula.js';
-import { acceptVaultRoute, declineVaultRoute, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, vaultRoutingRows, } from './roster.js';
+import { pendingVaultQuota, retainVaultQuotaWriter } from './quota-writer.js';
+import { acceptVaultRoute, applyVaultQuota, declineVaultRoute, forgetPendingVaultDiscovery, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, vaultRoutingRows, } from './roster.js';
 import { SAFETY_POLL_MS } from './watch.js';
 /**
  * One plugin host's view of its vault accounts. It turns vault credentials
@@ -35,9 +36,13 @@ export class ClaustrumConsumer {
     #insulaSkips = new Map();
     /** When this instance last completed a discovery, by `now`. */
     #discoveredAt;
+    #releaseQuotaWriter;
     constructor(options) {
         this.#options = options;
         this.#logger = options.logger ?? createLogger('claustrum');
+        this.#releaseQuotaWriter = retainVaultQuotaWriter(options.rosterPath, (publication) => {
+            this.#roster = applyVaultQuota(this.#roster, publication).roster;
+        });
     }
     #assertOpen(signal) {
         this.#shutdown.signal.throwIfAborted();
@@ -176,11 +181,9 @@ export class ClaustrumConsumer {
             let discovered;
             const roster = await refreshVaultRoster({
                 path: this.#options.rosterPath,
-                custody: {
-                    discover: async (signal) => {
-                        discovered = await custody.discover(signal);
-                        return discovered;
-                    },
+                custody,
+                onInventory: (inventory) => {
+                    discovered = inventory;
                 },
                 isActive: () => this.#active(),
                 signal: this.#shutdown.signal,
@@ -193,7 +196,7 @@ export class ClaustrumConsumer {
             });
             this.#assertOpen();
             const changed = roster?.view !== this.#roster?.view;
-            this.#roster = roster;
+            this.#roster = pendingVaultQuota(this.#options.rosterPath, roster);
             custody.retain(roster?.rows ?? []);
             // Each discovery replaces the previous value, including with unknown. A
             // refresh that served a peer's roster discovered nothing and leaves it;
@@ -349,7 +352,7 @@ export class ClaustrumConsumer {
             return undefined;
         try {
             await readClaustrumEnrollmentToken(this.#options.tokenPath);
-            const roster = await readVaultRoster(this.#options.rosterPath);
+            const roster = pendingVaultQuota(this.#options.rosterPath, await readVaultRoster(this.#options.rosterPath));
             const row = roster?.rows.find((entry) => entry.routeId === routeId);
             return this.#normalizeInsulaQuota(row?.accountIdentity);
         }
@@ -364,7 +367,7 @@ export class ClaustrumConsumer {
             return { miss: 'unreachable' };
         try {
             await readClaustrumEnrollmentToken(this.#options.tokenPath);
-            const roster = await readVaultRoster(this.#options.rosterPath);
+            const roster = pendingVaultQuota(this.#options.rosterPath, await readVaultRoster(this.#options.rosterPath));
             const account = roster?.rows.find((row) => row.routeId === routeId)?.accountIdentity;
             if (!account || !this.#insula)
                 return { miss: 'unreachable' };
@@ -419,7 +422,7 @@ export class ClaustrumConsumer {
             this.#insula = undefined;
             throw new ClaustrumConsumerError('not-active', 'Claustrum scoped custody is not active');
         }
-        const current = await readVaultRoster(this.#options.rosterPath);
+        const current = pendingVaultQuota(this.#options.rosterPath, await readVaultRoster(this.#options.rosterPath));
         this.#assertOpen(signal);
         const observed = roster.rows.find((row) => row.routeId === routeId);
         const configured = current?.rows.find((row) => row.routeId === routeId);
@@ -511,13 +514,13 @@ export class ClaustrumConsumer {
     async decline(routeId) {
         this.#assertOpen();
         await declineVaultRoute(this.#options.rosterPath, routeId);
-        this.#roster = await readVaultRoster(this.#options.rosterPath);
+        this.#roster = pendingVaultQuota(this.#options.rosterPath, await readVaultRoster(this.#options.rosterPath));
         this.#custody?.retain(this.#roster?.rows ?? []);
     }
     async accept(routeId) {
         this.#assertOpen();
         await acceptVaultRoute(this.#options.rosterPath, routeId);
-        this.#roster = await readVaultRoster(this.#options.rosterPath);
+        this.#roster = pendingVaultQuota(this.#options.rosterPath, await readVaultRoster(this.#options.rosterPath));
     }
     /**
      * Store a quota or profile observation for a vault route. The receipt the
@@ -527,7 +530,7 @@ export class ClaustrumConsumer {
      */
     async recordQuota(routeId, observation, attempt) {
         this.#assertOpen();
-        const kept = await recordVaultQuota(this.#options.rosterPath, {
+        return recordVaultQuota(this.#options.rosterPath, {
             routeId,
             observation,
             credentialId: attempt.credentialId,
@@ -539,27 +542,21 @@ export class ClaustrumConsumer {
                 expectedAccountIdentity: attempt.expectedAccountIdentity,
             }),
         });
-        if (kept)
-            this.#roster = await readVaultRoster(this.#options.rosterPath);
-        return kept;
     }
     /**
      * Store a background observation that belongs to an account rather than to
      * a served credential (an insula reading from `cachedInsulaQuotaForRoute`).
      * It lands only while the route is still bound to that known account, so no
      * credential fetch is needed and a replaced account's reading is dropped.
-     * The in-memory roster is reloaded from the file, without a vault call.
+     * Memory updates immediately; durable publication is detached and coalesced.
      */
     async recordAccountQuota(routeId, accountIdentity, observation) {
         this.#assertOpen();
-        const kept = await recordVaultAccountQuota(this.#options.rosterPath, {
+        return recordVaultAccountQuota(this.#options.rosterPath, {
             routeId,
             accountIdentity,
             observation,
         });
-        if (kept)
-            this.#roster = await readVaultRoster(this.#options.rosterPath);
-        return kept;
     }
     close() {
         if (this.#shutdown.signal.aborted)
@@ -574,5 +571,12 @@ export class ClaustrumConsumer {
         this.#insula = undefined;
         this.#roster = undefined;
         this.#grantReach = undefined;
+        void this.#releaseQuotaWriter();
+        forgetPendingVaultDiscovery(this.#options.rosterPath);
+    }
+    /** Close immediately; the last consumer also waits for the writer's bounded drain. */
+    async dispose() {
+        this.close();
+        await this.#releaseQuotaWriter();
     }
 }

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

@@ -1,4 +1,9 @@
 import { type ClaustrumClientOptions as ClaustrumEnrollmentClientOptions, type EnrollmentPollOutcome, type EnrollmentTokenFile, writeEnrollmentTokenFile } from '@cortexkit/claustrum-client';
+/**
+ * The code a vault without the enrollment ceremony answers a proposal with.
+ * Setup reports it as "this vault cannot connect plugins" instead of waiting.
+ */
+export declare const UNSUPPORTED_ENROLLMENT_CODE = "unknown_method";
 /**
  * Codes the vault's closed enrollment-refusal vocabulary marks permanent. The
  * client labels some module error frames transient/retry regardless, so the

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

@@ -10,12 +10,22 @@ const ENROLLMENT_SCHEMA = 1;
 const ENROLLMENT_FILE_MAX_BYTES = 16 * 1024;
 const ENROLLMENT_LOCK_TTL_MS = 30_000;
 const TOKEN_RE = /^[0-9a-f]{64}$/;
+/**
+ * The code a vault without the enrollment ceremony answers a proposal with.
+ * Setup reports it as "this vault cannot connect plugins" instead of waiting.
+ */
+export const UNSUPPORTED_ENROLLMENT_CODE = 'unknown_method';
 /**
  * Codes the vault's closed enrollment-refusal vocabulary marks permanent. The
  * client labels some module error frames transient/retry regardless, so the
  * producer's code takes precedence over the client's action for these.
  */
 export const TERMINAL_ENROLLMENT_CODES = new Set([
+    // The daemon's answer to an operation it does not implement: a vault built
+    // before the enrollment ceremony. It arrives as a transport Error frame with
+    // no class, which claustrum-client before 0.13.0 labels transient/retry, but
+    // asking again can never succeed.
+    UNSUPPORTED_ENROLLMENT_CODE,
     'invalid_params',
     'pending_exists',
     'not_found',
@@ -638,6 +648,23 @@ export class ClaustrumEnrollmentManager {
                             retryCode: refusal.code,
                         };
                     }
+                    // A vault without the ceremony cannot hold a request for this
+                    // proposal, now or from an earlier run (the state has no request
+                    // id). So nothing is blocked and nothing is in progress: remove the
+                    // pending state, still under the ceremony lock, so status reads as
+                    // "not enrolled" and a reset or a later run starts afresh.
+                    if (refusal.code === UNSUPPORTED_ENROLLMENT_CODE) {
+                        await lock.assertOwned();
+                        await unlink(this.#paths.statePath).catch((cause) => {
+                            if (cause.code !== 'ENOENT')
+                                throw cause;
+                        });
+                        return {
+                            state: 'unavailable',
+                            proposedName: state.proposedName,
+                            code: refusal.code,
+                        };
+                    }
                     return this.#block(state, refusal.code);
                 }
             }

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

@@ -9,6 +9,7 @@ export { ClaustrumConsumerError, type ClaustrumConsumerFailureKind, type Claustr
 export { assertHostSlotMatchesMode, assertNotCustodyPlaceholder, CUSTODY_PLACEHOLDER_PREFIX, classifyHostSlot, custodyPlaceholder, custodyPlaceholderKey, type HostSlotContent, isCustodyPlaceholder, isCustodyPlaceholderValue, } from './host-slot.js';
 export { acquireInsulaQuotaSource, type InsulaQuotaContext, type InsulaQuotaLookup, type InsulaQuotaMiss, type InsulaQuotaOptions, type InsulaQuotaReading, type InsulaQuotaResult, type InsulaQuotaSource, type InsulaUsageEntry, type InsulaUsageTransport, type InsulaUsageWatch, type InsulaUsageWindow, type InsulaWatchOptions, } from './insula.js';
 export { acceptAccount, type DeclinedAccount, declineAccount, isDeclined, } from './interlock.js';
+export { drainVaultQuota } from './quota-writer.js';
 export { type AccountMapper, acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, type MutateVaultRosterOptions, mutateVaultRoster, type ProjectionOptions, projectVaultRoster, type QuotaReceipt, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, resolveVaultPrimary, type VaultPrimary, type VaultPrimaryBinding, type VaultPrimaryUnavailableReason, type VaultRosterFile, type VaultRosterLockContext, type VaultRosterRow, vaultRoutingRows, } from './roster.js';
 export { type ChangeNotice, ChangeNoticeReader, RESUBSCRIBE_BACKOFF_MS, SAFETY_POLL_MS, ScopedRosterWatch, type ScopedRosterWatchOptions, type ScopedWatchEnd, type ScopedWatchHandle, type ScopedWatchNoticeShape, type ScopedWatchSource, WATCH_RETRY_MS, type WatchMode, } from './watch.js';
 /**

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

@@ -14,6 +14,7 @@ export { ClaustrumConsumerError, } from './errors.js';
 export { assertHostSlotMatchesMode, assertNotCustodyPlaceholder, CUSTODY_PLACEHOLDER_PREFIX, classifyHostSlot, custodyPlaceholder, custodyPlaceholderKey, isCustodyPlaceholder, isCustodyPlaceholderValue, } from './host-slot.js';
 export { acquireInsulaQuotaSource, } from './insula.js';
 export { acceptAccount, declineAccount, isDeclined, } from './interlock.js';
+export { drainVaultQuota } from './quota-writer.js';
 export { acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, mutateVaultRoster, projectVaultRoster, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, resolveVaultPrimary, vaultRoutingRows, } from './roster.js';
 export { ChangeNoticeReader, RESUBSCRIBE_BACKOFF_MS, SAFETY_POLL_MS, ScopedRosterWatch, WATCH_RETRY_MS, } from './watch.js';
 /**

package/dist/common-auth-embedded/claustrum/quota-writer.d.ts

@@ -0,0 +1,18 @@
+import { type QuotaObservation } from '../quota/index.js';
+import { type QuotaReceipt, type VaultRosterFile } from './roster.js';
+export type VaultQuotaPublication = {
+    routeId: string;
+    accountIdentity?: string;
+    receipt?: QuotaReceipt;
+    observation: QuotaObservation;
+};
+type Listener = (publication: VaultQuotaPublication) => void;
+/** Retain the shared writer; the last consumer's close drains it. */
+export declare function retainVaultQuotaWriter(path: string, listener: Listener): () => Promise<void>;
+/** Enqueue without filesystem work; each quota field retains its own receipt fence. */
+export declare function enqueueVaultQuota(path: string, publication: VaultQuotaPublication): Promise<boolean>;
+/** Overlay uncommitted observations when a consumer reloads the durable roster. */
+export declare function pendingVaultQuota(path: string, roster: VaultRosterFile | undefined): VaultRosterFile | undefined;
+/** Wait at most timeoutMs for detached publication; shutdown loss is acceptable. */
+export declare function drainVaultQuota(path: string, timeoutMs?: number): Promise<void>;
+export {};

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