@cortexkit/opencode-antigravity-auth 2.2.1 → 3.0.0

package/dist/types/src/common-auth-embedded/commands/seam.d.ts

@@ -0,0 +1,72 @@
+import { type RedactionOptions } from '../logger/index.js';
+import type { ActionDefinition, CommandApplyResult, CommandDialogPayload, ItemDefinition, MenuAccount, MenuConfirmation, SectionContent, SectionSlot } from './model.js';
+/** Where a dropped field is reported. Names only, never values. */
+export interface SeamLogger {
+    warn(message: string, data?: unknown): void;
+}
+/** Masks the secret-shaped parts of one string. */
+export type TextRedactor = (text: string) => string;
+/** The string redactor every value crossing the seam goes through. */
+export declare function createTextRedactor(options?: RedactionOptions): TextRedactor;
+/**
+ * A failure whose message was written for the user. An action throws it to
+ * show `message` with the stable `code`; any other thrown value is shown only
+ * as a generic message, because its text may quote a request, a response or
+ * a credential. `code` is lowercase letters, digits and dashes; anything else
+ * is reported as `action-failed`.
+ */
+export declare class CommandError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** What a failed action shows: a stable code and a message safe to display. */
+export interface ProjectedFailure {
+    code: string;
+    text: string;
+}
+/** The code and message shown for an exception the seam cannot vouch for. */
+export declare const ACTION_FAILED: ProjectedFailure;
+/** The code and display text for a thrown value; never its raw text. */
+export declare function projectFailure(error: unknown): ProjectedFailure;
+/** A built-in item may carry the account it shows; plugin items cannot. */
+export interface ResolvedItem extends ItemDefinition {
+    account?: MenuAccount;
+}
+/** A section with its bodies, as the menu holds it between builds. */
+export interface ResolvedSection {
+    id: string;
+    slot: SectionSlot;
+    title: string;
+    content: Omit<SectionContent, 'items'> & {
+        items?: ResolvedItem[];
+    };
+}
+/** The confirmation shown when an irreversible action names none. */
+export declare const DEFAULT_IRREVERSIBLE_CONFIRMATION = "This cannot be undone. Continue?";
+/** What every payload builder needs besides the payload itself. */
+export interface SeamContext {
+    logger: SeamLogger;
+    redact: TextRedactor;
+}
+/**
+ * The confirmation an action must pass before it runs, or undefined. An
+ * irreversible action always has one, even when its definition (built
+ * outside the type checker) names none.
+ */
+export declare function confirmationOf(action: ActionDefinition): MenuConfirmation | undefined;
+/** The account fields a renderer may show; see `MenuAccount`. */
+export declare function projectAccount(account: MenuAccount): MenuAccount;
+/** The payload a host's TUI receives when the slash command opens. */
+export declare function dialogPayload(command: string, title: string, sections: readonly ResolvedSection[], seam: SeamContext): CommandDialogPayload;
+/** How an apply ended, before the seam turns it into a payload. */
+export interface ApplyOutcome {
+    ok: boolean;
+    text: string;
+    /** Present on every failure. */
+    code?: string;
+    needsConfirmation?: boolean;
+}
+/** An apply's result: the message and the refreshed menu. */
+export declare function applyResult(command: string, title: string, sections: readonly ResolvedSection[], outcome: ApplyOutcome, seam: SeamContext): CommandApplyResult;

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

@@ -0,0 +1,33 @@
+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;
+    /**
+     * File the lock is named after. Required: the lock and the write it guards
+     * must target the same file, and a default resolved in here could only ever
+     * be one host's path.
+     */
+    path: string;
+    now?: () => number;
+    renew?: boolean;
+    renewIntervalMs?: number;
+    /** Notifies a live-owner refusal without awaiting; observer failures are ignored. */
+    onContended?: () => void;
+    /** Synchronous, never awaited; throws and returned promise/thenable rejections are isolated. */
+    onRenewalTimer?: (event: 'scheduled' | 'cancelled') => void;
+    onStep?: (step: 'stale-marker-stat' | 'stale-marker-claimed' | 'stale-lock-observed' | 'stale-lock-confirmed' | 'stale-lock-removed' | 'stale-lock-recreated' | '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<RefreshFileLock | null>;

package/dist/types/src/common-auth-embedded/logger/capture-sink.d.ts

@@ -0,0 +1,14 @@
+import type { Level } from './engine.js';
+export interface LogTestRecord {
+    channel: string;
+    level: Level;
+    message: string;
+    data?: unknown;
+}
+/** The engine delivers scrubbed records only; this sink never sees raw credentials. */
+export type CaptureSink = (record: LogTestRecord) => void;
+export declare function createCaptureSink(): {
+    records: LogTestRecord[];
+    sink: CaptureSink;
+    clear: () => void;
+};

package/dist/types/src/common-auth-embedded/logger/engine.d.ts

@@ -0,0 +1,100 @@
+import type { CaptureSink } from './capture-sink.js';
+import { type RedactionOptions } from './redact.js';
+export type Level = 'error' | 'warn' | 'info' | 'debug' | 'trace';
+/** A logger that writes to a file, and to a capture sink when one is given. */
+export interface InitLoggerOptions extends RedactionOptions {
+    /** Receives every emitted record, scrubbed, alongside the file. */
+    captureSink?: CaptureSink;
+    /**
+     * Path of the file lines are appended to, or a function returning it.
+     *
+     * A function is what a host passes when its destination can move while the
+     * process runs — an operator or a test changing the variable that names the
+     * log file expects the next line to land in the new file, and a value
+     * captured once at init would keep writing to the old one.
+     */
+    file: string | (() => string);
+    /** Level floor applied when no `setLogLevel` call has overridden it. */
+    level?: Level | (() => Level | undefined);
+}
+/**
+ * A logger with no file: the capture sink is its only destination. Nothing
+ * is written to disk or printed, for a host that forwards records to its own
+ * log.
+ */
+export interface SinkOnlyLoggerOptions extends RedactionOptions {
+    /** Receives every emitted record, scrubbed. */
+    captureSink: CaptureSink;
+    file?: undefined;
+    /** Level floor applied when no `setLogLevel` call has overridden it. */
+    level?: Level | (() => Level | undefined);
+}
+/**
+ * What a logger is configured with: a file (`InitLoggerOptions`, the shape
+ * every release before this one accepted, kept as its own interface so a
+ * caller deriving a type from it with `Pick` or `extends` keeps compiling) or
+ * a capture sink alone.
+ */
+export type LoggerOptions = InitLoggerOptions | SinkOnlyLoggerOptions;
+export interface ChannelLogger {
+    error(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    debug(message: string, data?: unknown): void;
+    trace(message: string, data?: unknown): void;
+}
+/**
+ * A logger with its own file, level, redaction, capture sink and buffer.
+ * Two instances in one process never touch each other's settings or lines,
+ * so two plugins that load one shared copy of this module each keep their own
+ * log by holding their own instance.
+ */
+export interface LoggerInstance {
+    /** A logger whose lines carry `channel` and go to this instance's file. */
+    createLogger(channel: string): ChannelLogger;
+    /**
+     * Point this instance at a host's file and level. Idempotent: calling it
+     * again replaces both. A runtime level installed by `setLogLevel` is left
+     * alone, because it is the operator's explicit choice and outranks the
+     * floor a host computed at start-up.
+     */
+    configure(options: LoggerOptions): void;
+    /** Operator override of the level floor; undefined removes it. */
+    setLogLevel(level: Level | undefined): void;
+    /**
+     * Write whatever is buffered. Safe to call synchronously from a
+     * process-exit handler, which is how each host drains the buffer on
+     * shutdown.
+     */
+    flushLogs(): void;
+}
+/**
+ * A logger instance of its own, configured with `options`. A plugin whose
+ * copy of this module may be shared with another plugin in the same process
+ * uses this instead of `initLogger`, so neither replaces the other's file,
+ * level, redaction or capture sink.
+ */
+export declare function createLoggerInstance(options: LoggerOptions): LoggerInstance;
+/**
+ * Point the module's default logger at a host's file and level, and return
+ * it. Idempotent: calling it again replaces both. A runtime level installed
+ * by `setLogLevel` is deliberately left alone, because it is the operator's
+ * explicit choice and outranks the floor a host computed at start-up.
+ */
+export declare function initLogger(options: LoggerOptions): LoggerInstance;
+export declare function setLogLevel(l: Level | undefined): void;
+/**
+ * Write whatever the default logger has buffered. Safe to call synchronously
+ * from a process-exit handler, which is how each host drains the buffer on
+ * shutdown.
+ */
+export declare function flushLogs(): void;
+export declare function createLogger(channel: string): ChannelLogger;
+export declare function flushForTest(): Promise<void>;
+/**
+ * Return the default logger to its uninitialised state. Only a test needs
+ * this: a single process runs every test file, so a file path left over from
+ * one test would keep a later "logger was never initialised" case writing
+ * lines.
+ */
+export declare function resetLoggerForTest(): void;

package/dist/types/src/common-auth-embedded/logger/index.d.ts

@@ -0,0 +1,6 @@
+export type { CaptureSink, LogTestRecord } from './capture-sink.js';
+export { createCaptureSink } from './capture-sink.js';
+export type { ChannelLogger, InitLoggerOptions, Level, LoggerInstance, LoggerOptions, SinkOnlyLoggerOptions, } from './engine.js';
+export { createLogger, createLoggerInstance, flushForTest, flushLogs, initLogger, resetLoggerForTest, setLogLevel, } from './engine.js';
+export type { RedactionOptions, Redactor } from './redact.js';
+export { createRedactor, redact, redactStrings } from './redact.js';

package/dist/types/src/common-auth-embedded/logger/redact.d.ts

@@ -0,0 +1,11 @@
+export interface RedactionOptions {
+    extraSecretKeys?: (normalizedKey: string) => boolean;
+    extraValuePatterns?: RegExp[];
+}
+export declare function createRedactor(options?: RedactionOptions): {
+    redact: (value: unknown) => unknown;
+    redactStrings: (value: unknown) => unknown;
+};
+export type Redactor = ReturnType<typeof createRedactor>;
+export declare const redact: (value: unknown) => unknown;
+export declare const redactStrings: (value: unknown) => unknown;

package/dist/types/src/common-auth-embedded/quota/codec.d.ts

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

package/dist/types/src/common-auth-embedded/quota/format.d.ts

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

package/dist/types/src/common-auth-embedded/quota/index.d.ts

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

package/dist/types/src/common-auth-embedded/quota/map.d.ts

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

package/dist/types/src/common-auth-embedded/quota/merge.d.ts

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

package/dist/types/src/common-auth-embedded/quota/projection.d.ts

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

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