@cortexkit/antigravity-auth-core 2.2.1 → 3.0.0

package/dist/common-auth-embedded/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/common-auth-embedded/store/attribution.js

@@ -0,0 +1,60 @@
+import { PoolOperationError } from './errors.js';
+import { toFailure, withTransaction } from './mutate.js';
+import { LockStack } from './refresh-lock.js';
+import { refusal, requireBound, unknownRow, } from './runtime.js';
+import { isCredentialEpoch } from './schema.js';
+/**
+ * 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 async function recordQuota(rt, id, attribution, observation) {
+    const { ctx } = rt;
+    const locks = new LockStack(ctx.lockDefaults, ctx.lockEnv);
+    const progress = { writes: 0 };
+    try {
+        if (!isCredentialEpoch(attribution?.credentialEpoch))
+            throw refusal('pull', id, 'invalid-input', 'the credential epoch the reading was issued for must be a positive safe integer');
+        await withTransaction(ctx, locks, progress, { operation: 'pull', rowId: id }, async (tx) => {
+            tx.assertNotStaged(id);
+            const row = tx.row(id);
+            if (!row)
+                throw unknownRow('pull', id);
+            if (row.invalid)
+                throw refusal('pull', id, 'invalid-row', `row ${id} is invalid`);
+            // A reading belongs to one (epoch, identity, credential). A row
+            // holding no credential, or torn between the writes of a replace,
+            // has no such triple on disk, so no reading is recorded for it.
+            if (!row.credential)
+                throw refusal('pull', id, 'no-credential', `row ${id} holds no credential`);
+            requireBound('pull', row);
+            const entry = tx.entry(id);
+            if (row.torn ||
+                !entry ||
+                entry.credentialEpoch !== attribution.credentialEpoch ||
+                row.identity !== attribution.identity)
+                throw new PoolOperationError({
+                    operation: 'pull',
+                    rowId: id,
+                    phase: 'pull',
+                    retryable: true,
+                    kind: 'attribution',
+                    message: `quota for ${id} was issued for a credential the row no longer holds`,
+                });
+            const merged = ctx.codec.merge(entry.quota, observation);
+            if (!ctx.codec.validate(merged))
+                throw refusal('pull', id, 'invalid-quota', 'the quota codec rejected the merged map');
+            tx.setEntry(id, { ...entry, quota: merged, needsFirstReading: false });
+            await tx.commitConfig();
+        }, 
+        // Recording a reading never completes a torn row: the fence above
+        // refuses it, and the row's own next write completes it.
+        { completeTorn: false });
+    }
+    catch (error) {
+        throw toFailure(error, 'pull', id, progress);
+    }
+    finally {
+        await locks.releaseAll();
+    }
+}

package/dist/common-auth-embedded/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/common-auth-embedded/store/errors.js

@@ -0,0 +1,38 @@
+/**
+ * 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 class PoolOperationError extends Error {
+    operation;
+    rowId;
+    phase;
+    retryable;
+    kind;
+    committed;
+    constructor(details) {
+        super(details.message ??
+            `${details.operation} failed (${details.kind}, ${details.phase})`, details.cause === undefined ? undefined : { cause: details.cause });
+        this.name = 'PoolOperationError';
+        this.operation = details.operation;
+        this.rowId = details.rowId;
+        this.phase = details.phase;
+        this.retryable = details.retryable;
+        this.kind = details.kind;
+        this.committed = details.committed;
+    }
+}
+/**
+ * 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 class PoolReentryError extends Error {
+    operation;
+    constructor(operation) {
+        super(`${operation} was called from inside a store hook; hand it to the caller's continuation instead`);
+        this.name = 'PoolReentryError';
+        this.operation = operation;
+    }
+}

package/dist/common-auth-embedded/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/common-auth-embedded/store/hooks.js

@@ -0,0 +1,34 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { PoolReentryError } from './errors.js';
+/**
+ * Set while a hook of a lock-holding operation runs. Async context is
+ * inherited by every timer, promise and continuation created inside the hook,
+ * so work a hook schedules is inside the guarded region too.
+ */
+const insideHook = new AsyncLocalStorage();
+/** Refuses a row operation or refresh called from inside a hook. */
+export function assertNotInsideHook(operation) {
+    if (insideHook.getStore() !== undefined)
+        throw new PoolReentryError(operation);
+}
+export function runInsideHook(operation, fn) {
+    return insideHook.run(operation, async () => await fn());
+}
+/**
+ * Runs a failure hook. A hook that throws never replaces the failure it was
+ * handed: its exception is logged and discarded.
+ */
+export async function callFailureHook(operation, hook, rowId, error, logger) {
+    if (!hook)
+        return;
+    try {
+        await runInsideHook(operation, () => hook(rowId, error));
+    }
+    catch (hookError) {
+        logger?.warn('store failure hook threw; the original failure stands', {
+            operation,
+            rowId,
+            error: hookError instanceof Error ? hookError.message : String(hookError),
+        });
+    }
+}

package/dist/common-auth-embedded/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/common-auth-embedded/store/identity.js

@@ -0,0 +1,79 @@
+/** Prefix of a refresh quarantine reason, followed by JSON of the expected and returned identities. */
+export const IDENTITY_CONTRADICTED_REASON_PREFIX = 'identity-contradicted: ';
+/** The reason recorded on a row disabled because an earlier row is the same account. */
+export 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 function countUnknownIdentityRows(rows) {
+    return rows.filter((row) => row.invalid === undefined &&
+        !row.staged &&
+        row.type === 'oauth' &&
+        row.enabled &&
+        row.credential !== undefined &&
+        row.identity === undefined).length;
+}
+/**
+ * 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 function disableIn(tx, id, reason) {
+    const raw = tx.rosterRow(id);
+    if (!raw)
+        return;
+    raw.enabled = false;
+    const entry = tx.entry(id) ?? { credentialEpoch: 1, needsFirstReading: true };
+    // A routine disable must not erase the evidence needed to refuse enable.
+    const quarantined = typeof entry.disabledReason === 'string' &&
+        entry.disabledReason.startsWith(IDENTITY_CONTRADICTED_REASON_PREFIX);
+    tx.setEntry(id, {
+        ...entry,
+        disabledReason: quarantined ? 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
+ * with a reason. Returns the ids it disabled.
+ */
+export function disableIdentityDuplicates(tx, identity) {
+    const holders = tx
+        .rows()
+        .filter((row) => row.invalid === undefined &&
+        !row.staged &&
+        row.type === 'oauth' &&
+        row.enabled &&
+        row.identity === identity);
+    const disabled = [];
+    for (const row of holders.slice(1)) {
+        disableIn(tx, row.id, DUPLICATE_IDENTITY_REASON);
+        disabled.push(row.id);
+    }
+    return disabled;
+}
+/** Records a row's wire identity in its roster row, then applies dedupe. */
+export function recordIdentityIn(tx, id, identity) {
+    const raw = tx.rosterRow(id);
+    if (!raw)
+        return [];
+    raw.accountId = identity;
+    return disableIdentityDuplicates(tx, identity);
+}

package/dist/common-auth-embedded/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/common-auth-embedded/store/index.js

@@ -0,0 +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, PROVIDER_STATE_KEY, REFRESH_STAMP_TOLERANCE_MS, rowLockKey, } from './schema.js';
+export { POOL_OWNED_KEYS } from './settings.js';

package/dist/common-auth-embedded/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>;