@cortexkit/anthropic-auth-core 2.2.7 → 2.3.0

package/dist/internal-types/claustrum/consumer.d.ts

@@ -3,8 +3,9 @@ import type { QuotaObservation } from '../quota/index.js';
 import type { RoutingRow } from '../routing/index.js';
 import { type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, type IdentityParser, type KeptReceiptState, type VaultGrantReach } from './custody.js';
 import { type ClaustrumLogger } from './errors.js';
+import type { CustodyLease } from './hub.js';
 import { type InsulaQuotaOptions, type InsulaQuotaResult } from './insula.js';
-import { type AccountMapper, type QuotaReceipt, type ReorderVaultRosterResult, type VaultRosterFile } from './roster.js';
+import { type AccountMapper, type ProjectionOptions, type QuotaReceipt, type ReorderVaultRosterResult, type VaultRosterFile } from './roster.js';
 import { type WatchMode } from './watch.js';
 export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
     /**
@@ -17,6 +18,14 @@ export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
     tokenPath: string;
     family: ClaustrumFamily;
     connect: () => Promise<ClaustrumScopedClient>;
+    /**
+     * How long one `connect()` attempt may take before this consumer treats the
+     * vault as unreachable (default 10 s). A connect that never settles would
+     * otherwise leave every later `refresh()` waiting on the same promise. After
+     * the limit the waiters get an unreachable error, the next `refresh()`
+     * connects again, and a client that arrives late is closed.
+     */
+    connectTimeoutMs?: number;
     /**
      * Whether the plugin currently takes its accounts from the vault (custody
      * mode) rather than from local logins. Checked before every discovery,
@@ -65,6 +74,72 @@ export interface ClaustrumWatchState {
     readonly vault: WatchMode;
     readonly insula?: WatchMode;
 }
+/**
+ * What a hub member asks of the `ClaustrumDiscoveryHub` that built it.
+ * Package-internal: the hub implements it, and `/claustrum` exports neither
+ * it nor `createHubMember`.
+ */
+export interface HubMemberPort {
+    readonly provider: string;
+    /** The member's `start()`: make sure the hub's own driver runs. */
+    start(): void;
+    /**
+     * One hub refresh, coalesced across members (one list, one fan-out).
+     * Undefined while vault mode is off, or when the connection it ran on was
+     * ended before its fan-out finished. `errors` holds each member's own
+     * commit error; a failed list rejects instead.
+     */
+    refresh(): Promise<HubRefreshOutcome | undefined>;
+    /**
+     * The hub's authority read. The hub, not the member, decides what a false
+     * read means: it runs its inactive transition on the first one.
+     */
+    readAuthority(): Promise<boolean>;
+    acquire(signal?: AbortSignal): Promise<CustodyLease>;
+    /** False once a lease was released or its connection ended. */
+    leaseLive(lease: CustodyLease): boolean;
+    /** The hub's grant reach, only while `view` is the view it was read with. */
+    grantReach(view: string | undefined): VaultGrantReach | undefined;
+    watchMode(): WatchMode;
+    keptReceiptState(): KeptReceiptState;
+    /** Apply the union of every member's roster in memory to kept receipts. */
+    retainUnion(): void;
+    forget(credentialId: string): void;
+    /** The member closed: the hub stops committing and pushing to it. */
+    detach(): void;
+}
+export interface HubRefreshOutcome {
+    readonly errors: ReadonlyMap<string, unknown>;
+}
+/** What the hub may do to one member's memory. Package-internal. */
+export interface HubMemberHooks {
+    /**
+     * Set the roster in memory as a consumer's own refresh does (pending quota
+     * readings included) and notify `onRoster` when its view changed.
+     */
+    install(roster: VaultRosterFile): void;
+    /** Vault mode went off: forget the roster. */
+    reset(): void;
+    roster(): VaultRosterFile | undefined;
+    projection(): ProjectionOptions;
+    onError(error: unknown): void;
+}
+/**
+ * How long one connect attempt may take by default. It bounds a connect that
+ * never settles; the client's own handshake limit is not guaranteed to cover
+ * every stall, and callers waiting on discovery need an answer either way.
+ */
+export declare const DEFAULT_CONNECT_TIMEOUT_MS = 10000;
+/**
+ * Build the consumer for one hub member. `options` holds only what the member
+ * uses: the hub's roster path for this member and the member's own fields.
+ * Hub-mode paths never read `tokenPath`, `family` or `connect`, which the hub
+ * owns. Package-internal: only `ClaustrumDiscoveryHub.member` calls it.
+ */
+export declare function createHubMember<Q>(port: HubMemberPort, options: ClaustrumConsumerOptions<Q>): {
+    consumer: ClaustrumConsumer<Q>;
+    hooks: HubMemberHooks;
+};
 export interface SendOptions {
     /**
      * What kind of request this is (for example `model`, `quota`, `profile`),
@@ -179,6 +254,6 @@ export declare class ClaustrumConsumer<Q = QuotaObservation> {
      */
     recordAccountQuota(routeId: string, accountIdentity: string, observation: QuotaObservation): Promise<boolean>;
     close(): void;
-    /** Close immediately; the last consumer also waits for the writer's bounded drain. */
+    /** Close immediately; background work gets 2 s and the quota writer its own 1 s. */
     dispose(): Promise<void>;
 }

package/dist/internal-types/claustrum/custody.d.ts

@@ -22,10 +22,35 @@ export interface ClaustrumFamily {
     category: string;
     apiKeys?: boolean;
 }
+/** Non-secret classification facts, including rows decoded by older clients. */
+export interface VaultRowFacts {
+    readonly credentialId: string;
+    readonly credentialType: string;
+    readonly authMethod?: string;
+    readonly refreshAdapter?: string;
+    readonly providerIds?: readonly string[];
+    readonly categories: readonly string[];
+}
+/** A policy that partitions one category without requiring one OAuth adapter. */
+export interface ClassifyingClaustrumFamily<Code extends string> {
+    category: string;
+    refusalCodes: readonly Code[];
+    classify(row: VaultRowFacts): {
+        kind: 'not-mine';
+    } | {
+        kind: 'mine';
+        member: string;
+    } | {
+        kind: 'refused';
+        code: Code;
+    };
+}
+export type ClaustrumFamilyInput = ClaustrumFamily | ClassifyingClaustrumFamily<string>;
 /** One vault credential this consumer may serve. Never carries bearer material. */
 export interface VaultCredential {
     readonly credentialId: string;
     readonly credentialType: VaultCredentialType;
+    readonly member?: string;
     /**
      * The provider account the credential logs into, when the vault's adapter
      * claims one. Absent means the adapter makes no claim, not a mismatch.
@@ -47,6 +72,7 @@ export type SkippedVaultReason = 'empty credential id' | 'duplicate credential i
  */
 export interface SkippedVaultRecord {
     readonly credentialId?: string;
+    readonly member?: string;
     readonly reason: SkippedVaultReason;
 }
 /**
@@ -82,6 +108,13 @@ export interface VaultInventory {
     readonly view: string;
     readonly credentials: readonly VaultCredential[];
     readonly skipped: readonly SkippedVaultRecord[];
+    /** Classifying families only: fixed refusal codes, never classifier errors. */
+    readonly refused?: readonly {
+        credentialId?: string;
+        code: string;
+    }[];
+    /** Classifying families only: rows outside this family's responsibility. */
+    readonly notMine?: number;
     /**
      * The consumer's grants, as the vault's list reply named them. Undefined means unknown
      * (the vault or client predates the fields), never zero grants.
@@ -221,7 +254,7 @@ export declare class ClaustrumScopedCustody {
     #private;
     constructor(options: {
         client: ClaustrumScopedClient;
-        family: ClaustrumFamily;
+        family: ClaustrumFamilyInput;
         tokenPath?: string;
         readToken?: () => Promise<EnrollmentTokenFile>;
         parseIdentity?: IdentityParser;
@@ -296,4 +329,6 @@ export declare class ClaustrumScopedCustody {
      */
     watchRoster(options: ClaustrumRosterWatchOptions): ClaustrumRosterWatch;
     close(): void;
+    /** Stop immediately; allow token reads 2 s and share an owner's timeout warning. */
+    dispose(onTimeout?: (pendingOperations: number) => void): Promise<void>;
 }

package/dist/internal-types/claustrum/hub.d.ts

@@ -0,0 +1,195 @@
+import type { QuotaObservation } from '../quota/index.js';
+import { type ClaustrumConsumer } from './consumer.js';
+import { type ClassifyingClaustrumFamily, type ClaustrumScopedClient, ClaustrumScopedCustody, type IdentityParser, type KeptReceiptState, type VaultGrantReach } from './custody.js';
+import { type ClaustrumLogger } from './errors.js';
+import { type AccountMapper, type VaultRosterFile } from './roster.js';
+import { type WatchMode } from './watch.js';
+export interface ClaustrumDiscoveryHubOptions {
+    /**
+     * The plugin's owner-only state directory. Member rosters live under
+     * `<stateDir>/rosters/<hostGeneration>/<fingerprint>/<provider>.json`.
+     */
+    stateDir: string;
+    /**
+     * Which host generation this process runs (for example `opencode1`,
+     * `opencode2` or `pi`). Hosts that classify rows differently keep separate
+     * roster directories.
+     */
+    hostGeneration: string;
+    /**
+     * Everything the plugin's classifier decides with, as plain JSON: the
+     * exact object it hands the classifier (its version, the supported-table
+     * entries, the reserved provider set and every host fact it reads). The
+     * hub hashes it, with the member set, `routePrefix` and `mapAccount`, into
+     * the roster key, so processes whose classifiers or projections could
+     * disagree never share a roster file. Configuration that `mapAccount`
+     * reads, beyond its own source text, belongs here too.
+     */
+    classifierInput: unknown;
+    /**
+     * Every provider the plugin serves on this host, fixed for the hub's life.
+     * Each is the `member` a classified row names and a roster file name, so
+     * it is lowercase ASCII: letters, digits, `.`, `_` and `-`.
+     */
+    members: readonly string[];
+    /** Prefix of every member's vault route ids; part of the roster key. */
+    routePrefix?: string;
+    /**
+     * How every member presents a vault credential (the credential names its
+     * member). Part of the roster key by its source text.
+     */
+    mapAccount?: AccountMapper;
+    /** This host's enrollment token, written by setup. */
+    tokenPath: string;
+    /**
+     * The plugin's classifying family. A legacy `ClaustrumFamily` names no
+     * member for any row and is refused.
+     */
+    family: ClassifyingClaustrumFamily<string>;
+    connect: () => Promise<ClaustrumScopedClient>;
+    /**
+     * How long one `connect()` attempt may take before the hub treats the vault
+     * as unreachable (default 10 s, as `ClaustrumConsumerOptions`). The hub's
+     * connect is shared by every member waiting for a lease, so an attempt that
+     * never settles would hold every one of them; after the limit they get an
+     * unreachable error and the next acquire connects again.
+     */
+    connectTimeoutMs?: number;
+    /**
+     * Whether the plugin takes its accounts from the vault. Read from local
+     * state only, never from the vault: on every hub tick, and when a member
+     * refreshes or authorizes. The first false read revokes every lease,
+     * closes the connection and clears every member.
+     */
+    isCustodyActive?: () => boolean | Promise<boolean>;
+    parseIdentity?: IdentityParser;
+    /** As `ClaustrumConsumerOptions.requireAssertion`, for every member. */
+    requireAssertion?: boolean;
+    /**
+     * How often the hub ticks (default 5 s). A tick reads authority, installs
+     * member roster files another writer changed under the same view, and
+     * lists when a list is due: on every tick while no vault watch is open,
+     * when a pending member's retry is due (a member the last list did not
+     * commit, retried with a backoff), otherwise every five minutes as a
+     * safety net.
+     */
+    pollIntervalMs?: number;
+    setTimeoutImpl?: typeof setTimeout;
+    clearTimeoutImpl?: typeof clearTimeout;
+    now?: () => number;
+    logger?: ClaustrumLogger;
+    /**
+     * Errors of the hub's own tick, list and watch. A failed list and a vault
+     * refusal of the watch also reach every member's `onError`.
+     */
+    onError?: (error: unknown) => void;
+}
+/**
+ * What one hub member takes: only what is per provider. The hub owns the
+ * roster path, the enrollment token, the family, the connection, the
+ * authority check, the poll timer and the projection inputs that are part of
+ * the roster key (`routePrefix`, `mapAccount`), so none of them can be given
+ * here. The type parameter matches the consumer `member` returns; members
+ * have no insula source.
+ */
+export interface ClaustrumHubMemberOptions<_Q = QuotaObservation> {
+    /**
+     * Ids of the plugin's local pool rows; no vault route id may equal one.
+     * Read on every projection and install, so it may change at any time.
+     */
+    reservedRouteIds?: () => Iterable<string>;
+    /** As `ClaustrumConsumerOptions.onRoster`: once per change of view. */
+    onRoster?: (roster: VaultRosterFile) => void;
+    /** This member's own failures, such as a roster commit that failed. */
+    onError?: (error: unknown) => void;
+    logger?: ClaustrumLogger;
+}
+/** What a lease may do with the shared custody. */
+export type ClaustrumLeasedCustody = Pick<ClaustrumScopedCustody, 'authorize' | 'reportFailure' | 'forget' | 'keptReceiptState'>;
+/**
+ * One acquisition of the hub's shared custody. `custody` throws `closed`
+ * after `release()`, and once the connection it belongs to ended for any
+ * reason, vault mode going off included. `release()` is idempotent.
+ */
+export interface CustodyLease {
+    readonly custody: ClaustrumLeasedCustody;
+    /** The connection this lease belongs to; each new connection counts up. */
+    readonly generation: number;
+    release(): void;
+}
+/** The rows the hub's last complete discovery refused or left to others. */
+export interface ClaustrumHubRefusals {
+    readonly view: string;
+    readonly refused: readonly {
+        credentialId?: string;
+        code: string;
+    }[];
+    readonly notMine: number;
+}
+/**
+ * One discovery hub per host process: the only vault connection and the only
+ * `ClaustrumScopedCustody`, one vault watch and one list per refresh, fanned
+ * out to one roster per provider. Members (`member()`) are ordinary
+ * `ClaustrumConsumer`s that never connect, list or watch themselves; each
+ * holds a custody lease. The connection stays open while vault mode is on,
+ * because the hub's own discovery holds a lease of its own, and closes when
+ * the last lease of a connection is released, when vault mode goes off, or
+ * at `close()`.
+ */
+export declare class ClaustrumDiscoveryHub {
+    #private;
+    constructor(options: ClaustrumDiscoveryHubOptions);
+    /** The roster file member `provider` reads and the hub commits. */
+    rosterPath(provider: string): string;
+    /**
+     * Build the consumer for `provider`, once. It is an ordinary
+     * `ClaustrumConsumer` whose roster path is `rosterPath(provider)`; it
+     * connects, lists and watches only through this hub.
+     */
+    member<Q = QuotaObservation>(provider: string, options: ClaustrumHubMemberOptions<Q>): ClaustrumConsumer<Q>;
+    /**
+     * Take a lease on the current connection, connecting first when there is
+     * none. The acquirer's count is taken before anything is awaited, so a
+     * release elsewhere meanwhile cannot end the connection under it. An abort
+     * or a failed connect gives that count back; an acquirer whose connection
+     * ended while it waited tries once more on the current one. Rejects with
+     * `not-active` while vault mode is off.
+     */
+    acquire(signal?: AbortSignal): Promise<CustodyLease>;
+    /** The current connection and its lease count, for status and tests. */
+    leaseState(): {
+        readonly generation?: number;
+        readonly count: number;
+    };
+    /**
+     * Start the hub's tick, which runs until `close()`. While vault mode is
+     * off a tick only reads authority and makes no vault request.
+     */
+    start(): void;
+    /**
+     * List once and commit every member, as a tick does. Resolves once every
+     * member's memory holds its new roster. Rejects when the list fails; a
+     * member's own commit error goes to that member's `onError`.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Rows the last discovery every member committed refused, with their fixed
+     * codes, and how many rows it left to other plugins. Undefined while
+     * unknown: before a complete discovery, and while vault mode is off.
+     */
+    refusals(): ClaustrumHubRefusals | undefined;
+    /** The grant reach of the same discovery as `refusals()`. */
+    grantReach(): VaultGrantReach | undefined;
+    /** How the hub learns about changes; `polling` until a watch is open. */
+    watchState(): WatchMode;
+    /** The shared custody's kept receipts, host-wide. */
+    keptReceiptState(): KeptReceiptState;
+    /**
+     * Stop the tick and the watch and close the connection. Members are not
+     * closed; they fail `closed` from then on. Use `dispose()` to also allow
+     * in-flight discovery up to two seconds to release its file handles.
+     */
+    close(): void;
+    /** Close immediately, then join background work for at most two seconds. */
+    dispose(): Promise<void>;
+}

package/dist/internal-types/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/internal-types/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/internal-types/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/internal-types/fs/refresh-file-lock.d.ts

@@ -28,7 +28,7 @@ type RefreshFileLockOptions = {
     onContended?: () => void;
     /** Synchronous, never awaited; throws and returned promise/thenable rejections are isolated. */
     onRenewalTimer?: (event: 'scheduled' | 'cancelled') => void;
-    onStep?: (step: 'stale-marker-stat' | 'stale-marker-claimed' | 'stale-lock-observed' | 'lock-read-ready' | 'lock-missing' | 'stale-lock-confirmed' | 'stale-lock-removed' | 'stale-lock-recreated' | 'eviction-marker-acquired' | 'renewal-owner-confirmed' | 'renewal-marker-unavailable' | 'renewal-write-fenced' | 'renewal-write-ready' | 'renewal-write-finished' | 'relinquish-read' | 'renewal-finished' | 'release-owner-confirmed') => void | Promise<void>;
+    onStep?: (step: 'stale-marker-stat' | 'stale-marker-claimed' | 'stale-lock-observed' | 'lease-contention-read-ready' | 'lock-read-ready' | 'lock-missing' | 'stale-lock-confirmed' | 'stale-lock-removed' | 'stale-lock-recreated' | 'eviction-marker-acquired' | 'renewal-owner-confirmed' | 'renewal-marker-unavailable' | 'renewal-write-fenced' | 'renewal-write-ready' | 'renewal-write-finished' | 'relinquish-read' | 'renewal-finished' | 'release-owner-confirmed') => void | Promise<void>;
 };
 /** Filesystem leases share wall time across all callers and processes. */
 export declare function acquireRefreshFileLock(options: RefreshFileLockOptions): Promise<RefreshFileLock | null>;

package/dist/internal-types/quota/commit-interval.d.ts

@@ -0,0 +1,9 @@
+export declare const QUOTA_COMMIT_INTERVAL_MS = 30000;
+export interface QuotaCommitTimer {
+    now(): number;
+    schedule(delayMs: number, run: () => Promise<void>): {
+        cancel(): void;
+        unref?(): void;
+    };
+}
+export declare const quotaCommitTimer: QuotaCommitTimer;

package/dist/internal-types/setup/register.d.ts

@@ -3,6 +3,8 @@ export interface PlannedWrite {
     path: string;
     content: string;
     changed: boolean;
+    existingLocalEntries?: string[];
+    existingNpmEntries?: string[];
 }
 /** Edit only array entries so unrelated JSONC text, including comments, survives. */
 export declare function updatePluginConfig(text: string, key: 'plugin' | 'plugins', pkg: string, version: string): string;

package/dist/internal-types/store/attribution.d.ts

@@ -1,4 +1,6 @@
+import { type StoreContext } from './mutate.js';
 import { type StoreRuntime } from './runtime.js';
+import { type PoolRow } from './schema.js';
 /**
  * What a pull or refresh captured about its row (named by id alongside) when
  * it was issued. A result applies only while the row with that id still has
@@ -20,6 +22,9 @@ export interface Attribution {
     credentialEpoch: number;
     identity?: string;
 }
+export declare function assertQuotaEpoch(id: string, attribution: Attribution): void;
+export declare function assertQuotaRow(id: string, attribution: Attribution, row: PoolRow | undefined): asserts row is PoolRow;
+export declare function mergedQuota(ctx: StoreContext, id: string, stored: unknown, observation: unknown): unknown;
 /**
  * Merges a quota observation into a row's stored map under the store locks,
  * after attribution passes. Needs no row lock, so it is permitted from

package/dist/internal-types/store/mutate.d.ts

@@ -52,6 +52,8 @@ export type ReadResult = ({
     kind?: 'snapshot-contended';
     retryable?: true;
 };
+/** Settings need only the config classification, not a joined roster snapshot. */
+export declare function readPoolConfig(path: string): Promise<import("./schema.js").ConfigClassification>;
 /**
  * Validate config/state/config bytes without locks. Roster replacement writes
  * config before deleting old state credentials. Re-read a changed config so an

package/dist/internal-types/store/pool.d.ts

@@ -1,3 +1,4 @@
+import type { QuotaCommitTimer } from '../quota/commit-interval.js';
 import { type Attribution } from './attribution.js';
 import type { PoolOperationError } from './errors.js';
 import type { PoolLogger } from './hooks.js';
@@ -16,6 +17,23 @@ export interface OpenPoolStoreOptions {
     configPath: string;
     statePath: string;
     quota: QuotaCodec;
+    /**
+     * Opt in to detached, coalesced quota publication, with any `quota` codec.
+     * Each accepted observation is queued whole for its row and binding, and
+     * the queue is applied in arrival order through `quota.merge` under the
+     * store locks, so the codec's own merge decides which fields a newer or
+     * older reading replaces. Accepted readings appear in read/load
+     * immediately, merged the same way; the returned promise still rejects
+     * current-row refusals before queueing. Await dispose or close at shutdown
+     * to attempt a bounded drain; readings still pending at its timeout are
+     * discarded. Normal quota commits are at least 30 seconds apart; a full
+     * queue commits early so response handling never waits for that interval.
+     */
+    coalesceQuota?: boolean;
+    /** Bounded quota drain on close/dispose, in milliseconds; defaults to 1,000. */
+    quotaDrainTimeoutMs?: number;
+    /** Monotonic clock and scheduling seam for detached quota commits. */
+    quotaCommitTimer?: QuotaCommitTimer;
     /**
      * The codec of the provider state kept beside each row's credential (see
      * `ProviderStateCodec`). Without it no row shows a provider state, and
@@ -189,6 +207,10 @@ export interface PoolStore {
     }>;
     refresh(id: string, provider: ProviderRefresh, options?: RefreshOptions): Promise<RefreshOutcome>;
     recordQuota(id: string, attribution: Attribution, observation: unknown): Promise<void>;
+    /** Drain opted-in quota publication; subsequent coalesced readings refuse. Idempotent. */
+    close(): Promise<void>;
+    /** Same bounded quota drain as close(). Does not wait for provider pull hooks. */
+    dispose(): Promise<void>;
     /** Fires a pull for a row admission refused for want of a reading. */
     requestReading(id: string): void;
     /** Resolves once every pull fired so far has settled. */

package/dist/internal-types/store/runtime.d.ts

@@ -1,3 +1,4 @@
+import type { Attribution } from './attribution.js';
 import { type PoolOperation, PoolOperationError } from './errors.js';
 import { type ReadResult, type StoreContext } from './mutate.js';
 import type { PoolLockOptions, PoolLockSpec } from './refresh-lock.js';
@@ -10,6 +11,7 @@ export interface StoreRuntime {
     providerLock: PoolLockSpec;
     rowLockOptions: Partial<PoolLockOptions>;
     firePull(id: string, reason: PullReason): void;
+    publishQuota?: (id: string, attribution: Attribution, observation: unknown) => Promise<void>;
 }
 /**
  * The row lock's (name, path): keyed by the row's recorded wire identity when

package/dist/internal-types/store/settings.d.ts

@@ -50,7 +50,7 @@ export type UpdateSettingsResult = {
     /** `unchanged` when the mutator left the settings as they were; nothing was written. */
     outcome: 'updated' | 'unchanged';
 };
-/** Reads the settings without taking a lock or writing anything. */
+/** Reads only the config's settings, without taking a lock or writing anything. */
 export declare function readPoolSettings(rt: StoreRuntime): Promise<SettingsRead>;
 /**
  * One locked read-modify-write of the plugin's settings in the config file