@cortexkit/antigravity-auth-core 3.0.12 → 3.0.13

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

@@ -2,21 +2,31 @@ import { type ClaustrumClientOptions } from '@cortexkit/claustrum-client';
 import type { ClaustrumScopedClient } from './custody.js';
 export { ClaustrumCredentialError, type ClaustrumReporterSource, type EnrollmentTokenFile, } from '@cortexkit/claustrum-client';
 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 { ClaustrumConsumer, type ClaustrumConsumerOptions, type ClaustrumWatchState, DEFAULT_CONNECT_TIMEOUT_MS, type SendOptions, } from './consumer.js';
+export { type AccountIdentitySource, type ClassifyingClaustrumFamily, type ClaustrumFamily, type ClaustrumFamilyInput, 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, type VaultRowFacts, } 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 { ClaustrumDiscoveryHub, type ClaustrumDiscoveryHubOptions, type ClaustrumHubMemberOptions, type ClaustrumHubRefusals, type ClaustrumLeasedCustody, type CustodyLease, } from './hub.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, type ReorderVaultRosterOptions, type ReorderVaultRosterResult, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, reorderVaultRoster, resolveVaultPrimary, type VaultPrimary, type VaultPrimaryBinding, type VaultPrimaryUnavailableReason, type VaultRosterFile, type VaultRosterLockContext, type VaultRosterRow, vaultRoutingRows, } from './roster.js';
+export { type AccountMapper, acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, type MutateVaultRosterOptions, mutateVaultRoster, type ProjectionOptions, projectVaultRoster, type QuotaReceipt, type ReorderVaultRosterOptions, type ReorderVaultRosterResult, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, reorderVaultRoster, resolveVaultPrimary, type VaultPrimary, type VaultPrimaryBinding, type VaultPrimaryUnavailableReason, type VaultRosterFile, type VaultRosterLockContext, type VaultRosterRow, type VaultRosterSeed, vaultRosterSeed, 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';
+/** How long `connectClaustrumScopedClient` waits by default. */
+export declare const SCOPED_CONNECT_TIMEOUT_MS = 10000;
 /**
  * Connect the client that lists and fetches this consumer's vault credentials
  * on the request path. `connectionFile` is required: this library
  * reads no environment, so the plugin resolves the vault's connection file.
+ *
+ * The wait is bounded by `connectTimeoutMs` (default 10 s) so a connect that
+ * never settles cannot leave a consumer with a pending connection forever; the
+ * caller then gets an unreachable error and may try again. A socket handshake
+ * has its own limit, but local reads before it (the connection file) do not,
+ * and a client that arrives after this deadline is closed, not returned.
  */
 export declare function connectClaustrumScopedClient(options: ClaustrumClientOptions & {
     connectionFile: string;
+    connectTimeoutMs?: number;
 }): Promise<ClaustrumScopedClient>;

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

@@ -4,25 +4,58 @@
 // declined-account interlock and the host-slot guard. Needs the optional
 // peer `@cortexkit/claustrum-client`.
 import { ClaustrumClient, } from '@cortexkit/claustrum-client';
+import { ClaustrumUnreachableError } from './availability.js';
 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 { ClaustrumConsumer, DEFAULT_CONNECT_TIMEOUT_MS, } from './consumer.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 { ClaustrumDiscoveryHub, } from './hub.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, reorderVaultRoster, resolveVaultPrimary, vaultRoutingRows, } from './roster.js';
+export { acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, mutateVaultRoster, projectVaultRoster, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, reorderVaultRoster, resolveVaultPrimary, vaultRosterSeed, vaultRoutingRows, } from './roster.js';
 export { ChangeNoticeReader, RESUBSCRIBE_BACKOFF_MS, SAFETY_POLL_MS, ScopedRosterWatch, WATCH_RETRY_MS, } from './watch.js';
+/** How long `connectClaustrumScopedClient` waits by default. */
+export const SCOPED_CONNECT_TIMEOUT_MS = 10_000;
 /**
  * Connect the client that lists and fetches this consumer's vault credentials
  * on the request path. `connectionFile` is required: this library
  * reads no environment, so the plugin resolves the vault's connection file.
+ *
+ * The wait is bounded by `connectTimeoutMs` (default 10 s) so a connect that
+ * never settles cannot leave a consumer with a pending connection forever; the
+ * caller then gets an unreachable error and may try again. A socket handshake
+ * has its own limit, but local reads before it (the connection file) do not,
+ * and a client that arrives after this deadline is closed, not returned.
  */
 export async function connectClaustrumScopedClient(options) {
-    const client = await ClaustrumClient.connect(options);
-    return Object.assign(client, { insula: insulaUsageTransport(options) });
+    const { connectTimeoutMs, ...client } = options;
+    const limit = connectTimeoutMs ?? SCOPED_CONNECT_TIMEOUT_MS;
+    const connecting = ClaustrumClient.connect(client);
+    let expired = false;
+    let timer;
+    const deadline = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            expired = true;
+            reject(new ClaustrumUnreachableError());
+        }, limit);
+        timer.unref?.();
+    });
+    try {
+        const client = await Promise.race([connecting, deadline]);
+        return Object.assign(client, { insula: insulaUsageTransport(options) });
+    }
+    catch (error) {
+        // A connection that arrives after the deadline still owns a socket.
+        void connecting.then((client) => client.close(), () => { });
+        throw error;
+    }
+    finally {
+        if (!expired && timer)
+            clearTimeout(timer);
+    }
 }

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

@@ -1,3 +1,4 @@
+import { type QuotaCommitTimer } from '../quota/commit-interval.js';
 import { type QuotaObservation } from '../quota/index.js';
 import { type QuotaReceipt, type VaultRosterFile } from './roster.js';
 export type VaultQuotaPublication = {
@@ -8,11 +9,17 @@ export type VaultQuotaPublication = {
 };
 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>;
+export declare function retainVaultQuotaWriter(path: string, listener: Listener, clock?: QuotaCommitTimer): () => 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;
+/**
+ * Whether this process holds quota readings for `path` that no commit of the
+ * durable roster has written yet, so a reader of the file alone is not seeing
+ * everything this process would publish.
+ */
+export declare function hasPendingVaultQuota(path: string): boolean;
 /** 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

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path';
 import { createLogger } from '../logger/index.js';
+import { QUOTA_COMMIT_INTERVAL_MS, quotaCommitTimer, } from '../quota/commit-interval.js';
 import { isQuotaObservation } from '../quota/index.js';
 import { quotaFields } from '../quota/pending.js';
 import { applyVaultQuota, mutateVaultRoster, } from './roster.js';
@@ -7,7 +8,7 @@ import { applyVaultQuota, mutateVaultRoster, } from './roster.js';
 const writers = new Map();
 const logger = createLogger('claustrum');
 const COALESCE_MS = 100;
-function writerFor(path) {
+function writerFor(path, clock = quotaCommitTimer) {
     const key = resolve(path);
     let writer = writers.get(key);
     if (!writer) {
@@ -17,6 +18,7 @@ function writerFor(path) {
             listeners: new Set(),
             wake: new Set(),
             abort: new AbortController(),
+            clock,
             failures: 0,
             draining: false,
             order: 0,
@@ -26,8 +28,8 @@ function writerFor(path) {
     return writer;
 }
 /** Retain the shared writer; the last consumer's close drains it. */
-export function retainVaultQuotaWriter(path, listener) {
-    const writer = writerFor(path);
+export function retainVaultQuotaWriter(path, listener, clock) {
+    const writer = writerFor(path, clock);
     writer.listeners.add(listener);
     let released;
     return () => (released ??= (() => {
@@ -93,37 +95,57 @@ export function pendingVaultQuota(path, roster) {
     }
     return roster;
 }
+/**
+ * Whether this process holds quota readings for `path` that no commit of the
+ * durable roster has written yet, so a reader of the file alone is not seeing
+ * everything this process would publish.
+ */
+export function hasPendingVaultQuota(path) {
+    return !!writers.get(resolve(path))?.pending.size;
+}
 function schedule(writer, delay) {
     if (writer.running ||
         writer.timer ||
         !writer.pending.size ||
         writer.abort.signal.aborted)
         return;
-    writer.timer = setTimeout(() => {
+    const remaining = writer.draining
+        ? 0
+        : (writer.committedAt ?? -Infinity) +
+            QUOTA_COMMIT_INTERVAL_MS -
+            writer.clock.now();
+    writer.timer = writer.clock.schedule(Math.max(delay, remaining), () => {
         writer.timer = undefined;
-        flush(writer);
-    }, delay);
+        return flush(writer);
+    });
     if (!writer.draining)
         writer.timer.unref?.();
 }
+function cancelTimer(writer) {
+    writer.timer?.cancel();
+    writer.timer = undefined;
+}
 function flush(writer) {
     if (writer.running || writer.abort.signal.aborted)
-        return;
+        return writer.running ?? Promise.resolve();
     const batch = new Map([...writer.pending].map(([account, pending]) => [
         account,
         new Map(pending),
     ]));
     writer.running = (async () => {
         try {
-            await mutateVaultRoster(writer.path, (current) => {
+            const committed = 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 };
+                const changed = JSON.stringify(next) !== JSON.stringify(current);
+                return { ...(changed && { next }), result: changed };
             }, { signal: writer.abort.signal });
+            if (committed)
+                writer.committedAt = writer.clock.now();
             for (const [account, fields] of batch) {
                 const pending = writer.pending.get(account);
                 for (const [key, field] of fields) {
@@ -155,6 +177,7 @@ function flush(writer) {
             schedule(writer, backoff);
         }
     })();
+    return writer.running;
 }
 /** Wait at most timeoutMs for detached publication; shutdown loss is acceptable. */
 export async function drainVaultQuota(path, timeoutMs = 1_000) {
@@ -163,8 +186,7 @@ export async function drainVaultQuota(path, timeoutMs = 1_000) {
     if (!writer)
         return;
     writer.draining = true;
-    clearTimeout(writer.timer);
-    writer.timer = undefined;
+    cancelTimer(writer);
     let deadline;
     let wake;
     const drained = new Promise((done) => {
@@ -194,7 +216,7 @@ export async function drainVaultQuota(path, timeoutMs = 1_000) {
         // must not discard its observations or stop its retries.
         if (!writer.listeners.size) {
             writer.abort.abort();
-            clearTimeout(writer.timer);
+            cancelTimer(writer);
             writer.pending.clear();
             if (writers.get(key) === writer)
                 writers.delete(key);

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

@@ -62,7 +62,25 @@ export interface ProjectionOptions {
     routePrefix?: string;
     mapAccount?: AccountMapper;
     now?: number;
+    /**
+     * Preferences carried over from another roster file, used only when there
+     * is no previous roster: its declines become this roster's declines, and
+     * its account order sorts the rows this inventory produces. No row of the
+     * seed is ever projected, so a seed cannot make an account routable.
+     */
+    seed?: VaultRosterSeed;
+}
+/** The preferences one roster file can pass to a first projection elsewhere. */
+export interface VaultRosterSeed {
+    readonly declined: readonly DeclinedAccount[];
+    /** Accounts in the seed roster's order, matched by account, then by id. */
+    readonly order: readonly {
+        readonly credentialId: string;
+        readonly accountIdentity?: string;
+    }[];
 }
+/** Declines and account order of `roster`, and nothing else of it. */
+export declare function vaultRosterSeed(roster: VaultRosterFile): VaultRosterSeed;
 export declare const DEFAULT_ROUTE_PREFIX = "vault:";
 /**
  * Project the vault's list onto the previous roster. Pure: callers serialize
@@ -87,6 +105,12 @@ export declare function projectVaultRoster(previous: VaultRosterFile | undefined
  * reaches admission.
  */
 export declare function vaultRoutingRows(roster: VaultRosterFile | undefined): RoutingRow[];
+/**
+ * `roster` as `readVaultRoster` decodes it from the file that holds it, so a
+ * committed roster and a later read of its file compare equal. Package
+ * internal: not exported from `/claustrum`.
+ */
+export declare function decodedVaultRoster(roster: VaultRosterFile): VaultRosterFile;
 export declare function readVaultRoster(path: string): Promise<VaultRosterFile | undefined>;
 /** The ownership assertion available to a roster mutation callback. */
 export interface VaultRosterLockContext {
@@ -190,6 +214,16 @@ export declare function applyVaultQuota(current: VaultRosterFile | undefined, in
     kept: boolean;
 };
 export declare function forgetPendingVaultDiscovery(path: string): void;
+/**
+ * Whether `error` from a roster commit at `path` means another writer had the
+ * roster at that moment, not that the commit itself failed: the discovery
+ * lease was busy before any roster existed, the write lock stayed busy, or a
+ * lock this commit held was lost. On Windows the same lock steps can reject
+ * with a PrivateFileError instead (a lock file that could not be read or
+ * replaced while another process held it), so a PrivateFileError naming one
+ * of this roster's lock files counts the same on every OS.
+ */
+export declare function isVaultRosterLockRefusal(path: string, error: unknown): boolean;
 /**
  * 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
@@ -197,7 +231,8 @@ export declare function forgetPendingVaultDiscovery(path: string): void;
  * 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.
+ * unless a peer has superseded its base view in the meantime. A list that
+ * would write the file the roster already holds takes no write lock at all.
  */
 export declare function refreshVaultRoster(options: {
     path: string;
@@ -206,6 +241,19 @@ export declare function refreshVaultRoster(options: {
     signal?: AbortSignal;
     projection?: ProjectionOptions | (() => ProjectionOptions);
     onInventory?: (inventory: VaultInventory) => void;
+    /**
+     * For a caller that listed before taking this path's discovery lease (the
+     * discovery hub lists once for several rosters): the view this roster file
+     * held before that list. `custody.discover` then returns that list. It is
+     * held to the rule a kept discovery is held to below: it is projected only
+     * while the file still holds this view or the list's own view. Otherwise
+     * another process committed since the list, and the file is returned
+     * unchanged. No discovery is kept for a later call, because such a caller
+     * lists again.
+     */
+    listedOver?: {
+        readonly view: string | undefined;
+    };
 }): 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,12 +1,36 @@
 import { createHash } from 'node:crypto';
+import { stat } from 'node:fs/promises';
 import { resolve } from 'node:path';
-import { acquireRefreshFileLock, LockContentionError, withLock, writeJsonAtomic, } from '../fs/index.js';
+import { acquireRefreshFileLock, LockContentionError, LockOwnershipError, lockPathFor, PrivateFileError, withLock, writeJsonAtomic, } from '../fs/index.js';
 import { readPrivateText, windowsPrivateFiles } from '../fs/private-files.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';
+import { enqueueVaultQuota, hasPendingVaultQuota, pendingVaultQuota, } from './quota-writer.js';
 export { drainVaultQuota } from './quota-writer.js';
+/** Declines and account order of `roster`, and nothing else of it. */
+export function vaultRosterSeed(roster) {
+    return {
+        declined: roster.declined.map((entry) => ({ ...entry })),
+        order: roster.rows.flatMap((row) => memberIds(row).map((credentialId) => ({
+            credentialId,
+            ...(row.accountIdentity !== undefined && {
+                accountIdentity: row.accountIdentity,
+            }),
+        }))),
+    };
+}
+/** Where a projected row falls in the seed's order; unknown rows go last. */
+function seedIndex(seed, row) {
+    const ids = memberIds(row);
+    const byAccount = row.accountIdentity === undefined
+        ? -1
+        : seed.order.findIndex((entry) => entry.accountIdentity === row.accountIdentity);
+    const index = byAccount >= 0
+        ? byAccount
+        : seed.order.findIndex((entry) => ids.includes(entry.credentialId));
+    return index >= 0 ? index : Infinity;
+}
 export const DEFAULT_ROUTE_PREFIX = 'vault:';
 function hash(value) {
     return createHash('sha256').update(value).digest('hex');
@@ -47,8 +71,9 @@ export function projectVaultRoster(previous, inventory, options = {}) {
     const prefix = options.routePrefix ?? DEFAULT_ROUTE_PREFIX;
     const reserved = options.reservedRouteIds ?? new Set();
     const previousRows = previous?.rows ?? [];
+    const seed = previous ? undefined : options.seed;
     // Declines follow the account and outlive its records, so none is pruned.
-    const declined = [...(previous?.declined ?? [])];
+    const declined = [...(previous?.declined ?? seed?.declined ?? [])];
     const complete = inventory.skipped.length === 0;
     const listed = new Set(inventory.credentials.map((credential) => credential.credentialId));
     const rejectedIds = new Set(inventory.skipped.flatMap((record) => record.credentialId === undefined ? [] : [record.credentialId]));
@@ -146,6 +171,11 @@ export function projectVaultRoster(previous, inventory, options = {}) {
                 ...(!chosen.claimed && identity !== undefined && { unclaimed: true }),
             },
         });
+        // With no previous roster every row is new; a seed from another key
+        // sorts them by that key's order instead of by credential id.
+        const pushed = projected.at(-1);
+        if (seed && pushed)
+            pushed.previousIndex = seedIndex(seed, pushed.row);
     }
     // An account the reply does not account for keeps its last good projection:
     // a rejected record must not read as the account having been removed. A
@@ -293,6 +323,14 @@ function decodeRoster(value) {
         declined,
     };
 }
+/**
+ * `roster` as `readVaultRoster` decodes it from the file that holds it, so a
+ * committed roster and a later read of its file compare equal. Package
+ * internal: not exported from `/claustrum`.
+ */
+export function decodedVaultRoster(roster) {
+    return decodeRoster(JSON.parse(JSON.stringify(roster)));
+}
 export async function readVaultRoster(path) {
     let text;
     try {
@@ -560,6 +598,102 @@ const pendingDiscoveries = new Map();
 export function forgetPendingVaultDiscovery(path) {
     pendingDiscoveries.delete(resolve(path));
 }
+/**
+ * Whether `error` from a roster commit at `path` means another writer had the
+ * roster at that moment, not that the commit itself failed: the discovery
+ * lease was busy before any roster existed, the write lock stayed busy, or a
+ * lock this commit held was lost. On Windows the same lock steps can reject
+ * with a PrivateFileError instead (a lock file that could not be read or
+ * replaced while another process held it), so a PrivateFileError naming one
+ * of this roster's lock files counts the same on every OS.
+ */
+export function isVaultRosterLockRefusal(path, error) {
+    const target = resolve(path);
+    if (error instanceof ClaustrumConsumerError)
+        return error.kind === 'roster-busy';
+    if (error instanceof LockContentionError ||
+        error instanceof LockOwnershipError)
+        return resolve(error.details.target) === target;
+    if (error instanceof PrivateFileError) {
+        const failed = resolve(error.path);
+        return [WRITE_LOCK.name, DISCOVERY_LEASE.name].some((name) => {
+            const lock = lockPathFor(target, name);
+            // The lock file itself, its eviction marker and the temporary files
+            // its owner record is staged in all start with the lock path.
+            return failed === lock || failed.startsWith(`${lock}.`);
+        });
+    }
+    return false;
+}
+const UNLOCKED_READ_ATTEMPTS = 4;
+/**
+ * What identifies one version of the file at `path`: the roster is always
+ * replaced by a rename, so any write gives it a different inode, and an
+ * in-place rewrite a different size or modification time. Undefined when it
+ * cannot be inspected, which callers must read as 'may have changed'.
+ */
+async function fileStamp(path) {
+    try {
+        const { dev, ino, size, mtimeMs } = await stat(path);
+        return { dev, ino, size, mtimeMs };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether two `fileStamp` readings are of the same file version. */
+function sameFileStamp(left, right) {
+    return (left !== undefined &&
+        right !== undefined &&
+        left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.size === right.size &&
+        left.mtimeMs === right.mtimeMs);
+}
+/**
+ * Whether a roster list that lands unlocked would write exactly the file at
+ * `path`. `overlay` names what this process holds besides the file: `target` is
+ * the file's own roster, which the locked commit compares against, and `local`,
+ * when different, is that roster plus unwritten quota readings, which must
+ * equal the commit's result too. Both must equal `next(target)`'s bytes, which
+ * is the write the commit would make; any difference, a missing or unreadable
+ * file, or a read that a concurrent reader keeps changing all mean 'commit'.
+ */
+async function readUnlockedCommitTarget(path, overlay, next) {
+    for (let attempt = 0; attempt < UNLOCKED_READ_ATTEMPTS; attempt++) {
+        // Roster files are replaced by rename, so each attempt reads one whole
+        // file either way.
+        const before = await fileStamp(path);
+        const current = await readVaultRoster(path);
+        let target;
+        let local;
+        let changed;
+        try {
+            ;
+            ({ target, local } = overlay(current));
+            const written = JSON.stringify(next(target));
+            changed =
+                JSON.stringify(target) !== written ||
+                    (local !== undefined && JSON.stringify(local) !== written);
+        }
+        catch {
+            return 'commit';
+        }
+        // No lock was taken, so another writer may have replaced the file while
+        // it was being projected. The answer must describe the file as it is now,
+        // otherwise a later list of the same roster would find it changed again.
+        if (!sameFileStamp(before, await fileStamp(path)))
+            continue;
+        if (changed)
+            return 'commit';
+        // Quota readings this process enqueued while the file was being projected
+        // are not part of `current`, and a list that returns unchanged while they
+        // wait would be the only chance to serve them as this list's roster. They
+        // keep their own commit either way, so this path takes the locked one.
+        return hasPendingVaultQuota(path) ? 'commit' : 'unchanged';
+    }
+    return 'commit';
+}
 /**
  * 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
@@ -567,7 +701,8 @@ export function forgetPendingVaultDiscovery(path) {
  * 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.
+ * unless a peer has superseded its base view in the meantime. A list that
+ * would write the file the roster already holds takes no write lock at all.
  */
 export async function refreshVaultRoster(options) {
     options.signal?.throwIfAborted();
@@ -589,10 +724,11 @@ export async function refreshVaultRoster(options) {
         return persisted;
     }
     const key = resolve(options.path);
+    const listedOver = options.listedOver;
     let discovered;
     try {
         const previous = await readVaultRoster(options.path);
-        const pending = pendingDiscoveries.get(key);
+        const pending = listedOver ? undefined : 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 =
@@ -606,20 +742,58 @@ export async function refreshVaultRoster(options) {
                 };
         pendingDiscoveries.delete(key);
         const { inventory } = discovered;
-        options.onInventory?.(inventory);
+        // Called, not awaited: a caller noting the list here may wait for this
+        // roster's write lock, and this refresh decides below whether it needs it.
+        void options.onInventory?.(inventory);
         options.signal?.throwIfAborted();
+        const projection = typeof options.projection === 'function'
+            ? options.projection()
+            : options.projection;
+        const next = (current) => projectVaultRoster(current, inventory, projection);
+        const isActive = async () => {
+            options.signal?.throwIfAborted();
+            await lease.assertOwned();
+            return active();
+        };
+        // The write lock costs a lock file, an eviction marker and staging files in
+        // the roster's directory on every poll, so it is skipped when the list
+        // would write the file that is already there. The read deciding that takes
+        // no lock: a writer that commits between the read and this decision only
+        // makes our comparison stale, and a stale comparison never writes (the
+        // commit below judges the file again under the lock). Only equality with
+        // every byte the commit would write skips; every other answer commits.
+        const decision = await readUnlockedCommitTarget(options.path, (current) => {
+            // A hub member listed over a base view of its file: the file's own view
+            // is what the commit compares, so the overlay is the plain file. The
+            // locked commit below still applies the base-view rule.
+            if (listedOver)
+                return { target: current };
+            // This process's unwritten quota readings are part of the roster it
+            // serves, so a list that matches everything but them still commits.
+            const local = pendingVaultQuota(options.path, current);
+            return { target: current, ...(local !== current && { local }) };
+        }, next);
+        if (decision === 'unchanged') {
+            if (!(await isActive()))
+                return undefined;
+            // Returned as a later read of the file: that is what today's locked
+            // unchanged commit returns, and memory keeps only what was committed.
+            return await readVaultRoster(options.path);
+        }
         return await mutateVaultRoster(options.path, async (current) => {
             if (!(await active()))
                 return { result: undefined };
             options.signal?.throwIfAborted();
             await lease.assertOwned();
-            const projection = typeof options.projection === 'function'
-                ? options.projection()
-                : options.projection;
-            const next = projectVaultRoster(current, inventory, projection);
-            const changed = JSON.stringify(current) !== JSON.stringify(next);
-            return { ...(changed && { next }), result: next };
+            if (listedOver &&
+                current?.view !== listedOver.view &&
+                current?.view !== inventory.view)
+                return { result: current };
+            const projected = next(current);
+            const changed = JSON.stringify(current) !== JSON.stringify(projected);
+            return { ...(changed && { next: projected }), result: projected };
         }, {
+            signal: options.signal,
             beforePublish: async () => {
                 options.signal?.throwIfAborted();
                 await lease.assertOwned();
@@ -629,6 +803,7 @@ export async function refreshVaultRoster(options) {
     catch (error) {
         if (error instanceof LockContentionError &&
             discovered &&
+            !listedOver &&
             !options.signal?.aborted &&
             (await active()))
             pendingDiscoveries.set(key, discovered);

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

@@ -0,0 +1,42 @@
+/** Retired generations report separately until their owner closes and shares one warning. */
+export function shutdownWarning(logger, shutdown) {
+    let warned = false;
+    return (pendingOperations) => {
+        if (warned)
+            return;
+        if (!shutdown || shutdown.aborted)
+            warned = true;
+        logger.warn('claustrum shutdown drain timed out', { pendingOperations });
+    };
+}
+/**
+ * Give cancelled background work two seconds to release its handles without letting
+ * an unresponsive connector or disk hold the host's shutdown indefinitely.
+ */
+export async function drainShutdown(pending, onTimeout) {
+    if (!pending.size)
+        return;
+    let timer;
+    let expired = false;
+    const drained = (async () => {
+        while (!expired && pending.size)
+            await Promise.allSettled([...pending]);
+    })();
+    try {
+        await Promise.race([
+            drained,
+            new Promise((resolve) => {
+                timer = setTimeout(() => {
+                    expired = true;
+                    resolve();
+                }, 2_000);
+            }),
+        ]);
+        if (expired && pending.size)
+            onTimeout(pending.size);
+    }
+    finally {
+        expired = true;
+        clearTimeout(timer);
+    }
+}