@cortexkit/opencode-antigravity-auth 2.2.0 → 3.0.0

package/dist/types/src/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>;

package/dist/types/src/common-auth-embedded/store/pool.d.ts

@@ -0,0 +1,196 @@
+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 PublicationReceipt, type PublishOptions, type PublishPlan, type PublishResult } from './publication.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 AddOptions, type AddResult, type CredentialWriteInput, type RemoveOptions, type RemoveResult, type ReorderOptions, type ReorderResult, type RowOperationOptions, type RowToggleOptions, type RowTransitionOptions, type RowTransitionResult, type RowWriteOptions } 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. */
+    provider: string;
+    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).
+     * When true, a row whose `stamp` is not `bound` loads `unbound` and is no
+     * candidate, and every operation that would use or keep its credential or
+     * what was observed about it (`refresh`, quota pulls, `recordQuota`,
+     * `recordIdentity`, `rotate`, and an `add` of the same secret or onto the
+     * same credential-less row) refuses with `unbound-credential` before any
+     * provider call or write, checked again under the locks and at commit.
+     * Nothing makes such a row bound except `replace`, which starts a new
+     * credential epoch and drops what was observed about the old one.
+     * An interrupted add's state-only orphan is recovered only when its stamp
+     * binds the stored and incoming material, including a supplied identity and
+     * an API key's endpoint/header. Otherwise add refuses `unbound-credential`
+     * without writing; `remove(id)` explicitly discards the orphan.
+     */
+    requireCredentialStamps?: boolean;
+    /** Require an exact secret fingerprint for every roster-publication removal. */
+    requireRemovedFingerprint?: boolean;
+    /** Injected clock for leases, refresh stamps and `addedAt`. */
+    now?: () => number;
+    /**
+     * Ordered store-lock list held across every read-modify-write. Defaults to
+     * the older writers' `save` lock at the config path, then at the state path.
+     */
+    storeLocks?: readonly PoolLockSpec[];
+    /** Defaults for every lock the store takes (see `POOL_LOCK_DEFAULTS`). */
+    lockOptions?: Partial<PoolLockOptions>;
+    /** Overrides for the row locks only. */
+    rowLockOptions?: Partial<PoolLockOptions>;
+    /** The provider-wide lock; defaults to `provider-<provider>` beside the state file. */
+    providerLock?: PoolLockSpec;
+    /** Quota pull hook, fired without being awaited. */
+    pull?: PullHook;
+    /** Receives every pull failure, since no caller awaits a pull. */
+    onPullFailure?: (rowId: string, error: PoolOperationError) => void | Promise<void>;
+    logger?: PoolLogger;
+    /** Named write steps, awaited; a test seam for crash and ownership rows. */
+    onStep?: StoreContext['onStep'];
+    /** Awaitable hold points on the refresh and pull paths; a test seam. */
+    hold?: (point: HoldPoint, rowId: string) => void | Promise<void>;
+    onLockEvent?: LockEnvironment['onLockEvent'];
+    onLockStep?: LockEnvironment['onLockStep'];
+}
+export type PoolLoad = {
+    status: 'ready';
+    schemaVersion: number;
+    rows: PoolRow[];
+} | {
+    status: 'pending-migration';
+    roster: unknown[];
+} | {
+    status: 'error';
+    file: 'config' | 'state';
+    reason: string;
+    kind?: 'snapshot-contended';
+    retryable?: true;
+};
+export interface PoolStore {
+    /** Reads the pool and fires first-reading pulls; never writes a file itself. */
+    load(): Promise<PoolLoad>;
+    /** Reads the pool without firing anything. */
+    read(): Promise<PoolLoad>;
+    /**
+     * Turns a pending-migration config into an empty pool (the pool key with no
+     * row entries) in one locked config write, dropping the named top-level
+     * keys and keeping the rest. The start of a plugin's migration; a ready
+     * pool is left alone. Failures carry operation `initialize`.
+     */
+    initialize(input?: {
+        dropKeys?: readonly string[];
+    }): Promise<{
+        status: InitializeOutcome;
+    }>;
+    /**
+     * Adds a row, or completes or rotates the row already holding the id or
+     * the secret. A new row starts at credential epoch 1; since 0.8.0 one
+     * whose id the pool held before starts one past the highest epoch that id
+     * held (see `Attribution`), and an id that held `Number.MAX_SAFE_INTEGER`
+     * refuses (`id-removed`) before writing.
+     */
+    add(input: AddInput, options?: AddOptions): Promise<AddResult>;
+    publishRoster(plan: PublishPlan, options?: PublishOptions): Promise<PublishResult>;
+    publication(operationId: string): Promise<PublicationReceipt | undefined>;
+    /**
+     * 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.
+     * Optional `attribution` fences the write on the prior credential under the
+     * locks, before any write or replacement hook; see `RowWriteOptions`.
+     */
+    replace(id: string, credential: PoolCredential, input?: CredentialWriteInput, options?: RowWriteOptions): Promise<{
+        id: string;
+        credential: StoredCredential;
+        credentialEpoch: number;
+    }>;
+    /**
+     * Refreshes the secret a row holds without changing its account or
+     * endpoint. Since 0.4.1 an API key may leave out `baseURL` and `authHeader`
+     * to keep the row's, and one that gives another is refused
+     * (`endpoint-mismatch`) before writing: that is a `replace`.
+     * Takes the same optional attribution fence as `replace` (`RowWriteOptions`).
+     */
+    rotate(id: string, credential: RotateCredential, input?: CredentialWriteInput, options?: RowWriteOptions): 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). 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?: 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`, and takes the same options since 0.7.0.
+     */
+    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.
+     */
+    remove(id: string, options?: RemoveOptions): Promise<RemoveResult>;
+    /**
+     * Sets the roster order (since 0.2.4) in one config write. `ids` must name
+     * every roster id exactly once; anything else refuses with `invalid-order`
+     * and writes nothing. Takes `extraLocks`, then the store locks; no row or
+     * provider-wide lock. Roster rows and their entries are left unchanged.
+     */
+    reorder(ids: readonly string[], options?: ReorderOptions): Promise<ReorderResult>;
+    /**
+     * The plugin's settings (since 0.2.6): every top-level key of the config
+     * file except the pool-owned ones (`POOL_OWNED_KEYS`). Never writes.
+     */
+    readSettings(): Promise<SettingsRead>;
+    /**
+     * One locked write of the plugin's settings (since 0.2.6) beside the pool,
+     * in the config file. Refuses a result that sets a pool-owned key
+     * (`invalid-input`). Takes `extraLocks`, then the store locks.
+     */
+    updateSettings(mutator: SettingsMutator, options?: UpdateSettingsOptions): Promise<UpdateSettingsResult>;
+    /**
+     * Records the identity a lookup found for the row's credential. Since
+     * 0.3.1 it takes the credential epoch the lookup was issued for, and
+     * refuses a lookup that completes after the row was replaced
+     * (`attribution`) or a row recorded for another account
+     * (`identity-mismatch`).
+     */
+    recordIdentity(id: string, identity: string, attribution: Pick<Attribution, 'credentialEpoch'>, options?: RowOperationOptions): Promise<{
+        id: string;
+        disabled: string[];
+    }>;
+    refresh(id: string, provider: ProviderRefresh, options?: RefreshOptions): Promise<RefreshOutcome>;
+    recordQuota(id: string, attribution: Attribution, observation: unknown): Promise<void>;
+    /** Fires a pull for a row admission refused for want of a reading. */
+    requestReading(id: string): void;
+    /** Resolves once every pull fired so far has settled. */
+    pullsSettled(): Promise<void>;
+}
+export declare function openPoolStore(options: OpenPoolStoreOptions): PoolStore;

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

package/dist/types/src/common-auth-embedded/store/publication.d.ts

@@ -0,0 +1,47 @@
+import type { Attribution } from './attribution.js';
+import type { PoolLockSpec } from './refresh-lock.js';
+import { type FailureHook, type ProtectFn } from './rows.js';
+import { type StoreRuntime } from './runtime.js';
+export interface PublishPlan {
+    operationId: string;
+    remove: Array<{
+        id: string;
+        attribution: Attribution;
+        fingerprint?: string;
+    }>;
+    finalize: Array<{
+        id: string;
+        attribution: Attribution;
+        reservation: string;
+        enabled: boolean;
+        disabledReason?: string;
+    }>;
+    order: string[];
+}
+export interface PublicationReceipt {
+    operationId: string;
+    planDigest: string;
+    phase: 'committed' | 'cleaned';
+    removed: Array<{
+        id: string;
+        credentialEpoch: number;
+    }>;
+    finalized: Array<{
+        id: string;
+        credentialEpoch: number;
+        reservation: string;
+        enabled: boolean;
+    }>;
+}
+export interface PublishOptions {
+    protect?: ProtectFn;
+    extraLocks?: PoolLockSpec[];
+    providerLock?: PoolLockSpec;
+    onFailure?: FailureHook;
+}
+export interface PublishResult {
+    outcome: 'published' | 'cleaned' | 'already-cleaned';
+    receipt: PublicationReceipt;
+}
+export declare function publication(rt: StoreRuntime, operationId: string): Promise<PublicationReceipt | undefined>;
+export declare function publishRoster(rt: StoreRuntime, plan: PublishPlan, options?: PublishOptions): Promise<PublishResult>;

package/dist/types/src/common-auth-embedded/store/pull.d.ts

@@ -0,0 +1,36 @@
+import { PoolOperationError } from './errors.js';
+import type { PoolLogger } from './hooks.js';
+import { type PullReason, type StoreRuntime } from './runtime.js';
+import type { StoredCredential } from './schema.js';
+/** What a pull is issued with: the credential and its attribution tuple. */
+export interface PullRequest {
+    id: string;
+    credential: StoredCredential;
+    credentialEpoch: number;
+    identity?: string;
+    reason: PullReason;
+}
+export type PullHook = (request: PullRequest) => Promise<unknown>;
+/**
+ * Fires quota pulls without ever making a caller wait for one. A pull first
+ * gives a row without a per-row entry its entry at epoch 1 (its own locked
+ * config write), then captures the credential and the attribution tuple in
+ * one locked read, requests the observation, and records it only if
+ * attribution still holds. Failures go to the store's pull failure hook.
+ */
+export declare class PullScheduler {
+    private readonly rt;
+    private readonly hook;
+    private readonly onFailure;
+    /** Rows a load-time pull has fired for in this process. */
+    private readonly firedAtLoad;
+    private readonly logger;
+    private readonly inflight;
+    constructor(rt: () => StoreRuntime, hook: PullHook | undefined, onFailure: ((rowId: string, error: PoolOperationError) => void | Promise<void>) | undefined, 
+    /** Rows a load-time pull has fired for in this process. */
+    firedAtLoad: Set<string>, logger: PoolLogger | undefined);
+    fire(id: string, reason: PullReason): void;
+    /** Resolves once every pull fired so far has settled. */
+    settled(): Promise<void>;
+    private run;
+}

package/dist/types/src/common-auth-embedded/store/refresh-lock.d.ts

@@ -0,0 +1,63 @@
+import { acquireRefreshFileLock } from '../fs/refresh-file-lock.js';
+type LockStep = NonNullable<Parameters<typeof acquireRefreshFileLock>[0]['onStep']> extends (step: infer S) => unknown ? S : never;
+/** Tuning shared by every lock the store takes; each field is overridable. */
+export interface PoolLockOptions {
+    ttlMs: number;
+    timeoutMs: number;
+    retryMs: number;
+    renew: boolean;
+    renewIntervalMs?: number;
+}
+/** A lock: the (name, path) pair naming its file plus optional tuning. */
+export interface PoolLockSpec extends Partial<PoolLockOptions> {
+    name: string;
+    path: string;
+}
+/**
+ * Store lock defaults: a 15 000 ms bounded wait retried every 50 ms plus
+ * jitter, and a renewed 10 000 ms lease.
+ */
+export declare const POOL_LOCK_DEFAULTS: Readonly<PoolLockOptions>;
+export type LockEvent = {
+    type: 'acquired' | 'released' | 'contended';
+    name: string;
+    path: string;
+};
+export interface LockEnvironment {
+    now: () => number;
+    onLockEvent?: (event: LockEvent) => void;
+    onLockStep?: (lock: {
+        name: string;
+        path: string;
+    }, step: LockStep) => void | Promise<void>;
+}
+export interface HeldLock {
+    readonly name: string;
+    readonly path: string;
+    assertOwned(): Promise<void>;
+    release(): Promise<void>;
+}
+/**
+ * Takes one lock, retrying while a live holder has it until `timeoutMs` has
+ * passed on the real clock, then throws `LockContentionError`. The lease is
+ * asserted as owned once acquired, so a caller never proceeds on a lease that
+ * expired during the wait.
+ */
+export declare function acquirePoolLock(spec: PoolLockSpec, defaults: PoolLockOptions, env: LockEnvironment): Promise<HeldLock>;
+/**
+ * Locks taken in order and released in reverse. Every acquisition re-asserts
+ * the leases already held, because a wait is exactly when an earlier lease
+ * can expire unnoticed.
+ */
+export declare class LockStack {
+    private readonly defaults;
+    private readonly env;
+    readonly held: HeldLock[];
+    constructor(defaults: PoolLockOptions, env: LockEnvironment);
+    acquire(spec: PoolLockSpec): Promise<HeldLock>;
+    assertAll(): Promise<void>;
+    /** Releases every lock taken after `mark` (a length of `held`), newest first. */
+    releaseTo(mark: number): Promise<void>;
+    releaseAll(): Promise<void>;
+}
+export {};