@cortexkit/common-auth 0.5.0 → 0.7.0

package/dist/fs/index.d.ts

@@ -1,6 +1,7 @@
 export type { AtomicWriteOptions } from './atomic-write.js';
 export { writeJsonAtomic } from './atomic-write.js';
 export { WRITER_LOCK_CONSTANTS } from './lock-constants.js';
+export type { LockLoss, RefreshFileLock } from './refresh-file-lock.js';
 export { acquireRefreshFileLock, isLostMarkerRaceError, } from './refresh-file-lock.js';
-export type { LockOptions } from './with-lock.js';
+export type { LockOptions, LockOwnershipDetails } from './with-lock.js';
 export { LockContentionError, LockOwnershipError, lockPathFor, withLock, } from './with-lock.js';

package/dist/fs/refresh-file-lock.d.ts

@@ -1,4 +1,18 @@
 export declare function isLostMarkerRaceError(error: unknown): boolean;
+export interface LockLoss {
+    readonly reason: 'taken-over' | 'expired' | 'unreadable' | 'renewal-failed' | 'marker-lost';
+    readonly expectedOwnerId: string;
+    readonly observedOwnerId?: string;
+    readonly observedExpiresAt?: number;
+}
+export interface RefreshFileLock {
+    readonly ownerId: string;
+    assertOwned(): Promise<void>;
+    release(): Promise<void>;
+    /** Resolves once on detected loss; remains pending after an owner's release. */
+    whenLost(): Promise<LockLoss>;
+    hasLost(): boolean;
+}
 export declare function acquireRefreshFileLock(options: {
     name: string;
     ttlMs: number;
@@ -12,7 +26,4 @@ export declare function acquireRefreshFileLock(options: {
     renew?: boolean;
     renewIntervalMs?: number;
     onStep?: (step: 'stale-marker-stat' | 'stale-marker-claimed' | 'stale-lock-confirmed' | 'eviction-marker-acquired' | 'renewal-owner-confirmed' | 'renewal-marker-unavailable' | 'renewal-write-fenced' | 'renewal-write-ready' | 'relinquish-read' | 'renewal-finished' | 'release-owner-confirmed') => void | Promise<void>;
-}): Promise<{
-    release: () => Promise<void>;
-    assertOwned: () => Promise<void>;
-} | null>;
+}): Promise<RefreshFileLock | null>;

package/dist/fs/refresh-file-lock.js

@@ -19,6 +19,30 @@ export async function acquireRefreshFileLock(options) {
     const now = options.now ?? Date.now;
     let renewTimer = null;
     let released = false;
+    let loss;
+    let resolveLoss;
+    const lostPromise = new Promise((resolve) => {
+        resolveLoss = resolve;
+    });
+    function recordLoss(reason, owner) {
+        if (loss || released)
+            return;
+        loss = Object.freeze({
+            reason,
+            expectedOwnerId: ownerId,
+            ...(typeof owner?.ownerId === 'string'
+                ? { observedOwnerId: owner.ownerId }
+                : {}),
+            ...(typeof owner?.expiresAt === 'number'
+                ? { observedExpiresAt: owner.expiresAt }
+                : {}),
+        });
+        if (renewTimer) {
+            clearRefreshLockRenewalTimeout(renewTimer);
+            renewTimer = null;
+        }
+        resolveLoss(loss);
+    }
     let renewalInFlight = null;
     // Only the owner of this exclusively-created marker may remove or renew a
     // lock. A contender recovering a stale marker can accidentally rename a newer
@@ -203,7 +227,7 @@ export async function acquireRefreshFileLock(options) {
         }
     }
     function scheduleRenewal() {
-        if (!options.renew || released)
+        if (!options.renew || released || loss)
             return;
         const intervalMs = options.renewIntervalMs ?? Math.max(1_000, Math.floor(options.ttlMs / 3));
         renewTimer = setRefreshLockRenewalTimeout(() => {
@@ -213,19 +237,25 @@ export async function acquireRefreshFileLock(options) {
                     const markerAcquired = await withEvictionMarker(async () => {
                         const owner = await readOwner();
                         const currentNow = now();
-                        if (released || owner?.ownerId !== ownerId) {
+                        if (released || loss) {
+                            shouldReschedule = false;
+                            return;
+                        }
+                        if (owner?.ownerId !== ownerId) {
+                            recordLoss('taken-over', owner);
                             shouldReschedule = false;
                             return;
                         }
                         // An expired lease is no longer ours to extend; a contender may
                         // already be eligible to acquire it.
-                        if (Number(owner?.expiresAt) <= currentNow) {
+                        if (!(Number(owner?.expiresAt) > currentNow)) {
+                            recordLoss('expired', owner);
                             shouldReschedule = false;
                             return;
                         }
                         if (options.onStep)
                             await options.onStep('renewal-owner-confirmed');
-                        if (released) {
+                        if (released || loss) {
                             shouldReschedule = false;
                             return;
                         }
@@ -233,7 +263,7 @@ export async function acquireRefreshFileLock(options) {
                             return;
                         if (options.onStep)
                             await options.onStep('renewal-write-fenced');
-                        if (released) {
+                        if (released || loss) {
                             shouldReschedule = false;
                             return;
                         }
@@ -241,10 +271,15 @@ export async function acquireRefreshFileLock(options) {
                             return;
                         if (options.onStep)
                             await options.onStep('renewal-write-ready');
+                        if (released || loss) {
+                            shouldReschedule = false;
+                            return;
+                        }
                         await writeOwner();
                         if (!(await ownsEvictionMarker())) {
                             // If marker ownership cannot be read, stop claiming the lease
                             // and remove only a record that still carries our owner id.
+                            recordLoss('marker-lost');
                             shouldReschedule = false;
                             await relinquishLockAfterMarkerLoss();
                             return;
@@ -255,7 +290,17 @@ export async function acquireRefreshFileLock(options) {
                     }
                 }
                 catch {
-                    // Transient marker and filesystem failures retry on the next interval.
+                    // Retry transient failures only while the lease can still be verified.
+                    try {
+                        const owner = await readOwner();
+                        if (owner?.ownerId !== ownerId)
+                            recordLoss('taken-over', owner);
+                        else if (!(Number(owner?.expiresAt) > now()))
+                            recordLoss('expired', owner);
+                    }
+                    catch {
+                        recordLoss('renewal-failed');
+                    }
                 }
                 finally {
                     if (options.onStep) {
@@ -266,7 +311,7 @@ export async function acquireRefreshFileLock(options) {
                             // Errors from the onStep observer must not reject the renewal.
                         }
                     }
-                    if (shouldReschedule && !released)
+                    if (shouldReschedule && !released && !loss)
                         scheduleRenewal();
                 }
             })();
@@ -341,20 +386,35 @@ export async function acquireRefreshFileLock(options) {
         return null;
     scheduleRenewal();
     return {
+        ownerId,
+        whenLost: () => lostPromise,
+        hasLost: () => loss !== undefined,
         assertOwned: async () => {
+            let observed;
             try {
                 const owner = await readOwner();
+                observed = owner;
                 if (!released &&
+                    !loss &&
                     owner?.ownerId === ownerId &&
                     Number(owner?.expiresAt) > now())
                     return;
+                recordLoss(owner?.ownerId !== ownerId ? 'taken-over' : 'expired', owner);
             }
             catch {
                 // Unreadable ownership is not evidence of a valid lease.
+                recordLoss('unreadable');
             }
             throw new LockOwnershipError({
                 target: options.path,
                 name: options.name,
+                expectedOwnerId: ownerId,
+                ...(typeof observed?.ownerId === 'string'
+                    ? { observedOwnerId: observed.ownerId }
+                    : {}),
+                ...(typeof observed?.expiresAt === 'number'
+                    ? { observedExpiresAt: observed.expiresAt }
+                    : {}),
             });
         },
         release: async () => {

package/dist/fs/with-lock.d.ts

@@ -11,15 +11,16 @@ export declare class LockContentionError extends Error {
         timeoutMs: number;
     });
 }
+export interface LockOwnershipDetails {
+    target: string;
+    name: string;
+    expectedOwnerId?: string;
+    observedOwnerId?: string;
+    observedExpiresAt?: number;
+}
 export declare class LockOwnershipError extends Error {
-    readonly details: {
-        target: string;
-        name: string;
-    };
-    constructor(details: {
-        target: string;
-        name: string;
-    });
+    readonly details: LockOwnershipDetails;
+    constructor(details: LockOwnershipDetails);
 }
 export interface LockOptions {
     name: string;

package/dist/store/errors.d.ts

@@ -1,6 +1,6 @@
 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' | 'refresh' | 'pull';
+export type PoolOperation = 'initialize' | 'add' | 'replace' | 'rotate' | 'disable' | 'enable' | 'remove' | 'reorder' | 'updateSettings' | 'recordIdentity' | 'updateProviderState' | 'refresh' | 'pull';
 /**
  * How far an operation got before it failed.
  *
@@ -19,7 +19,7 @@ export type PoolFailurePhase = 'before-first-write' | 'after-first-write' | 'pul
  * 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' | 'unknown-row' | 'invalid-row' | 'invalid-input' | 'id-exists' | 'id-removed' | 'type-mismatch' | 'no-credential' | 'row-disabled' | 'row-protected' | 'duplicate-identity' | 'identity-mismatch' | 'endpoint-mismatch' | 'row-key-changed' | 'invalid-order' | 'refresh-stamp-ahead' | 'unbound-credential' | 'attribution' | 'provider' | 'pull' | 'invalid-quota' | 'after-persist-hook' | 'unexpected';
+export type PoolFailureKind = 'lock-contention' | 'lock-ownership' | 'pending-migration' | 'load-error' | 'unknown-row' | 'invalid-row' | 'invalid-input' | 'id-exists' | 'id-removed' | 'type-mismatch' | 'no-credential' | 'row-disabled' | 'row-protected' | 'duplicate-identity' | 'identity-mismatch' | '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

package/dist/store/identity.d.ts

@@ -22,6 +22,11 @@ export declare function countUnknownIdentityRows(rows: readonly PoolRow[]): numb
  * 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

package/dist/store/identity.js

@@ -24,6 +24,22 @@ export function disableIn(tx, id, reason) {
     const entry = tx.entry(id) ?? { credentialEpoch: 1, needsFirstReading: true };
     tx.setEntry(id, { ...entry, disabledReason: reason });
 }
+/**
+ * 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 function enableIn(tx, id) {
+    const raw = tx.rosterRow(id);
+    if (!raw)
+        return;
+    raw.enabled = true;
+    const entry = tx.entry(id);
+    if (entry && 'disabledReason' in entry) {
+        const next = { ...entry };
+        delete next.disabledReason;
+        tx.setEntry(id, next);
+    }
+}
 /**
  * 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

package/dist/store/index.d.ts

@@ -6,13 +6,15 @@ export { countUnknownIdentityRows, DUPLICATE_IDENTITY_REASON, } from './identity
 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 { 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, AddResult, FailureHook, RemoveOptions, RemoveResult, RemoveView, ReorderOptions, ReorderResult, RowOperationOptions, RowToggleOptions, } from './rows.js';
+export type { AddInput, AddResult, CredentialWriteInput, FailureHook, RemoveOptions, RemoveResult, RemoveView, ReorderOptions, ReorderResult, RowOperationOptions, RowToggleOptions, RowTransitionOptions, RowTransitionResult, } from './rows.js';
 export type { PullReason } from './runtime.js';
-export type { ApiKeyCredential, CredentialStampStatus, OAuthCredential, PoolCredential, PoolRow, QuotaCodec, RotateCredential, StoredCredential, } from './schema.js';
-export { fingerprintOf, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, REFRESH_STAMP_TOLERANCE_MS, rowLockKey, } from './schema.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/store/index.js

@@ -1,6 +1,7 @@
 export { PoolOperationError, PoolReentryError } from './errors.js';
 export { countUnknownIdentityRows, DUPLICATE_IDENTITY_REASON, } from './identity.js';
 export { openPoolStore } from './pool.js';
+export { DECLINE_TRANSITION } from './provider-state.js';
 export { POOL_LOCK_DEFAULTS } from './refresh-lock.js';
-export { fingerprintOf, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, REFRESH_STAMP_TOLERANCE_MS, rowLockKey, } 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 { POOL_OWNED_KEYS } from './settings.js';

package/dist/store/mutate.d.ts

@@ -1,7 +1,7 @@
 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 QuotaCodec, type StoredCredential } from './schema.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. */
@@ -11,6 +11,8 @@ export interface StoreContext {
     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;

package/dist/store/mutate.js

@@ -41,6 +41,7 @@ export async function readPool(ctx) {
         state: state.state,
         rows: loadRows(config.config, state.state, ctx.codec, {
             requireCredentialStamps: ctx.requireCredentialStamps === true,
+            ...(ctx.providerState ? { providerState: ctx.providerState } : {}),
         }),
     };
 }
@@ -90,6 +91,9 @@ export class Transaction {
     rows() {
         return loadRows(this.config, this.state, this.ctx.codec, {
             requireCredentialStamps: this.ctx.requireCredentialStamps === true,
+            ...(this.ctx.providerState
+                ? { providerState: this.ctx.providerState }
+                : {}),
         });
     }
     row(id) {

package/dist/store/pool.d.ts

@@ -2,11 +2,12 @@ import { type Attribution } from './attribution.js';
 import type { PoolOperationError } from './errors.js';
 import type { PoolLogger } from './hooks.js';
 import { type HoldPoint, type InitializeOutcome, type StoreContext } from './mutate.js';
+import { type ProviderStateMutator, type UpdateProviderStateResult } from './provider-state.js';
 import { type PullHook } from './pull.js';
 import { type ProviderRefresh, type RefreshOptions, type RefreshOutcome } from './refresh.js';
 import { type LockEnvironment, type PoolLockOptions, type PoolLockSpec } from './refresh-lock.js';
-import { type AddInput, type AddResult, type RemoveOptions, type RemoveResult, type ReorderOptions, type ReorderResult, type RowOperationOptions, type RowToggleOptions } from './rows.js';
-import { type PoolCredential, type PoolRow, type QuotaCodec, type RotateCredential, type StoredCredential } from './schema.js';
+import { type AddInput, type AddResult, type CredentialWriteInput, type RemoveOptions, type RemoveResult, type ReorderOptions, type ReorderResult, type RowOperationOptions, type RowToggleOptions, type RowTransitionOptions, type RowTransitionResult } from './rows.js';
+import { type PoolCredential, type PoolRow, type ProviderStateCodec, type QuotaCodec, type RotateCredential, type StoredCredential } from './schema.js';
 import { type SettingsMutator, type SettingsRead, type UpdateSettingsOptions, type UpdateSettingsResult } from './settings.js';
 export interface OpenPoolStoreOptions {
     /** The provider every row of this pool belongs to; keys the provider-wide lock. */
@@ -14,6 +15,13 @@ export interface OpenPoolStoreOptions {
     configPath: string;
     statePath: string;
     quota: QuotaCodec;
+    /**
+     * The codec of the provider state kept beside each row's credential (see
+     * `ProviderStateCodec`). Without it no row shows a provider state, and
+     * every write that would set one refuses (`invalid-input`); writes that
+     * leave it alone keep the value on disk as it is, and `replace` clears it.
+     */
+    providerState?: ProviderStateCodec;
     /**
      * Refuse every credential this store did not stamp (default false, which
      * loads unstamped and mis-stamped credentials as older writers left them).
@@ -81,9 +89,12 @@ export interface PoolStore {
         status: InitializeOutcome;
     }>;
     add(input: AddInput, options?: RowOperationOptions): Promise<AddResult>;
-    replace(id: string, credential: PoolCredential, input?: {
-        identity?: string;
-    }, options?: RowOperationOptions): Promise<{
+    /**
+     * Gives a row a new credential and a new credential epoch. Since 0.6.0 the
+     * row's provider state is whatever `ProviderStateCodec.onReplace` returns;
+     * without that hook it is `input.providerState`, else cleared.
+     */
+    replace(id: string, credential: PoolCredential, input?: CredentialWriteInput, options?: RowOperationOptions): Promise<{
         id: string;
         credential: StoredCredential;
         credentialEpoch: number;
@@ -94,28 +105,32 @@ export interface PoolStore {
      * to keep the row's, and one that gives another is refused
      * (`endpoint-mismatch`) before writing: that is a `replace`.
      */
-    rotate(id: string, credential: RotateCredential, input?: {
-        identity?: string;
-    }, options?: RowOperationOptions): Promise<{
+    rotate(id: string, credential: RotateCredential, input?: CredentialWriteInput, options?: RowOperationOptions): Promise<{
         id: string;
         credential: StoredCredential;
     }>;
+    /**
+     * Changes a row's provider state without touching its credential (since
+     * 0.6.0), under the row lock, `extraLocks` and the store locks. Refuses
+     * (`attribution`) once the row has moved off the credential epoch or
+     * identity in `fence`, and (`unknown-row`) once it is removed.
+     */
+    updateProviderState(id: string, fence: Attribution, mutator: ProviderStateMutator, options?: RowToggleOptions): Promise<UpdateProviderStateResult>;
     /**
      * Sets `enabled: false` and the entry's `disabledReason`. Takes the row
      * lock, then `extraLocks`, then the store locks (the row lock and
-     * `extraLocks` since 0.2.3).
+     * `extraLocks` since 0.2.3). Since 0.7.0 it may be fenced on the
+     * credential the caller's evidence is about (`attribution`) and carry a
+     * provider-state change that lands with it (`providerState`); see
+     * `RowTransitionOptions`.
      */
-    disable(id: string, reason: string, options?: RowToggleOptions): Promise<{
-        id: string;
-    }>;
+    disable(id: string, reason: string, options?: RowTransitionOptions): Promise<RowTransitionResult>;
     /**
      * Clears `enabled: false` and `disabledReason` (since 0.2.3); refuses with
      * `duplicate-identity` when another enabled OAuth row holds the row's
-     * identity. Locks as `disable`.
+     * identity. Locks as `disable`, and takes the same options since 0.7.0.
      */
-    enable(id: string, options?: RowToggleOptions): Promise<{
-        id: string;
-    }>;
+    enable(id: string, options?: RowTransitionOptions): Promise<RowTransitionResult>;
     /**
      * Deletes the roster row, its per-row entry and its state-file credential
      * (since 0.2.3). Locks as `disable`; `protect` can refuse the id.

package/dist/store/pool.js

@@ -1,5 +1,6 @@
 import { recordQuota } from './attribution.js';
 import { initializePool, readPool, } from './mutate.js';
+import { updateProviderStateRow, } from './provider-state.js';
 import { PullScheduler } from './pull.js';
 import { refreshRow, } from './refresh.js';
 import { POOL_LOCK_DEFAULTS, } from './refresh-lock.js';
@@ -47,6 +48,7 @@ export function openPoolStore(options) {
         configPath: options.configPath,
         statePath: options.statePath,
         codec: options.quota,
+        ...(options.providerState ? { providerState: options.providerState } : {}),
         now: options.now ?? Date.now,
         storeLocks: options.storeLocks ?? [
             { name: 'save', path: options.configPath },
@@ -98,6 +100,7 @@ export function openPoolStore(options) {
         add: (input, callOptions) => addRow(rt, input, callOptions),
         replace: (id, credential, input, callOptions) => replaceRow(rt, id, credential, input, callOptions),
         rotate: (id, credential, input, callOptions) => rotateRow(rt, id, credential, input, callOptions),
+        updateProviderState: (id, fence, mutator, callOptions) => updateProviderStateRow(rt, id, fence, mutator, callOptions),
         disable: (id, reason, callOptions) => disableRow(rt, id, reason, callOptions),
         enable: (id, callOptions) => enableRow(rt, id, callOptions),
         remove: (id, callOptions) => removeRow(rt, id, callOptions),

package/dist/store/provider-state.d.ts

@@ -0,0 +1,131 @@
+import type { Attribution } from './attribution.js';
+import type { PoolOperation } from './errors.js';
+import { type Transaction } from './mutate.js';
+import type { RowToggleOptions } from './rows.js';
+import { type StoreRuntime } from './runtime.js';
+import { type PoolRow, type ProviderStateCodec } from './schema.js';
+/**
+ * What a credential write does to the provider state beside it: `keep`
+ * leaves the value on disk as it is (bound by the new stamp only if the old
+ * stamp bound it to the same row, epoch and identity), `set` stores a value
+ * the codec accepted, and `clear` deletes it.
+ */
+export type ProviderStateWrite = {
+    kind: 'keep';
+} | {
+    kind: 'set';
+    value: unknown;
+} | {
+    kind: 'clear';
+};
+/**
+ * A provider state as the store will store it: a JSON round trip of it (so
+ * its digest is the same once read back from disk), accepted by the codec.
+ * Refused before anything is written when the store has no codec, the value
+ * is not JSON, or the codec rejects it.
+ */
+export declare function acceptProviderState(codec: ProviderStateCodec | undefined, operation: PoolOperation, id: string, value: unknown, what?: string): unknown;
+/**
+ * The write for a value a credential write brings (`add` of a secret the
+ * pool holds, `rotate`, a refresh): merged with the row's value on disk by
+ * the codec's `merge` when both exist, else the incoming value as is.
+ */
+export declare function mergedProviderState(codec: ProviderStateCodec | undefined, operation: PoolOperation, id: string, onDisk: unknown, incoming: unknown): ProviderStateWrite;
+/**
+ * The provider state a replace leaves on the row, decided before anything is
+ * written: whatever the codec's `onReplace` returns (undefined clears it), or
+ * without that hook the value handed to `replace`, else nothing. The old
+ * credential's value is never kept by default: it describes the account the
+ * replaced credential belonged to.
+ */
+export declare function replacementProviderState(codec: ProviderStateCodec | undefined, row: PoolRow, credentialEpoch: number, identity: string | undefined, incoming: unknown): ProviderStateWrite;
+/**
+ * The provider-state digest the stamp of a credential write carries, and the
+ * state-file fields it changes. `set` binds the new value; `keep` carries the
+ * old stamp's digest forward only when that stamp bound it to this row as it
+ * stood before the write (same credential lineage, the epoch being written,
+ * the identity recorded before the write); `clear` binds nothing.
+ */
+export declare function providerStateCoverage(codec: ProviderStateCodec | undefined, write: ProviderStateWrite, prior: Record<string, unknown> | undefined, priorRow: PoolRow | undefined, credentialEpoch: number): string | undefined;
+/**
+ * Receives a private copy of the row's provider state (undefined when the row
+ * shows none) and the row as loaded under the locks, and returns the next
+ * provider state; returning undefined clears it, so a mutator that means to
+ * keep the value returns it. It runs under the row lock and the store locks,
+ * so it must not call back into the store (`PoolReentryError`).
+ */
+export type ProviderStateMutator = (current: unknown | undefined, row: PoolRow) => unknown | Promise<unknown>;
+export type UpdateProviderStateResult = {
+    id: string;
+    /** The provider state now on disk; absent when the row has none. */
+    providerState?: unknown;
+    /**
+     * `unchanged`: the mutator returned what the row already shows (or cleared
+     * a row that holds none); nothing was written.
+     */
+    outcome: 'updated' | 'cleared' | 'unchanged';
+};
+/**
+ * Changes a row's provider state without touching its credential, in one
+ * state-file write under the row lock, the caller's extra locks and the
+ * store locks. `fence` is what the caller read the row at: the write is
+ * refused (`attribution`, retryable) when the row has since moved to another
+ * credential epoch or recorded identity, and (`unknown-row`) once it is
+ * removed, so a writer that read the row before a replace or a removal never
+ * lands its value on the new credential or brings a removed row's state back.
+ *
+ * The value is bound by the stamp already beside the credential. When its
+ * credential-bound part is unchanged the stamp is left byte for byte as it
+ * is; otherwise only the stamp's provider-state digest changes, so the
+ * credential's stamp status never moves. With `requireCredentialStamps`, an
+ * unbound row refuses (`unbound-credential`) as every other strict path
+ * does. Without it, a row whose stamp was not written by this store with this
+ * credential at the row's epoch and identity refuses the same way: no stamp
+ * could bind the value, so no reader would ever show it. A `rotate` or
+ * `replace` stamps such a row.
+ */
+export declare function updateProviderStateRow(rt: StoreRuntime, id: string, fence: Attribution, mutator: ProviderStateMutator, options?: RowToggleOptions): Promise<UpdateProviderStateResult>;
+/**
+ * Returned by the provider-state mutator of an attributed `disable` or
+ * `enable` to decline the whole transition: nothing is written, neither the
+ * provider state nor the row's enabled flag, and the call resolves with
+ * `declined: true`. A mutator declines when the state it is shown is newer
+ * than what its caller saw, such as an eligibility recorded after the
+ * request whose refusal is being acted on. It is a value of its own because
+ * `undefined` already means "clear the provider state". `Symbol.for` keeps it
+ * equal across two copies of this module loaded in one process.
+ */
+export declare const DECLINE_TRANSITION: unique symbol;
+/**
+ * The provider-state mutator of an attributed `disable` or `enable`: as
+ * `ProviderStateMutator`, and it may also return `DECLINE_TRANSITION`.
+ */
+export type RowTransitionMutator = (current: unknown | undefined, row: PoolRow) => unknown | typeof DECLINE_TRANSITION | Promise<unknown | typeof DECLINE_TRANSITION>;
+/**
+ * What a provider-state mutator asks of a row, worked out under the locks
+ * before anything is written. `changed` carries the row's whole next
+ * state-file account entry (the value, and the stamp rebound to it when its
+ * credential-bound part moved); `value` is the next value, absent when it is
+ * cleared.
+ */
+export type ProviderStatePlan = {
+    kind: 'declined';
+} | {
+    kind: 'unchanged';
+    value?: unknown;
+} | {
+    kind: 'changed';
+    value?: unknown;
+    account: Record<string, unknown>;
+};
+/**
+ * Runs a provider-state mutator for a row loaded under every lock and
+ * already checked by the caller (present, valid, inside its attribution
+ * fence), and plans the write. Refuses (`no-credential`) a row holding no
+ * credential, and (`unbound-credential`) one whose credential carries no
+ * stamp of this store at the row's epoch and identity: no stamp could bind
+ * the value, so no reader would ever show it. `DECLINE_TRANSITION` is
+ * honoured only when `declinable` is set; elsewhere it is not JSON and is
+ * refused as such.
+ */
+export declare function planProviderStateIn(tx: Transaction, codec: ProviderStateCodec, operation: PoolOperation, row: PoolRow, mutator: ProviderStateMutator | RowTransitionMutator, declinable?: boolean): Promise<ProviderStatePlan>;