@cortexkit/anthropic-auth-core 1.22.0 → 2.0.0

package/dist/internal-types/pi-slot/index.d.ts

@@ -0,0 +1,3 @@
+/** Move a Pi provider slot aside without changing provider or model identifiers. */
+export type { PiSlot, PiSlotErrorCode, PiSlotInspection, PiSlotOptions, } from './slot.js';
+export { openPiSlot, PiSlotError } from './slot.js';

package/dist/internal-types/pi-slot/slot.d.ts

@@ -0,0 +1,49 @@
+export type PiSlotErrorCode = 'invalid-options' | 'invalid-auth' | 'invalid-stash' | 'unsafe-path' | 'missing-stash' | 'conflict' | 'lock-timeout' | 'lock-compromised' | 'io';
+/** Errors deliberately contain neither paths nor credentials nor underlying error messages. */
+export declare class PiSlotError extends Error {
+    readonly code: PiSlotErrorCode;
+    constructor(code: PiSlotErrorCode);
+}
+export interface PiSlotOptions {
+    authPath: string;
+    provider: string;
+    /**
+     * Where the provider's original Pi login is kept while the vault serves.
+     * Put it in a private directory, and give each provider its own file: one
+     * stash holds one provider's original login, and a second provider writing
+     * to it would overwrite the first one's backup.
+     */
+    stashPath: string;
+    /**
+     * The api_key Pi stores in the slot while the vault serves. It is a fixed,
+     * non-secret string that no provider accepts. Pi runs a key starting with
+     * `!` as a shell command and expands `$NAME` from the environment, so the
+     * placeholder may contain neither.
+     */
+    placeholderKey: string;
+    lockTimeoutMs?: number;
+}
+export interface PiSlotInspection {
+    slot: 'original' | 'placeholder' | 'foreign' | 'empty';
+    stash: 'valid' | 'missing';
+}
+export interface PiSlot {
+    inspect(): Promise<PiSlotInspection>;
+    enterVault(): Promise<void>;
+    exitVault(): Promise<'restored' | 'conflict' | 'nothing-to-do'>;
+}
+/**
+ * Production entry point. Pi caches which models are usable; after a
+ * successful transition the extension calls `ctx.modelRegistry.refresh()` so
+ * Pi re-reads the slot it just changed.
+ */
+export declare function openPiSlot(options: PiSlotOptions): PiSlot;
+/**
+ * Internal test entry point: pause reads, renewals, or renames to simulate races,
+ * and observe durable writes/deletion to simulate crashes. Not a public export.
+ */
+export declare function createPiSlot(options: PiSlotOptions, onStep?: (step: 'stash-written' | 'auth-written' | 'stash-deleted') => void, hooks?: {
+    afterReadCheck?: (path: string) => Promise<void>;
+    onRenew?: (renew: () => Promise<void>) => void;
+    beforeRename?: (path: string) => Promise<void>;
+}): PiSlot;

package/dist/internal-types/quota/codec.d.ts

@@ -0,0 +1,11 @@
+export interface QuotaCodec {
+    readonly validate: (value: unknown) => boolean;
+    readonly merge: (stored: unknown, observation: unknown) => unknown;
+}
+/**
+ * The quota codec the account-pool store (the `/store` subpath) takes when it
+ * is opened: `validate` checks a stored per-row quota map and `merge` applies
+ * an observation to one, so the store persists the map without interpreting
+ * it.
+ */
+export declare const quotaCodec: QuotaCodec;

package/dist/internal-types/quota/format.d.ts

@@ -0,0 +1,46 @@
+import type { ProjectedLimit, ProjectedQuota } from './projection.js';
+/** A reading older than this is marked with its age. */
+export declare const QUOTA_STALE_AFTER_MS: number;
+/** What `formatQuota` returns when there is no reading at all. */
+export declare const NO_QUOTA_READING = "no quota reading yet";
+/**
+ * What `formatQuota` returns when the provider answered but reported no
+ * limit for any window (every window is an absence record or a tombstone).
+ */
+export declare const NO_LIMITS_REPORTED = "no limits reported";
+/**
+ * `compact` fits a footer or a sidebar row: each window's figure, the credit
+ * budget and the stale marker, without reset times. `full` adds each reset.
+ */
+export type QuotaTextForm = 'compact' | 'full';
+export interface QuotaTextOptions {
+    /** The current time in ms, for reset countdowns and the stale marker. */
+    now: number;
+    /** Defaults to `full`. */
+    form?: QuotaTextForm;
+    /** Defaults to `QUOTA_STALE_AFTER_MS`. */
+    staleAfterMs?: number;
+}
+/**
+ * The name a window is shown under. A general window (scope `all`) is named
+ * by its stored length; a model-scoped window keeps the label the plugin
+ * stored it under, which already names the model (`seven_day_opus`). A
+ * general window stored without a length (a snapshot from before lengths
+ * were recorded) falls back to its label.
+ */
+export declare function quotaWindowName(limit: Pick<ProjectedLimit, 'scope' | 'label' | 'windowMinutes'>): string;
+/**
+ * The pieces of a quota text, in order: one per reported window
+ * (`5h 58% left, resets 2h`), then the credit budget when there is one, then
+ * `checked 3h ago` when the oldest piece shown is stale. Empty when nothing
+ * was reported; `formatQuota` turns that into a sentence. A caller printing
+ * one line per window (the terminal auth menu) uses these directly.
+ */
+export declare function quotaTextParts(quota: ProjectedQuota | undefined, options: QuotaTextOptions): string[];
+/**
+ * A row's quota as one line: `5h 58% left · 7d 90% left` in the compact
+ * form, with `, resets 2h` after each window in the full form. With nothing
+ * reported it is `NO_QUOTA_READING`, or `NO_LIMITS_REPORTED` when the
+ * provider answered without a limit for any window.
+ */
+export declare function formatQuota(quota: ProjectedQuota | undefined, options: QuotaTextOptions): string;

package/dist/internal-types/quota/index.d.ts

@@ -0,0 +1,10 @@
+export type { QuotaCodec } from './codec.js';
+export { quotaCodec } from './codec.js';
+export type { QuotaTextForm, QuotaTextOptions } from './format.js';
+export { formatQuota, NO_LIMITS_REPORTED, NO_QUOTA_READING, QUOTA_STALE_AFTER_MS, quotaTextParts, quotaWindowName, } from './format.js';
+export type { CreditBudgetCleared, CreditBudgetEntry, CreditBudgetReading, QuotaAbsentEntry, QuotaEntry, QuotaMap, QuotaReadingEntry, QuotaRetiredEntry, } from './map.js';
+export { ALL_SCOPE, DEFAULT_REQUIRED_LABELS, emptyQuotaMap, isQuotaMap, } from './map.js';
+export type { ObservedBudget, ObservedPair, ObservedReading, QuotaObservation, } from './merge.js';
+export { isQuotaObservation, mergeQuotaObservation, QuotaCodecError, } from './merge.js';
+export type { ExhaustionReset, ProjectedBudget, ProjectedLimit, ProjectedQuota, } from './projection.js';
+export { budgetExhaustedResetAt, futureResetAt, projectQuota, readsExhausted, } from './projection.js';

package/dist/internal-types/quota/map.d.ts

@@ -0,0 +1,63 @@
+/** The scope of a limit that binds every request regardless of model. */
+export declare const ALL_SCOPE = "all";
+/** The window label required when an admission call supplies none. */
+export declare const DEFAULT_REQUIRED_LABELS: readonly string[];
+export interface QuotaReadingEntry {
+    scope: string;
+    label: string;
+    kind: 'reading';
+    checkedAt: number;
+    usedPercent: number;
+    /** ISO timestamp at which the window resets, as the provider reported it. */
+    resetsAt?: string;
+    /** Window length in minutes, when the provider reported one. */
+    windowMinutes?: number;
+}
+export interface QuotaRetiredEntry {
+    scope: string;
+    label: string;
+    kind: 'retired';
+    retiredAt: number;
+}
+export interface QuotaAbsentEntry {
+    scope: string;
+    label: string;
+    kind: 'absent';
+    checkedAt: number;
+}
+export type QuotaEntry = QuotaReadingEntry | QuotaRetiredEntry | QuotaAbsentEntry;
+export interface CreditBudgetReading {
+    kind: 'reading';
+    checkedAt: number;
+    /** The provider's own verdict that the budget is spent. */
+    reached: boolean;
+    remainingPercent?: number;
+    usedPercent?: number;
+    resetsAt?: string;
+    limit?: number;
+    used?: number;
+    remaining?: number;
+    unit?: string;
+}
+export interface CreditBudgetCleared {
+    kind: 'cleared';
+    checkedAt: number;
+}
+export type CreditBudgetEntry = CreditBudgetReading | CreditBudgetCleared;
+export interface QuotaMap {
+    limits: QuotaEntry[];
+    /** Absent means no observation has reported on the budget yet. */
+    budget?: CreditBudgetEntry;
+}
+export declare function emptyQuotaMap(): QuotaMap;
+/** The time an entry speaks for: its reading, retirement or absence time. */
+export declare function entryTime(entry: QuotaEntry): number;
+export declare function limitKey(scope: string, label: string): string;
+export declare function isCreditBudgetEntry(value: unknown): value is CreditBudgetEntry;
+/**
+ * True when `value` is a well-formed quota map. Unrecognised top-level keys
+ * are tolerated (and preserved by merge) so a newer writer's additions
+ * survive; a malformed entry, a duplicated (scope, label) key or a malformed
+ * budget makes the whole map invalid.
+ */
+export declare function isQuotaMap(value: unknown): value is QuotaMap;

package/dist/internal-types/quota/merge.d.ts

@@ -0,0 +1,48 @@
+import { type QuotaMap } from './map.js';
+export interface ObservedReading {
+    /** Defaults to `all`. */
+    scope?: string;
+    label: string;
+    usedPercent: number;
+    resetsAt?: string;
+    windowMinutes?: number;
+}
+export interface ObservedPair {
+    /** Defaults to `all`. */
+    scope?: string;
+    label: string;
+}
+export type ObservedBudget = {
+    kind: 'reading';
+    reached: boolean;
+    remainingPercent?: number;
+    usedPercent?: number;
+    resetsAt?: string;
+    limit?: number;
+    used?: number;
+    remaining?: number;
+    unit?: string;
+} | {
+    kind: 'cleared';
+};
+export interface QuotaObservation {
+    checkedAt: number;
+    readings?: ObservedReading[];
+    /** Pairs reported on with authority besides the ones carrying a reading. */
+    coverage?: ObservedPair[];
+    /** Absent means the observation says nothing about the budget. */
+    budget?: ObservedBudget;
+}
+/** Thrown by `mergeQuotaObservation` when either argument is malformed. */
+export declare class QuotaCodecError extends TypeError {
+    constructor(message: string);
+}
+/** True when `value` is a well-formed observation; a pair read twice is not. */
+export declare function isQuotaObservation(value: unknown): value is QuotaObservation;
+/**
+ * Applies `observation` to `stored` (undefined for a row with no map yet) and
+ * returns the new map. Pure: neither argument is modified. Throws
+ * `QuotaCodecError` when either argument is malformed, so a store refuses the
+ * write rather than persisting a map it could not read back.
+ */
+export declare function mergeQuotaObservation(stored: unknown, observation: unknown): QuotaMap;

package/dist/internal-types/quota/projection.d.ts

@@ -0,0 +1,64 @@
+import { type QuotaMap } from './map.js';
+export interface ProjectedLimit {
+    scope: string;
+    label: string;
+    kind: 'reading' | 'retired' | 'absent';
+    /** The reading, retirement or absence time. */
+    checkedAt: number;
+    /** The stored window length; undefined when the provider reported none. */
+    windowMinutes?: number;
+    /** Present on readings only. */
+    usedPercent?: number;
+    /** Present on readings only: `100 - usedPercent`. */
+    remainingPercent?: number;
+    resetsAt?: string;
+}
+export interface ProjectedBudget {
+    checkedAt: number;
+    reached: boolean;
+    remainingPercent?: number;
+    resetsAt?: string;
+}
+export interface ProjectedQuota {
+    scope: string;
+    /** One entry per label: longest known window first, unknown lengths last. */
+    limits: readonly ProjectedLimit[];
+    /**
+     * The oldest reading time among the limits (or, with no reading, the oldest
+     * evidence time), so a projection is only as fresh as its stalest limit.
+     */
+    checkedAt?: number;
+    /** Present only when the stored budget is a reading, not cleared. */
+    budget?: ProjectedBudget;
+}
+/**
+ * Resolves `map` for a request in `scope` (`all` or a model family). A family
+ * request sees only its own family's keys and the `all` keys.
+ *
+ * The label decides how a family limit relates to a general one. Under the
+ * same label, the family reading replaces the `all` reading: use this only
+ * when the provider's family figure is a more specific view of the same cap.
+ * Under different labels both limits are projected and every consumer judges
+ * both, so a family cap that applies on top of a general cap must be stored
+ * under its own label; otherwise the general cap is hidden from a family
+ * request. A family tombstone or absence record says only that no
+ * family-specific limit exists, so it does not hide an `all` entry for the
+ * same label and is used only when there is none.
+ */
+export declare function projectQuota(map: QuotaMap | undefined, scope?: string): ProjectedQuota;
+export interface ExhaustionReset {
+    resetsAt: string;
+    resetAtMs: number;
+}
+/**
+ * The credit budget's own exhaustion signal. Admission and the sticky
+ * routing decision to move a session off its pinned row both use it, so the
+ * two agree on what "spent" means. `reached` is the provider's
+ * verdict (the percentage is only a display value), and the check fails open
+ * on a missing, unparsable or already-passed reset.
+ */
+export declare function budgetExhaustedResetAt(quota: Pick<ProjectedQuota, 'budget'> | null | undefined, now: number): ExhaustionReset | undefined;
+/** True for a reading at or beyond its whole window. */
+export declare function readsExhausted(limit: ProjectedLimit): boolean;
+/** The reset time of a limit when it parses and lies after `now`. */
+export declare function futureResetAt(limit: ProjectedLimit, now: number): number | undefined;

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

@@ -0,0 +1,28 @@
+import { type StoreRuntime } from './runtime.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
+ * this credential epoch and this recorded identity; a replaced credential
+ * bumps the epoch, so work issued for the old one is discarded.
+ *
+ * The epoch names one credential lineage of the row: a credential given by
+ * `add` or `replace`, through every refresh and `rotate` of it, which keep
+ * the epoch. Since 0.8.0 that holds across removal too: a row added under an
+ * id the pool held before starts past every epoch that id held (the store
+ * records them when it drops a row, in the config file, so every process
+ * sees it), so an attribution taken for a removed row is refused once the id
+ * is added again, even with the same identity. Writers older than 0.8.0
+ * start a re-added id at epoch 1 again, and a writer that does not know the
+ * pool can remove and re-add a row without the store seeing it; work
+ * attributed across either may still apply to the new credential.
+ */
+export interface Attribution {
+    credentialEpoch: number;
+    identity?: string;
+}
+/**
+ * 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
+ * inside hooks. Clears needs-first-reading on success.
+ */
+export declare function recordQuota(rt: StoreRuntime, id: string, attribution: Attribution, observation: unknown): Promise<void>;

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

@@ -0,0 +1,55 @@
+import type { StoredCredential } from './schema.js';
+/** Every library operation that can fail, as named in the failure value. */
+export type PoolOperation = 'initialize' | 'add' | 'replace' | 'rotate' | 'disable' | 'enable' | 'remove' | 'reorder' | 'updateSettings' | 'recordIdentity' | 'updateProviderState' | 'refresh' | 'pull' | 'publishRoster';
+/**
+ * How far an operation got before it failed.
+ *
+ * `before-first-write`: nothing was written; both files are as they were.
+ * `after-first-write`: the operation's first file write landed and a later one
+ * did not; what that first write left is on disk and is never rolled back
+ * (add: a state entry no roster row names, which no reader loads; replace:
+ * the new credential stamped ahead of the config, which readers show as a
+ * torn row and the next store write on it completes; rotate: the rotated
+ * credential beside the old per-row entry). `pull`: a quota pull, or the
+ * recording of its result, failed.
+ */
+export type PoolFailurePhase = 'before-first-write' | 'after-first-write' | 'pull';
+/**
+ * Why an operation failed. `lock-contention` and `lock-ownership` are the two
+ * lock outcomes (a wait that ran out, and a lease found lost); the rest are
+ * refusals and failures of the operation itself.
+ */
+export type PoolFailureKind = 'lock-contention' | 'lock-ownership' | 'pending-migration' | 'load-error' | 'snapshot-contended' | 'publication-sync' | 'publication-incomplete' | 'unknown-row' | 'invalid-row' | 'invalid-input' | 'id-exists' | 'id-removed' | 'type-mismatch' | 'no-credential' | 'row-disabled' | 'row-protected' | 'row-staged' | 'credential-exists' | 'publication-mismatch' | 'duplicate-identity' | 'identity-mismatch' | 'identity-contradicted' | 'endpoint-mismatch' | 'row-key-changed' | 'invalid-order' | 'refresh-stamp-ahead' | 'unbound-credential' | 'attribution' | 'provider' | 'pull' | 'invalid-quota' | 'invalid-provider-state' | 'after-persist-hook' | 'unexpected';
+/**
+ * The single failure value of every store operation. `committed` is present
+ * only when the operation had already written a credential to the state file
+ * before it failed (a partial rotation or refresh): it is the credential now
+ * on disk, so a caller never has to re-read the files to learn it.
+ */
+export declare class PoolOperationError extends Error {
+    readonly operation: PoolOperation;
+    readonly rowId: string | undefined;
+    readonly phase: PoolFailurePhase;
+    readonly retryable: boolean;
+    readonly kind: PoolFailureKind;
+    readonly committed: StoredCredential | undefined;
+    constructor(details: {
+        operation: PoolOperation;
+        rowId?: string;
+        phase: PoolFailurePhase;
+        retryable: boolean;
+        kind: PoolFailureKind;
+        committed?: StoredCredential;
+        message?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a row operation or a refresh is called from inside a hook of a
+ * lock-holding operation (or from any continuation created inside one). It is
+ * thrown before any lock is taken or waited for.
+ */
+export declare class PoolReentryError extends Error {
+    readonly operation: PoolOperation;
+    constructor(operation: PoolOperation);
+}

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

@@ -0,0 +1,12 @@
+import { type PoolOperation } from './errors.js';
+/** Refuses a row operation or refresh called from inside a hook. */
+export declare function assertNotInsideHook(operation: PoolOperation): void;
+export declare function runInsideHook<T>(operation: PoolOperation, fn: () => Promise<T> | T): Promise<T>;
+export interface PoolLogger {
+    warn(message: string, data?: unknown): void;
+}
+/**
+ * Runs a failure hook. A hook that throws never replaces the failure it was
+ * handed: its exception is logged and discarded.
+ */
+export declare function callFailureHook<E, R extends string | undefined>(operation: PoolOperation, hook: ((rowId: R, error: E) => void | Promise<void>) | undefined, rowId: R, error: E, logger: PoolLogger | undefined): Promise<void>;

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

@@ -0,0 +1,39 @@
+import type { PoolRow } from './schema.js';
+/**
+ * What the identity rules edit: a transaction, or a config being completed
+ * in memory.
+ */
+export interface RowEditor {
+    rows(): PoolRow[];
+    rosterRow(id: string): Record<string, unknown> | undefined;
+    entry(id: string): Record<string, unknown> | undefined;
+    setEntry(id: string, entry: Record<string, unknown>): void;
+}
+/** Prefix of a refresh quarantine reason, followed by JSON of the expected and returned identities. */
+export declare const IDENTITY_CONTRADICTED_REASON_PREFIX = "identity-contradicted: ";
+/** The reason recorded on a row disabled because an earlier row is the same account. */
+export declare const DUPLICATE_IDENTITY_REASON = "duplicate-identity";
+/**
+ * Enabled OAuth rows holding a credential whose wire identity is not yet
+ * known. API-key rows and disabled rows never count.
+ */
+export declare function countUnknownIdentityRows(rows: readonly PoolRow[]): number;
+/**
+ * Marks a row disabled with a reason: `enabled: false` in the roster row,
+ * which older readers honour, and the reason in the per-row entry. A row
+ * without an entry gets one at epoch 1. Nothing is ever deleted.
+ */
+export declare function disableIn(tx: RowEditor, id: string, reason: string): void;
+/**
+ * Marks a row enabled: `enabled: true` in the roster row and no
+ * `disabledReason` in its entry. A row without an entry is not given one.
+ */
+export declare function enableIn(tx: RowEditor, id: string): void;
+/**
+ * Two enabled OAuth rows with one wire identity are the same account: the
+ * earlier row in roster order stays enabled and every later one is disabled
+ * with a reason. Returns the ids it disabled.
+ */
+export declare function disableIdentityDuplicates(tx: RowEditor, identity: string): string[];
+/** Records a row's wire identity in its roster row, then applies dedupe. */
+export declare function recordIdentityIn(tx: RowEditor, id: string, identity: string): string[];

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

@@ -0,0 +1,21 @@
+export type { Attribution } from './attribution.js';
+export type { PoolFailureKind, PoolFailurePhase, PoolOperation, } from './errors.js';
+export { PoolOperationError, PoolReentryError } from './errors.js';
+export type { PoolLogger } from './hooks.js';
+export { countUnknownIdentityRows, DUPLICATE_IDENTITY_REASON, } from './identity.js';
+export type { HoldPoint, InitializeOutcome, WriteStep } from './mutate.js';
+export type { OpenPoolStoreOptions, PoolLoad, PoolStore, } from './pool.js';
+export { openPoolStore } from './pool.js';
+export type { ProviderStateMutator, RowTransitionMutator, UpdateProviderStateResult, } from './provider-state.js';
+export { DECLINE_TRANSITION } from './provider-state.js';
+export type { PublicationReceipt, PublishOptions, PublishPlan, PublishResult, } from './publication.js';
+export type { PullHook, PullRequest } from './pull.js';
+export type { ProviderRefresh, ProviderRefreshResult, RefreshOptions, RefreshOutcome, } from './refresh.js';
+export type { LockEvent, PoolLockOptions, PoolLockSpec, } from './refresh-lock.js';
+export { POOL_LOCK_DEFAULTS } from './refresh-lock.js';
+export type { AddInput, AddOptions, AddResult, CredentialWriteInput, FailureHook, ProtectFn, ProtectView, RemoveOptions, RemoveResult, RemoveView, ReorderOptions, ReorderResult, RowOperationOptions, RowProjection, RowToggleOptions, RowTransitionOptions, RowTransitionResult, RowWriteOptions, } from './rows.js';
+export type { PullReason } from './runtime.js';
+export type { ApiKeyCredential, CredentialStampStatus, OAuthCredential, PoolCredential, PoolRow, ProviderStateCodec, ProviderStateDrop, ProviderStateReplacement, QuotaCodec, RotateCredential, StoredCredential, } from './schema.js';
+export { fingerprintOf, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, PROVIDER_STATE_KEY, REFRESH_STAMP_TOLERANCE_MS, rowLockKey, } from './schema.js';
+export type { PoolSettings, SettingsMutator, SettingsRead, UpdateSettingsOptions, UpdateSettingsResult, } from './settings.js';
+export { POOL_OWNED_KEYS } from './settings.js';

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

@@ -0,0 +1,189 @@
+import { type PoolFailurePhase, type PoolOperation, PoolOperationError } from './errors.js';
+import { type PoolLogger } from './hooks.js';
+import { type LockEnvironment, LockStack, type PoolLockOptions, type PoolLockSpec } from './refresh-lock.js';
+import { type PoolRow, type ProviderStateCodec, type QuotaCodec, type StoredCredential } from './schema.js';
+/** Named points on the write path, for crash and ownership injection. */
+export type WriteStep = 'before-config-write' | 'after-config-write' | 'before-state-write' | 'after-state-write';
+/** Awaitable pause points on the pull and refresh paths. */
+export type HoldPoint = 'refresh-before-provider' | 'pull-before-request';
+export interface StoreContext {
+    provider: string;
+    configPath: string;
+    statePath: string;
+    codec: QuotaCodec;
+    /** The provider-state codec; without one no row shows a provider state. */
+    providerState?: ProviderStateCodec;
+    now: () => number;
+    storeLocks: readonly PoolLockSpec[];
+    lockDefaults: PoolLockOptions;
+    lockEnv: LockEnvironment;
+    logger?: PoolLogger;
+    onStep?: (step: WriteStep, info: {
+        operation: PoolOperation;
+        rowId: string | undefined;
+    }) => void | Promise<void>;
+    hold?: (point: HoldPoint, rowId: string) => void | Promise<void>;
+    /** Ids whose per-row entry a library write dropped in this process. */
+    removedIds: Set<string>;
+    /**
+     * When true, rows whose credential stamp is not bound load `unbound` and
+     * the operations that use a credential refuse them (see
+     * `OpenPoolStoreOptions.requireCredentialStamps`).
+     */
+    requireCredentialStamps?: boolean;
+    requireRemovedFingerprint?: boolean;
+}
+export interface Snapshot {
+    configExists: boolean;
+    stateExists: boolean;
+    config: Record<string, unknown>;
+    state: Record<string, unknown>;
+    rows: PoolRow[];
+}
+export type ReadResult = ({
+    status: 'ready';
+} & Snapshot) | {
+    status: 'pending-migration';
+    config: Record<string, unknown>;
+} | {
+    status: 'error';
+    file: 'config' | 'state';
+    reason: string;
+    kind?: 'snapshot-contended';
+    retryable?: true;
+};
+/**
+ * Validate config/state/config bytes without locks. Roster replacement writes
+ * config before deleting old state credentials. Re-read a changed config so an
+ * old roster cannot be paired with state from which its accounts were removed.
+ */
+export declare function readPool(ctx: StoreContext): Promise<ReadResult>;
+/** The refusal for a pool that is not ready, as a failure value. */
+export declare function notReadyError(result: Exclude<ReadResult, {
+    status: 'ready';
+}>, operation: PoolOperation, rowId: string | undefined, phase?: PoolFailurePhase): PoolOperationError;
+/** What an operation has written so far; decides the failure phase. */
+export interface Progress {
+    writes: number;
+    /** The roster config was renamed into place, or its committed receipt was found. */
+    publicationDecided?: true;
+    /** The credential the operation's state write put on disk, once it has. */
+    committed?: StoredCredential;
+}
+/**
+ * One locked read-modify-write. The store locks are pushed onto the caller's
+ * lock stack, so the ownership assertion before each write covers the outer
+ * row, provider-wide and extra locks as well; they are released when the
+ * transaction ends, whatever happens.
+ */
+export declare class Transaction {
+    private readonly ctx;
+    readonly snapshot: Snapshot;
+    private readonly locks;
+    private readonly progress;
+    readonly info: {
+        operation: PoolOperation;
+        rowId: string | undefined;
+    };
+    config: Record<string, unknown>;
+    state: Record<string, unknown>;
+    constructor(ctx: StoreContext, snapshot: Snapshot, locks: LockStack, progress: Progress, info: {
+        operation: PoolOperation;
+        rowId: string | undefined;
+    });
+    /**
+     * The rows as every reader loads them: a row torn between the writes of a
+     * replace is shown as that replace leaves it once completed (see
+     * `PoolRow.torn`).
+     */
+    rows(): PoolRow[];
+    row(id: string): PoolRow | undefined;
+    /** Read the config marker, or an orphan's stamp; never use a caller's reservation. */
+    reservation(id: string): unknown;
+    assertNotStaged(id: string): void;
+    roster(): unknown[];
+    /** The first roster row with this id (the one the pool loads). */
+    rosterRow(id: string): Record<string, unknown> | undefined;
+    /**
+     * Drops every roster row carrying this id. The row's per-row entry goes with
+     * it on the next `commitConfig`, which drops entries for ids no longer in
+     * the roster. Returns how many roster rows were dropped.
+     */
+    dropRosterRows(id: string): number;
+    entries(): Record<string, unknown>;
+    entry(id: string): Record<string, unknown> | undefined;
+    setEntry(id: string, entry: Record<string, unknown>): void;
+    /**
+     * Writes the config of every row torn between the writes of a replace, or
+     * of a write giving it its first identity, as that write would have left it
+     * (see `completeTornRows`), in one config
+     * write ahead of the operation's own. The write is counted apart from the
+     * operation's: it is setup, like a pull giving a row its entry, so a later
+     * refusal still reports `before-first-write`.
+     */
+    completeTorn(): Promise<void>;
+    stateAccount(id: string): Record<string, unknown> | undefined;
+    /** Drops the row's credential and runtime fields from the state file's accounts. */
+    dropStateAccount(id: string): void;
+    setStateAccount(id: string, fields: Record<string, unknown>): void;
+    /**
+     * Writes the config: legacy `version: 1` and the legacy roster beside
+     * `commonAuthPool`, every other top-level key and every unrecognised pool
+     * key untouched. Entries for ids no longer in the roster are dropped here,
+     * and remembered so the id is not reused in this process. Every id the
+     * write drops (a roster row the files held when the transaction read them,
+     * or an entry left without one) has its epoch recorded in the config (see
+     * `retireEpochsIn`), which is what keeps a later `add` of the id, from any
+     * process, past every epoch an attribution could name.
+     */
+    commitConfig(options?: {
+        counted?: boolean;
+        durable?: boolean;
+        publicationDecision?: boolean;
+    }): Promise<void>;
+    /** Writes the state: every unrecognised top-level and per-row key kept. */
+    commitState(committed?: StoredCredential, options?: {
+        durable?: boolean;
+    }): Promise<void>;
+    assertAll(): Promise<void>;
+    syncState(): Promise<void>;
+    markPublicationDecision(): void;
+    syncConfig(): Promise<void>;
+    private write;
+}
+/** What `initializePool` did. */
+export type InitializeOutcome = 'initialized' | 'already-ready';
+/**
+ * Adds the pool key to a config that holds a legacy roster without one, under
+ * the store-lock list, in one config write: `commonAuthPool` with the schema
+ * version and no row entries, the legacy roster and every other top-level key
+ * kept, except the keys named in `dropKeys`. The state file is not touched.
+ * This is the only write the store makes to a pending-migration config; it is
+ * where a plugin's migration starts, and every later row goes through the
+ * ordinary operations. A config that is already a pool is left alone; a load
+ * error refuses.
+ */
+export declare function initializePool(ctx: StoreContext, dropKeys: readonly string[]): Promise<InitializeOutcome>;
+/**
+ * Runs `fn` under the store-lock list. The pool must be ready: a pending
+ * migration or a load error refuses before anything is written. Unless
+ * `completeTorn` is false, rows torn between the writes of a replace are
+ * completed first, so `fn` never sees one; the writes that only record
+ * readings or reorder the roster opt out and leave such rows as they are.
+ */
+export declare function withTransaction<T>(ctx: StoreContext, locks: LockStack, progress: Progress, info: {
+    operation: PoolOperation;
+    rowId: string | undefined;
+}, fn: (tx: Transaction) => Promise<T>, options?: {
+    completeTorn?: boolean;
+}): Promise<T>;
+/** Maps anything thrown inside an operation onto the one failure value. */
+export declare function toFailure(error: unknown, operation: PoolOperation, rowId: string | undefined, progress: Progress): PoolOperationError;
+/**
+ * The frame every lock-holding operation runs in: failures are mapped onto
+ * the failure value, handed to the failure hook while the outer locks are
+ * still held (the store locks are already released), and rethrown; every
+ * lock is released afterwards. `rowId` is undefined for an operation that
+ * names no row (`reorder`).
+ */
+export declare function runOperation<T, R extends string | undefined = string>(ctx: StoreContext, operation: PoolOperation, rowId: R, onFailure: ((rowId: R, error: PoolOperationError) => void | Promise<void>) | undefined, body: (locks: LockStack, progress: Progress) => Promise<T>): Promise<T>;