@cortexkit/antigravity-auth-core 3.0.6 → 3.0.8

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

@@ -1,14 +1,16 @@
 import { type ClaustrumClientOptions } from '@cortexkit/claustrum-client';
 import type { ClaustrumScopedClient } from './custody.js';
 export { ClaustrumCredentialError, type ClaustrumReporterSource, type EnrollmentTokenFile, } from '@cortexkit/claustrum-client';
-export { ClaustrumConsumer, type ClaustrumConsumerOptions, type SendOptions, } from './consumer.js';
-export { type AccountIdentitySource, type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, ClaustrumScopedCustody, type ClaustrumScopedIdentity, decideScopedRetryAfter401, type IdentityParser, isScopedCredentialRotation, type ScopedRetryReason, SERVING_MARGIN_MS, type SkippedVaultReason, type SkippedVaultRecord, type VaultCredential, type VaultCredentialType, type VaultInventory, } from './custody.js';
+export { ClaustrumUnreachableError, classifyVaultFailure, VAULT_FAILURE_CLASSES, type VaultFailureClass, } from './availability.js';
+export { ClaustrumConsumer, type ClaustrumConsumerOptions, type ClaustrumWatchState, type SendOptions, } from './consumer.js';
+export { type AccountIdentitySource, type ClaustrumFamily, type ClaustrumRosterWatch, type ClaustrumRosterWatchOptions, type ClaustrumScopedAttempt, type ClaustrumScopedClient, ClaustrumScopedCustody, type ClaustrumScopedIdentity, decideScopedRetryAfter401, type IdentityParser, isScopedCredentialRotation, KEPT_RECEIPT_MARGIN_MS, type KeptReceiptState, type ScopedRetryReason, SERVING_MARGIN_MS, type SkippedVaultReason, type SkippedVaultRecord, type VaultCredential, type VaultCredentialType, type VaultGrantReach, type VaultGrantTuple, type VaultInventory, } from './custody.js';
 export { type ClaustrumEnrollmentClient, type ClaustrumEnrollmentConnection, type ClaustrumEnrollmentDisconnectResult, ClaustrumEnrollmentManager, type ClaustrumEnrollmentPaths, type ClaustrumEnrollmentResetResult, type ClaustrumEnrollmentStatus, classifyEnrollmentError, connectClaustrumEnrollmentClient, disconnectClaustrumEnrollment, type EnrollmentDisposition, enrollmentAuthority, enrollmentName, getClaustrumEnrollmentPaths, hostEnrollmentPaths, RETRYABLE_ENROLLMENT_CODES, readClaustrumEnrollmentStatus, readClaustrumEnrollmentToken, resetClaustrumEnrollmentState, TERMINAL_ENROLLMENT_CODES, } from './enrollment.js';
 export { ClaustrumConsumerError, type ClaustrumConsumerFailureKind, type ClaustrumLogger, } from './errors.js';
 export { assertHostSlotMatchesMode, assertNotCustodyPlaceholder, CUSTODY_PLACEHOLDER_PREFIX, classifyHostSlot, custodyPlaceholder, custodyPlaceholderKey, type HostSlotContent, isCustodyPlaceholder, isCustodyPlaceholderValue, } from './host-slot.js';
-export type { InsulaQuotaContext, InsulaQuotaOptions, InsulaUsageEntry, InsulaUsageTransport, InsulaUsageWindow, } from './insula.js';
+export { acquireInsulaQuotaSource, type InsulaQuotaContext, type InsulaQuotaOptions, 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 { 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';
 /**
  * Connect the client that lists and fetches this consumer's vault credentials
  * on the request path. `connectionFile` is required: this library

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

@@ -6,13 +6,16 @@
 import { ClaustrumClient, } from '@cortexkit/claustrum-client';
 import { insulaUsageTransport } from './insula.js';
 export { ClaustrumCredentialError, } from '@cortexkit/claustrum-client';
+export { ClaustrumUnreachableError, classifyVaultFailure, VAULT_FAILURE_CLASSES, } from './availability.js';
 export { ClaustrumConsumer, } from './consumer.js';
-export { ClaustrumScopedCustody, decideScopedRetryAfter401, isScopedCredentialRotation, SERVING_MARGIN_MS, } from './custody.js';
+export { ClaustrumScopedCustody, decideScopedRetryAfter401, isScopedCredentialRotation, KEPT_RECEIPT_MARGIN_MS, SERVING_MARGIN_MS, } from './custody.js';
 export { ClaustrumEnrollmentManager, classifyEnrollmentError, connectClaustrumEnrollmentClient, disconnectClaustrumEnrollment, enrollmentAuthority, enrollmentName, getClaustrumEnrollmentPaths, hostEnrollmentPaths, RETRYABLE_ENROLLMENT_CODES, readClaustrumEnrollmentStatus, readClaustrumEnrollmentToken, resetClaustrumEnrollmentState, TERMINAL_ENROLLMENT_CODES, } from './enrollment.js';
 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 { 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';
 /**
  * Connect the client that lists and fetches this consumer's vault credentials
  * on the request path. `connectionFile` is required: this library

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

@@ -1,4 +1,5 @@
 import type { ClaustrumClientOptions } from '@cortexkit/claustrum-client';
+import { type WatchMode } from './watch.js';
 /** Insula's window fields are open: plugins choose which limits they understand. */
 export interface InsulaUsageWindow {
     usedPercent: number;
@@ -43,21 +44,68 @@ export interface InsulaQuotaOptions<Q> {
      */
     normalize: (entry: InsulaUsageEntry, context: InsulaQuotaContext) => Q | undefined;
 }
+/**
+ * A held-open `usage.watch` stream. `closed` resolves when insula ends the
+ * stream (STREAM_END at shutdown, or a reply that ends it) or after `stop()`,
+ * and rejects with insula's refusal (an error with a `code`, such as
+ * `unknown_method` from an insula that predates the method, or
+ * `usage_watch_limit` when 64 watches are already open) or with the
+ * transport failure.
+ */
+export interface InsulaUsageWatch {
+    stop(): void;
+    readonly closed: Promise<void>;
+}
 /** Optional transport for custom scoped clients; getUsage must not retry refusals. */
 export interface InsulaUsageTransport {
     connectionFile: string;
     getUsage(): Promise<unknown>;
+    /**
+     * Open a `usage.watch` stream, passing each notice's raw JSON body to
+     * `onNotice`. Optional: a transport without it is polled as before.
+     */
+    watchUsage?(onNotice: (body: Uint8Array) => void): InsulaUsageWatch;
 }
 /** Constructing this transport opens no connection; getUsage opens one per call. */
 export declare function insulaUsageTransport(options: ClaustrumClientOptions & {
     connectionFile: string;
 }): InsulaUsageTransport;
+export interface InsulaWatchOptions {
+    /**
+     * The provider this watcher reads. A notice that names only other
+     * providers then needs no read; unset means every notice does.
+     */
+    provider?: string;
+    /**
+     * setTimeout and clearTimeout for the waits before re-subscribing or retrying
+     * a watch. Defaults to the global timers; tests inject virtual ones.
+     */
+    setTimeoutImpl?: typeof setTimeout;
+    clearTimeoutImpl?: typeof clearTimeout;
+}
 export declare class InsulaQuotaSource {
     #private;
     private readonly transport;
     private readonly key;
     constructor(transport: InsulaUsageTransport, key: string);
+    /**
+     * The background poll: at most one usage.get per minute per daemon and
+     * enrollment token. While a watch is open it reads nothing, because insula's
+     * notices announce every new reading. If insula stops announcing an account,
+     * that account's last entry grows older than the freshness limit `current()`
+     * applies, `current()` returns nothing for it, and the plugin falls back to
+     * its own provider poll for that account.
+     */
     refresh(now: number): Promise<void>;
+    /** How this source currently learns about usage changes, for logs. */
+    watchMode(): WatchMode;
+    /**
+     * Hold a `usage.watch` open while any watcher wants it, and re-read
+     * usage.get when a notice says something changed. Watchers of one source
+     * share one watch, since insula admits only 64 per process. Returns the
+     * release; the last release closes the watch.
+     */
+    watch(options?: InsulaWatchOptions): () => void;
     current(provider: string, accountId: string, now: number): {
         entry: InsulaUsageEntry;
         context: InsulaQuotaContext;

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

@@ -5,6 +5,8 @@ import { storeIdentity } from '@cortexkit/claustrum-client';
 // import makes bundlers emit a separate chunk that a running host loses when
 // its dist folder is rebuilt underneath it.
 import { SubcClient } from '@cortexkit/subc-client';
+import { classifyVaultFailure } from './availability.js';
+import { ChangeNoticeReader, CoalescedRead, RESUBSCRIBE_BACKOFF_MS, WATCH_RETRY_MS, } from './watch.js';
 /** Constructing this transport opens no connection; getUsage opens one per call. */
 export function insulaUsageTransport(options) {
     const identity = options.identity ??
@@ -49,6 +51,79 @@ export function insulaUsageTransport(options) {
                 client?.close();
             }
         },
+        watchUsage(onNotice) {
+            // The watch holds its own connection for as long as it is open: each
+            // usage.get above opens and closes a short-lived one, and the scoped
+            // credential connection is never shared with insula. The method name
+            // alone makes the request a watch; subc-client does not yet set the
+            // SUBSCRIPTION flag, and insula does not require it.
+            let client;
+            let subscription;
+            let stopped = false;
+            const closed = (async () => {
+                let deadline;
+                const timeout = new Promise((_resolve, reject) => {
+                    deadline = setTimeout(
+                    // Coded as a timeout, so InsulaQuotaSource treats a watch that could
+                    // not open in time as an unreachable insula and tries again later,
+                    // not as a refusal.
+                    () => reject(Object.assign(new Error('insula watch timeout'), {
+                        code: 'timeout',
+                    })), 3_000);
+                    deadline.unref?.();
+                });
+                const open = (async () => {
+                    const handshakeTimeoutMs = Math.min(options.handshakeTimeoutMs ?? 3_000, 3_000);
+                    const connected = options.connector
+                        ? await options.connector({
+                            connectionFile: options.connectionFile,
+                            handshakeTimeoutMs,
+                        })
+                        : await SubcClient.connect({
+                            connectionFile: options.connectionFile,
+                            handshakeTimeoutMs,
+                        });
+                    client = connected;
+                    // A connection that arrives after stop() or after the open deadline
+                    // must not keep a route or socket alive.
+                    if (stopped) {
+                        connected.close();
+                        return;
+                    }
+                    const route = await connected.routeOpen({ kind: 'management_surface', module_id: 'insula' }, identity);
+                    if (stopped) {
+                        connected.close();
+                        return;
+                    }
+                    subscription = connected.subscribe(route, { method: 'usage.watch' }, onNotice);
+                })();
+                try {
+                    await Promise.race([open, timeout]);
+                }
+                catch (error) {
+                    stopped = true;
+                    throw error;
+                }
+                finally {
+                    clearTimeout(deadline);
+                }
+                if (subscription)
+                    await subscription.closed;
+            })().finally(() => {
+                stopped = true;
+                client?.close();
+            });
+            return {
+                stop() {
+                    if (stopped)
+                        return;
+                    stopped = true;
+                    subscription?.unsubscribe();
+                    client?.close();
+                },
+                closed,
+            };
+        },
     };
 }
 const MINUTE = 60_000;
@@ -60,18 +135,92 @@ const attempts = new Map();
 function record(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+function decodeUsageNotice(body) {
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(body));
+    }
+    catch {
+        return undefined;
+    }
+    if (!record(value) ||
+        typeof value.kind !== 'string' ||
+        typeof value.epoch !== 'string' ||
+        value.epoch.length === 0 ||
+        typeof value.seq !== 'number' ||
+        !Number.isSafeInteger(value.seq) ||
+        value.seq < 1 ||
+        (value.provider !== undefined && typeof value.provider !== 'string'))
+        return undefined;
+    return {
+        kind: value.kind,
+        epoch: value.epoch,
+        seq: value.seq,
+        ...(typeof value.provider === 'string' && { provider: value.provider }),
+    };
+}
+function refusalCode(error) {
+    return error instanceof Error &&
+        'code' in error &&
+        typeof error.code === 'string'
+        ? error.code
+        : undefined;
+}
 export class InsulaQuotaSource {
     transport;
     key;
     #entries = [];
-    #pending;
+    /** Every usage.get, polled or watch-driven, shares this one slot. */
+    #reads = new CoalescedRead(async () => {
+        try {
+            const reply = await this.transport.getUsage();
+            if (!record(reply) ||
+                !Array.isArray(reply.result) ||
+                reply.error !== undefined)
+                throw new Error('unavailable insula usage');
+            // Each response is a snapshot, not a delta. Missing accounts fall back;
+            // neither pending nor the entry count asserts provider completeness.
+            this.#entries = reply.result.filter((entry) => record(entry) && typeof entry.provider === 'string');
+        }
+        catch {
+            // Refusal is absence, even if the previous reading was still young.
+            this.#entries = [];
+        }
+    }, () => { });
+    #reader = new ChangeNoticeReader();
+    #mode = 'polling';
+    #watchers = 0;
+    /**
+     * How many registered watchers read every provider. Watchers limited to one
+     * provider are counted per provider in `#providers` instead.
+     */
+    #everyProvider = 0;
+    #providers = new Map();
+    #watch;
+    #timer;
+    #timers = {};
+    /**
+     * How many accepted watches in a row have closed; each one doubles the wait
+     * before the next re-subscribe. Reset once a watch brings a second notice.
+     */
+    #closes = 0;
     constructor(transport, key) {
         this.transport = transport;
         this.key = key;
     }
+    /**
+     * The background poll: at most one usage.get per minute per daemon and
+     * enrollment token. While a watch is open it reads nothing, because insula's
+     * notices announce every new reading. If insula stops announcing an account,
+     * that account's last entry grows older than the freshness limit `current()`
+     * applies, `current()` returns nothing for it, and the plugin falls back to
+     * its own provider poll for that account.
+     */
     refresh(now) {
-        if (this.#pending)
-            return this.#pending;
+        if (this.#reads.running)
+            return this.#reads.running;
+        if (this.#mode === 'watching')
+            return Promise.resolve();
         for (const [key, time] of attempts) {
             if (now - time >= MINUTE)
                 attempts.delete(key);
@@ -81,25 +230,141 @@ export class InsulaQuotaSource {
             return Promise.resolve();
         // Reserve the minute before I/O, so concurrent projects cannot each poll.
         attempts.set(this.key, now);
-        this.#pending = (async () => {
-            try {
-                const reply = await this.transport.getUsage();
-                if (!record(reply) ||
-                    !Array.isArray(reply.result) ||
-                    reply.error !== undefined)
-                    throw new Error('unavailable insula usage');
-                // Each response is a snapshot, not a delta. Missing accounts fall back;
-                // neither pending nor the entry count asserts provider completeness.
-                this.#entries = reply.result.filter((entry) => record(entry) && typeof entry.provider === 'string');
-            }
-            catch {
-                // Refusal is absence, even if the previous reading was still young.
-                this.#entries = [];
+        return this.#reads.request();
+    }
+    /** How this source currently learns about usage changes, for logs. */
+    watchMode() {
+        return this.#mode;
+    }
+    /**
+     * Hold a `usage.watch` open while any watcher wants it, and re-read
+     * usage.get when a notice says something changed. Watchers of one source
+     * share one watch, since insula admits only 64 per process. Returns the
+     * release; the last release closes the watch.
+     */
+    watch(options = {}) {
+        this.#watchers++;
+        const provider = options.provider;
+        if (provider === undefined)
+            this.#everyProvider++;
+        else
+            this.#providers.set(provider, (this.#providers.get(provider) ?? 0) + 1);
+        if (this.#watchers === 1) {
+            this.#timers = options;
+            this.#open();
+        }
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            if (provider === undefined)
+                this.#everyProvider--;
+            else {
+                const left = (this.#providers.get(provider) ?? 1) - 1;
+                if (left > 0)
+                    this.#providers.set(provider, left);
+                else
+                    this.#providers.delete(provider);
             }
-        })().finally(() => {
-            this.#pending = undefined;
-        });
-        return this.#pending;
+            if (--this.#watchers === 0)
+                this.#stopWatch();
+        };
+    }
+    #stopWatch() {
+        if (this.#timer)
+            (this.#timers.clearTimeoutImpl ?? clearTimeout)(this.#timer);
+        this.#timer = undefined;
+        const watch = this.#watch;
+        this.#watch = undefined;
+        watch?.handle?.stop();
+        this.#mode = 'polling';
+    }
+    #later(delay) {
+        this.#timer = (this.#timers.setTimeoutImpl ?? setTimeout)(() => {
+            this.#timer = undefined;
+            if (this.#watchers > 0 && !this.#watch)
+                this.#open();
+        }, delay);
+        this.#timer.unref?.();
+    }
+    #open() {
+        const watchUsage = this.transport.watchUsage;
+        if (!watchUsage) {
+            // A custom transport that cannot watch: poll exactly as before.
+            this.#mode = 'fallback';
+            return;
+        }
+        this.#mode = 'polling';
+        this.#reader.restart();
+        const watch = { notices: 0 };
+        this.#watch = watch;
+        let handle;
+        try {
+            handle = watchUsage.call(this.transport, (body) => this.#notice(watch, body));
+        }
+        catch (error) {
+            this.#closed(watch, error);
+            return;
+        }
+        watch.handle = handle;
+        handle.closed.then(() => this.#closed(watch, undefined), (error) => this.#closed(watch, error));
+    }
+    #notice(watch, body) {
+        // Frames already in transport can arrive after a local stop.
+        if (this.#watch !== watch)
+            return;
+        watch.notices++;
+        if (watch.notices === 1)
+            this.#mode = 'watching';
+        // A second notice means the watch stayed up past its acceptance.
+        if (watch.notices === 2)
+            this.#closes = 0;
+        const notice = decodeUsageNotice(body);
+        // An unreadable notice may hide any change: treat it as a break, and
+        // make the next notice read as one too.
+        if (!notice)
+            this.#reader.restart();
+        const continuous = notice ? this.#reader.continuous(notice) : false;
+        // The first notice of every watch names no provider, so it always reads:
+        // nothing was watched before it. After a gap or a new epoch notices were
+        // lost, so read even when this notice names another provider.
+        if (!continuous ||
+            notice?.provider === undefined ||
+            this.#everyProvider > 0 ||
+            this.#providers.has(notice.provider))
+            void this.#reads.request();
+    }
+    #closed(watch, error) {
+        if (this.#watch !== watch)
+            return;
+        this.#watch = undefined;
+        const code = refusalCode(error);
+        if (code === 'unknown_method' || code === 'usage_watch_limit') {
+            // An insula that predates usage.watch, or one already holding 64
+            // watches: poll exactly as before until every watcher has released.
+            this.#mode = 'fallback';
+            return;
+        }
+        if (watch.notices > 0) {
+            // An accepted watch that closed (insula shut down, or the connection
+            // dropped) gets one new watch, whose first notice reads usage.get.
+            const delay = Math.min(RESUBSCRIBE_BACKOFF_MS * 2 ** Math.min(this.#closes, 16), WATCH_RETRY_MS);
+            this.#closes++;
+            this.#mode = 'polling';
+            this.#later(delay);
+            return;
+        }
+        // Closed before any notice, so never accepted: read once to learn
+        // whether insula answers at all, then poll as before. A refusal insula
+        // answered stands until every watcher has released. A close it did not
+        // explain (a
+        // dropped connection, a timeout, a stream ended at once while insula
+        // shuts down) earns one new watch much later.
+        this.#mode = 'fallback';
+        void this.#reads.request();
+        if (error === undefined || classifyVaultFailure(error) === 'unreachable')
+            this.#later(WATCH_RETRY_MS);
     }
     current(provider, accountId, now) {
         for (const entry of this.#entries) {

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

@@ -0,0 +1,141 @@
+import type { ClaustrumLogger } from './errors.js';
+/**
+ * How a host currently learns about changes, for logs and status displays.
+ * `watching`: a watch was accepted and is open, so polling is reduced to a
+ * slow safety read. `polling`: no watch is open yet (not started, opening, or
+ * re-subscribing after a close), so the host polls at its usual interval.
+ * `fallback`: the watch is unavailable (an older module or client, a refusal,
+ * the watch limit, or repeated failures), so the host polls at its usual
+ * interval and may try a watch again later. Never carries secrets.
+ */
+export type WatchMode = 'watching' | 'polling' | 'fallback';
+/**
+ * While a vault watch is healthy, the roster is still read this often: the
+ * watch carries no history, so a lost notice or a silently dead stream is
+ * caught within this period.
+ */
+export declare const SAFETY_POLL_MS: number;
+/**
+ * After a watch fails without being accepted, the host polls and tries one
+ * new watch this much later, so a refusing or draining module is never asked
+ * in a tight loop.
+ */
+export declare const WATCH_RETRY_MS: number;
+/**
+ * First wait before re-subscribing a watch that closed after it had been
+ * accepted. It doubles for each further close in a row, up to WATCH_RETRY_MS.
+ */
+export declare const RESUBSCRIBE_BACKOFF_MS = 1000;
+/**
+ * The fields every change notice carries, from the vault's watchScoped and
+ * insula's usage.watch alike.
+ */
+export interface ChangeNotice {
+    readonly kind: string;
+    readonly epoch: string;
+    readonly seq: number;
+}
+/**
+ * Tells whether a notice follows the previous one with nothing lost between
+ * them. `seq` restarts at 1 for every watch and `epoch` names the sending
+ * module's process lifetime. A sequence gap (notices are sheddable), a
+ * different epoch (the module restarted) or a notice of an unknown kind all
+ * mean changes may have been missed, so the caller must re-read everything.
+ */
+export declare class ChangeNoticeReader {
+    #private;
+    /**
+     * Begin a new watch, whose first notice is seq 1 again. The epoch is kept,
+     * so a module restart between two watches still reads as a break.
+     */
+    restart(): void;
+    continuous(notice: ChangeNotice): boolean;
+}
+/**
+ * Runs `read` with at most one call in flight and at most one more queued
+ * behind it, however many requests arrive meanwhile. A request made while a
+ * read is running may have arrived after that read took its snapshot, so it
+ * earns exactly one more read; any further requests share that one.
+ */
+export declare class CoalescedRead {
+    #private;
+    constructor(read: () => Promise<void>, onError: (error: unknown) => void);
+    /** The read in flight (including its queued follow-up), if any. */
+    get running(): Promise<void> | undefined;
+    request(): Promise<void>;
+}
+/** A vault watch notice: `view` is the same digest `list_scoped` returns. */
+export interface ScopedWatchNoticeShape extends ChangeNotice {
+    readonly view: string;
+}
+/**
+ * How a vault watch ended, as claustrum-client 0.12.0 reports it. `refused`
+ * and `not_accepting` both mean the watch closed before its first notice; the
+ * client then made one `list_scoped` read to learn why, and `refused` carries
+ * that read's refusal.
+ */
+export type ScopedWatchEnd = {
+    readonly kind: 'refused';
+    readonly error: unknown;
+} | {
+    readonly kind: 'transport_lost';
+    readonly error: unknown;
+} | {
+    readonly kind: 'ended' | 'not_accepting' | 'unsupported' | 'stopped';
+};
+export interface ScopedWatchHandle {
+    stop(): void;
+    readonly closed: Promise<ScopedWatchEnd>;
+}
+/**
+ * The part of a vault client that can watch. claustrum-client added
+ * `watchScoped` in 0.12.0; the peer range still admits 0.6.2, so it is
+ * optional and detected at run time.
+ */
+export interface ScopedWatchSource {
+    watchScoped?(onNotice: (notice: ScopedWatchNoticeShape) => void, options?: {
+        enrollmentToken?: string;
+    }): ScopedWatchHandle;
+}
+export interface ScopedRosterWatchOptions {
+    client: ScopedWatchSource;
+    /** The enrollment token, read again for every watch so a new one is used. */
+    enrollmentToken: () => Promise<string>;
+    /** The view of the roster this host last discovered; undefined for none. */
+    view: () => string | undefined;
+    /**
+     * The host's existing discovery: `list_scoped`, the roster commit and
+     * everything that follows it. The watch never reads the vault list itself.
+     * `view` is the view the newest notice carried.
+     */
+    discover: (view: string) => Promise<unknown>;
+    /**
+     * The vault refused the watch, and the confirming `list_scoped` read it
+     * with this error (a revoked enrollment ends both with `not_found`). Handle
+     * it as discovery handles the same refusal from `list_scoped`.
+     */
+    onRefused: (error: unknown) => void;
+    onTransportLost?: () => void;
+    onReachable?: () => void;
+    onError?: (error: unknown) => void;
+    onMode?: (mode: WatchMode) => void;
+    logger?: ClaustrumLogger;
+    now?: () => number;
+    setTimeoutImpl?: typeof setTimeout;
+    clearTimeoutImpl?: typeof clearTimeout;
+}
+/**
+ * Keeps one vault `watchScoped` open for a host and runs the host's discovery
+ * when a notice shows the visible account list changed. Discovery runs only
+ * when the notice's view differs from the last discovered roster's view, when
+ * a notice shows a gap or a new epoch, or on the first notice of a watch that
+ * was re-subscribed after a close (the time between two watches was not
+ * observed). It never opens a second watch while one is open.
+ */
+export declare class ScopedRosterWatch {
+    #private;
+    constructor(options: ScopedRosterWatchOptions);
+    get mode(): WatchMode;
+    start(): void;
+    stop(): void;
+}