@cortexkit/anthropic-auth-core 1.22.0 → 2.0.0

package/dist/native-quota-codec.d.ts

@@ -0,0 +1,32 @@
+import { type QuotaCodec, type QuotaMap } from "./internal-types/quota/index.js";
+import { type OAuthQuotaSnapshot } from './accounts.ts';
+type ScopedMetadata = {
+    id: string;
+    title: string;
+    modelId?: string;
+    modelName: string;
+    remainingPercent: number;
+};
+/** Snapshot checkedAt, remaining percentages, scoped labels/ownership, account/source provenance and monetary extra usage absent from QuotaMap. */
+export type NativeQuotaMetadata = Omit<OAuthQuotaSnapshot, 'five_hour' | 'seven_day' | 'scoped'> & {
+    version: 1;
+    remainingPercent: {
+        five_hour?: number;
+        seven_day?: number;
+    };
+    scoped?: ScopedMetadata[];
+};
+export interface NativeQuotaMap extends QuotaMap {
+    anthropic: NativeQuotaMetadata;
+}
+export declare class NativeQuotaCodecError extends Error {
+    constructor();
+}
+export declare function isNativeOAuthQuotaSnapshot(value: unknown): value is OAuthQuotaSnapshot;
+export declare function nativeQuotaModelScope(model: string): string;
+/** Conversion is arithmetic-free: preserve independent clocks and raw percentages. */
+export declare function toNativeQuotaMap(snapshot: OAuthQuotaSnapshot): NativeQuotaMap;
+/** Reject missing Anthropic metadata, extra keys, duplicate/unowned limits, absent/retired entries and inconsistent budgets. */
+export declare function fromNativeQuotaMap(value: unknown): OAuthQuotaSnapshot;
+export declare const nativeQuotaCodec: QuotaCodec;
+export {};

package/dist/native-refresh-coordinator.d.ts

@@ -0,0 +1,240 @@
+import { type PoolFailureKind, type PoolLockSpec } from "./internal-types/store/index.js";
+import { refreshClaudeOAuthToken } from './auth.ts';
+import { type resolveClaudeCodeIdentity } from './claude-code.ts';
+import { type NativeLocalCredentialValidation, type NativeLocalCredentialVersion } from './native-credential-validation.ts';
+import { type NativeLocalPoolBinding } from './pool-binding.ts';
+import type { NativePoolPaths } from './pool-paths.ts';
+import { type NativePoolStoreOptions } from './pool-store.ts';
+export declare const NATIVE_REFRESH_MAX_ATTEMPTS = 3;
+/**
+ * Jobs distinguish credential replacements. This lock must still serialize
+ * all refreshes for the same account.
+ */
+export declare function nativeAccountProviderLock(paths: NativePoolPaths, identity: string): PoolLockSpec;
+export type NativeRefreshRestriction = {
+    status: 'allowed';
+} | {
+    status: 'blocked';
+    reason: 'quota-ineligible' | 'account-disabled' | 'local-mode-unavailable';
+} | {
+    status: 'blocked';
+    reason: 'refresh-backoff' | 'invalid-grant';
+    /**
+     * A one-way refresh-credential fingerprint ties this backoff to the stored
+     * OAuth lineage. Bearer values are secret, and an access-token fingerprint
+     * would identify a rotating access token rather than the failed refresh credential.
+     */
+    credentialFingerprint: string;
+};
+/**
+ * Outcome of the account lookup for a credential. 'unsupported-credential'
+ * means the lookup refused the access value itself (it is not a Claude OAuth
+ * access token, or it is a vault custody marker): no lookup request was made
+ * and no retry can succeed until the account is signed in again.
+ */
+export type NativeIdentityBootstrap = 'resolved' | 'unavailable' | 'failed' | 'unsupported-credential';
+export type NativeRefreshHandoff = 'not-needed' | 'acquired' | 'skipped-contention' | 'skipped-loss' | 'skipped-cancelled';
+export interface NativeRefreshFailure {
+    kind: PoolFailureKind | 'caller-hook' | 'validation';
+    classification: 'transient' | 'invalid-grant' | 'permanent';
+    status?: number;
+    retryAfter?: number;
+}
+/**
+ * Access can change while the refresh token and credential epoch stay the
+ * same. These fields identify the exact stored OAuth version observed.
+ */
+export type NativeRefreshDispatchVersion = Partial<NativeLocalCredentialVersion>;
+/**
+ * Identifies a captured pool row by storage, row id, credential epoch and
+ * recorded account UUID, together with its full refresh-token fingerprint and
+ * access fingerprint, expiry and optional refresh timestamp. Neither token is
+ * included; access fingerprint and expiry may be absent before recovery.
+ */
+export interface NativeRefreshSubject {
+    readonly binding: NativeLocalPoolBinding;
+    readonly credentialFingerprint: string;
+    readonly version: NativeRefreshDispatchVersion;
+}
+export type NativeKnownCredentialSubject = NativeLocalCredentialValidation;
+/**
+ * Records the runtime binding and error-reset timestamps/generation observed
+ * for the captured pool row. Null means no binding or no reset value was
+ * present; a recorded timestamp or generation of zero must remain distinct.
+ */
+export interface NativeRefreshContext {
+    readonly subject: NativeRefreshSubject;
+    readonly runtimeBinding: NativeLocalPoolBinding | null;
+    readonly refreshErrorClearedAt: number | null;
+    readonly quotaErrorClearedAt: number | null;
+    readonly quotaErrorGeneration: number | null;
+}
+export interface NativeRefreshPolicy {
+    readonly restriction: NativeRefreshRestriction;
+    readonly context: NativeRefreshContext;
+}
+export type NativeServingAdmission = {
+    status: 'proven';
+    validation: NativeLocalCredentialValidation;
+} | {
+    status: 'unproven';
+} | {
+    status: 'blocked';
+    reason: 'quota-ineligible' | 'account-disabled' | 'local-mode-unavailable' | 'refresh-backoff' | 'invalid-grant' | 'validation-backoff';
+};
+export interface NativeCommittedMaterial {
+    readonly credentialFingerprint: string;
+    readonly version: NativeRefreshDispatchVersion;
+}
+interface ObservationBase {
+    /**
+     * Identifies the row, credential version and account before refresh. Compare
+     * this binding with current store state before writing an observation.
+     */
+    binding: NativeLocalPoolBinding;
+    attempt: number;
+    credentialFingerprint?: string;
+    credentialVersion?: NativeRefreshDispatchVersion;
+    /**
+     * Runtime binding and error-reset values read before the provider exchange or
+     * account lookup. Later serving checks must not replace these values: doing
+     * so could let an older network result overwrite an intervening error reset.
+     */
+    context?: NativeRefreshContext;
+    bootstrap: NativeIdentityBootstrap;
+    handoff: NativeRefreshHandoff;
+}
+/**
+ * Observations contain no tokens or exceptions from the provider account lookup.
+ * Only a successful account lookup reported by a persisted or
+ * validation-observed event can support new validation evidence. An adopted
+ * event merely records credentials already present on the requesting pool row;
+ * it performs no account lookup. Failed events cannot create validation evidence.
+ */
+export type NativeRefreshObservation = ObservationBase & ({
+    status: 'persisted';
+    identity?: string;
+    successorFingerprint: string;
+    successorVersion: NativeRefreshDispatchVersion;
+    committed: NativeCommittedMaterial;
+} | {
+    status: 'adopted';
+    successorFingerprint: string;
+    successorVersion: NativeRefreshDispatchVersion;
+} | {
+    status: 'validation-observed';
+    identity: string;
+    context: NativeRefreshContext;
+} | {
+    status: 'refused';
+    reason: string;
+    consumed: boolean;
+} | {
+    status: 'identity-contradicted';
+    expectedIdentity: string;
+    returnedIdentity: string;
+    successorFingerprint: string;
+    successorVersion: NativeRefreshDispatchVersion;
+    committed: NativeCommittedMaterial;
+} | {
+    status: 'failed';
+    failure: NativeRefreshFailure;
+    persisted: boolean;
+    committed?: NativeCommittedMaterial;
+});
+export interface NativeRefreshHooks {
+    /**
+     * Read native local-mode, account-disable, quota and refresh-error restrictions
+     * for the captured row. Credential-bound errors apply only to the matching
+     * full refresh-token fingerprint; absent account-validation evidence must not
+     * prevent a refresh exchange. Echo the supplied row binding, refresh-token
+     * fingerprint and access version. Include the observed runtime binding,
+     * refreshErrorClearedAt, quotaErrorClearedAt and quotaErrorGeneration, using
+     * null for absent values. Before each physical exchange the coordinator keeps
+     * a new frozen copy after lock waits, outside pool-config/pool-state locks.
+     * Do not read host credentials or mutate the store.
+     */
+    readRestrictions(subject: NativeRefreshSubject): Promise<NativeRefreshPolicy>;
+    /**
+     * Read serving restrictions and validation evidence for the supplied row
+     * binding, full refresh-token fingerprint and access version, without token
+     * input or state writes. The binding has a recorded account UUID, but that
+     * UUID alone does not establish that the presented credential was validated.
+     * Returned evidence must match the credentials on the captured requesting row.
+     */
+    readAdmission(subject: NativeKnownCredentialSubject): Promise<NativeServingAdmission>;
+    /**
+     * Acquire pool-config, pool-state, then native-runtime before saving refresh
+     * errors or validation evidence. Re-read the observation's pool row and check
+     * storage, row id, credential epoch, recorded UUID, full refresh-token
+     * fingerprint, access fingerprint, expiry and lastRefreshedAt presence/value.
+     *
+     * credentialVersion names the credential captured before network work;
+     * successorVersion names the observed replacement; committed names the
+     * replacement actually saved before a later failure. A failed observation
+     * without committed credentials must not infer a replacement from a newer row.
+     *
+     * Compare the runtime binding and error-reset timestamps/generation with
+     * context. Changed reset values mean the older observation cannot overwrite
+     * state cleared while its exchange or lookup was pending. Learned UUIDs belong
+     * only to the row receiving the replacement. Clear obsolete credential-bound
+     * errors only after confirming which replacement is stored. Failed account
+     * lookups leave stored replacements without new validation evidence; observing
+     * an already advanced row or a failed operation cannot create that evidence.
+     *
+     * Reconciliation completes before authorize returns. The shared config/state
+     * locks are already released. A successful token exchange still holds the
+     * refresh locks that prevent another exchange for this row and account.
+     * Failed operations and checks of existing access without an exchange do not
+     * guarantee those locks. Do not call store operations that acquire row locks
+     * or wait for another caller of the same account's refresh job; either can
+     * wait for the locks or reconciliation this callback must complete.
+     */
+    reconcile(observation: NativeRefreshObservation): Promise<void>;
+}
+export interface NativeRefreshCoordinatorOptions extends NativePoolStoreOptions, NativeRefreshHooks {
+    paths: NativePoolPaths;
+    refreshToken?: typeof refreshClaudeOAuthToken;
+    resolveIdentity?: typeof resolveClaudeCodeIdentity;
+}
+export interface NativeRefreshRequest {
+    intent: 'serve' | 'refresh';
+    mode: 'local' | 'claustrum';
+    binding: NativeLocalPoolBinding;
+    /** A 401's dispatched access token, used only for replacement adoption. */
+    rejectedAccessToken?: string;
+    signal?: AbortSignal;
+}
+export type NativeRefreshResult = {
+    status: 'usable';
+    source: 'current' | 'validated' | 'rotated' | 'adopted';
+    binding: NativeLocalPoolBinding;
+    /**
+     * Token from the row addressed by request.binding.rowId whose validation
+     * evidence was checked. A caller for another row with the same account UUID
+     * may share recovery work, but must not receive the job owner's row token.
+     */
+    access: string;
+    expires: number;
+    subject: NativeKnownCredentialSubject;
+    validation: NativeLocalCredentialValidation;
+} | {
+    status: 'refused';
+    reason: string;
+    persisted: boolean;
+} | {
+    status: 'identity-contradicted';
+    expectedIdentity: string;
+    returnedIdentity: string;
+    persisted: true;
+} | {
+    status: 'failed';
+    failure: NativeRefreshFailure;
+    persisted: boolean;
+    reconciliationFailed: boolean;
+};
+/** Independent local machinery: construction performs no network or migration. */
+export declare function createNativeRefreshCoordinator(options: NativeRefreshCoordinatorOptions): {
+    authorize: (request: NativeRefreshRequest) => Promise<NativeRefreshResult>;
+};
+export {};

package/dist/native-roster-seed.d.ts

@@ -0,0 +1,115 @@
+import type { NativeCustodyInventory } from './native-custody.ts';
+/**
+ * Builds and re-checks the vault roster seed written while a legacy custody
+ * install migrates to the native pool. It is pure: it never lists, reads,
+ * refreshes or writes anything. The caller lists the vault, reads the legacy
+ * config, resolves the primary route id and owns every file write.
+ *
+ * The seed keeps the route ids the legacy install already used, so later
+ * discovery (which only adds new routes under its own prefix) keeps them.
+ * It carries no token, refresh token or other credential material.
+ */
+/** Allowed build/check failure codes. Diagnostics contain no caller data. */
+export type NativeRosterSeedErrorCode = 'roster-incomplete' | 'unenrolled-local-row' | 'roster-route-conflict' | 'seed-conflict';
+export declare class NativeRosterSeedError extends Error {
+    readonly code: NativeRosterSeedErrorCode;
+    constructor(code: NativeRosterSeedErrorCode);
+}
+/** One OAuth account row from the legacy custody config. No secrets. */
+export interface NativeRosterSeedLegacyRow {
+    /** The legacy account id; it becomes the seeded route id unchanged. */
+    readonly routeId: string;
+    /** Vault credential ID associated with this enrolled legacy row, if present. */
+    readonly scopedCredentialId?: string;
+    readonly anthropicAccountUuid?: string;
+    readonly label?: string;
+    readonly addedAt?: number;
+    /** The user's enable/disable choice for this row. */
+    readonly enabled: boolean;
+}
+export interface NativeRosterSeedInput {
+    /** The vault list, already verified by the caller's discovery. */
+    readonly inventory: NativeCustodyInventory;
+    /** The primary credential and account captured from the legacy config. */
+    readonly primary: {
+        readonly credentialId: string;
+        readonly accountIdentity: string;
+    };
+    /** Route ID assigned by offline migration to the legacy primary Claude account. */
+    readonly primaryRouteId: string;
+    readonly legacyRows: readonly NativeRosterSeedLegacyRow[];
+    /** Accounts the user disabled, by Anthropic account UUID. */
+    readonly disabledAccountIdentities: readonly string[];
+    /** Route ids taken by imported API-key rows; a seeded route never takes one. */
+    readonly reservedRouteIds: readonly string[];
+}
+export interface NativeVaultRosterSeedRow {
+    routeId: string;
+    credentialId: string;
+    credentialType: 'oauth';
+    accountIdentity: string;
+    state: string;
+    label: string;
+    enabled: boolean;
+    addedAt: number;
+}
+export interface NativeVaultRosterSeedDecline {
+    credentialId: string;
+    accountIdentity: string;
+}
+/** Fresh secret-free roster, compatible with common-auth's readVaultRoster. */
+export interface NativeVaultRosterSeed {
+    version: 1;
+    view: string;
+    complete: true;
+    rows: NativeVaultRosterSeedRow[];
+    declined: NativeVaultRosterSeedDecline[];
+}
+/**
+ * Stored roster returned by common-auth's readVaultRoster. Account quota,
+ * email and organisation metadata do not participate in seed matching.
+ */
+export interface NativeVaultRosterDocument {
+    readonly version: 1;
+    readonly view?: string;
+    readonly complete: boolean;
+    readonly rejected?: readonly {
+        readonly credentialId?: string;
+        readonly reason: string;
+    }[];
+    readonly rows: readonly {
+        readonly routeId: string;
+        readonly credentialId: string;
+        readonly credentialType: 'oauth' | 'api_key';
+        readonly accountIdentity?: string;
+        readonly aliases?: readonly string[];
+        readonly state: string;
+        readonly label: string;
+        readonly email?: string;
+        readonly orgName?: string;
+        readonly enabled: boolean;
+        readonly addedAt: number;
+        readonly quota?: unknown;
+        readonly stale?: true;
+        readonly unclaimed?: true;
+    }[];
+    readonly declined: readonly {
+        readonly credentialId: string;
+        readonly accountIdentity?: string;
+    }[];
+}
+/**
+ * Build the first seed from the current verified vault list and the captured
+ * legacy state. The result is a complete roster the published reader accepts,
+ * built only from owned copies, so it shares no object with the input.
+ */
+export declare function buildNativeVaultRosterSeed(input: NativeRosterSeedInput): NativeVaultRosterSeed;
+/**
+ * Check a seed already on disk against the captured legacy state, so a resumed
+ * migration can keep it. Returns nothing: a valid seed is kept exactly as it
+ * is, with its original view and states. The current vault list must still
+ * pass every refusal, but a changed view or record state alone is not a
+ * conflict. Route, credential and account membership, labels, added times and
+ * enable/decline choices must match exactly; any difference refuses.
+ */
+export declare function validateNativeVaultRosterSeed(existing: NativeVaultRosterDocument, input: NativeRosterSeedInput): void;

package/dist/native-runtime-registry.d.ts

@@ -0,0 +1,19 @@
+import type { NativePoolPaths } from './pool-paths.ts';
+/** Compare injected transports and policy callbacks by object identity when selecting a shared runtime. */
+export declare function nativeRuntimeOptionIdentity(value: object | undefined): number | undefined;
+export declare function nativeRuntimeStorageKey(options: {
+    paths: NativePoolPaths;
+    host: 'opencode' | 'pi';
+    env?: NodeJS.ProcessEnv;
+}): string;
+export declare function nativeRuntimeConnectionFile(host: 'opencode' | 'pi', env: NodeJS.ProcessEnv): string;
+/** A release applies to the runtime entry acquired earlier, not to a later entry created with the same key. */
+export declare class NativeRuntimeRegistry<T extends {
+    close(): void;
+}> {
+    private readonly entries;
+    acquire(key: string, create: () => T): {
+        use: () => T;
+        close: () => void;
+    };
+}

package/dist/native-runtime.d.ts

@@ -0,0 +1,204 @@
+import type { AccountOperationError, OAuthAccountProfile, PrimeUsageCounters } from './accounts.ts';
+import { type NativeLocalCredentialValidation } from './native-credential-validation.ts';
+import { type NativeQuotaMap } from './native-quota-codec.ts';
+import type { NativeRefreshObservation, NativeRefreshSubject } from './native-refresh-coordinator.ts';
+import { type NativeLocalPoolBinding } from './pool-binding.ts';
+import type { NativePoolPaths } from './pool-paths.ts';
+/** Identifies the vault credential and Claude account that supplied an observation. This binding contains no access token. */
+export interface NativeCustodyRuntimeBinding {
+    kind: 'custody';
+    storageId: string;
+    routeId: string;
+    credentialId: string;
+    accountIdentity: string;
+    recordVersion: number;
+}
+export type NativeRuntimeBinding = NativeLocalPoolBinding | NativeCustodyRuntimeBinding;
+/**
+ * A failed account check is recorded against the exact credentials it used.
+ * This lets a retry delay apply only to those credentials, without treating
+ * the failure as evidence that the account check succeeded.
+ */
+export interface NativeLocalValidationRetry {
+    readonly subject: Pick<NativeLocalCredentialValidation, 'binding' | 'credentialFingerprint' | 'version'>;
+    readonly checkedAt: number;
+    readonly nextRetryAt: number;
+}
+/**
+ * Match refresh failures using fingerprintOf({ type: 'oauth', refresh }),
+ * the full refresh-credential fingerprint. The legacy tokenHash hashes the raw refresh token, and
+ * refreshTokenFingerprint is a short hash; neither is an alias for this value.
+ * Errors without the explicit full fingerprint preserve error-reset timestamps
+ * but cannot restrict a credential.
+ */
+export interface NativeLocalRefreshError extends AccountOperationError {
+    credentialFingerprint?: string;
+}
+/**
+ * Per-account retry errors, profiles, quota-priming usage and observation
+ * identifiers stored separately from credentials. Vault quota is stored here;
+ * local quota stays in the pool.
+ */
+export interface NativeRuntimeEntry {
+    binding: NativeRuntimeBinding;
+    credentialValidation?: NativeLocalCredentialValidation;
+    validationRetry?: NativeLocalValidationRetry;
+    lastUsed?: number;
+    lastRefreshedAt?: number;
+    lastRefreshError?: NativeLocalRefreshError;
+    refreshErrorClearedAt?: number;
+    refreshLeaseId?: string;
+    refreshLeaseUntil?: number;
+    refreshLeaseTokenHash?: string;
+    lastQuotaRefreshError?: AccountOperationError;
+    quotaErrorGeneration?: number;
+    quotaErrorClearedAt?: number;
+    quota?: NativeQuotaMap;
+    quotaCheckedAt?: number;
+    quotaToken?: string;
+    profile?: OAuthAccountProfile;
+    /** No supported writer supplies profileToken, so its value cannot safely be interpreted as an identifier. */
+    profileToken?: never;
+    prime?: PrimeUsageCounters;
+    authLineageId?: string;
+    primeAuthLineageRefreshTokenFingerprint?: string;
+}
+export interface NativeRuntimeState {
+    version: 1;
+    storageId: string;
+    accounts: Record<string, NativeRuntimeEntry>;
+    relay?: {
+        token: string;
+    };
+}
+export type NativeRuntimeRead = {
+    status: 'missing';
+} | {
+    status: 'ready';
+    state: NativeRuntimeState;
+};
+export declare class NativeRuntimeError extends Error {
+    readonly code: 'invalid-runtime' | 'unsafe-runtime' | 'runtime-io' | 'runtime-conflict' | 'publication-refused';
+    constructor(code: 'invalid-runtime' | 'unsafe-runtime' | 'runtime-io' | 'runtime-conflict' | 'publication-refused');
+}
+/** Validate structure and internal identifier consistency. The publisher separately checks these identifiers against the current pool or vault roster. */
+export declare function decodeNativeRuntime(value: unknown, storageId: string): NativeRuntimeState;
+export declare function readNativeRuntime(path: string, storageId: string): Promise<NativeRuntimeRead>;
+export interface NativeRuntimeWriteHooks {
+    /** Verify that the observed account still matches the current pool record or vault roster and that the caller still owns the locks protecting those records. */
+    beforeRename?: () => Promise<void>;
+    /** Check caller authority after every lease assertion, immediately before replacement. This hook can only refuse publication. */
+    beforePublish?: () => Promise<void>;
+    /** Runs after the new file replaces the old one. Failure does not undo that replacement. */
+    afterRename?: () => Promise<void>;
+}
+/** This writer alone uses `<leaf>.native-runtime.<UUID v4>.partial`. */
+export declare function isNativeRuntimeStagingName(path: string, name: string): boolean;
+/**
+ * This file has its own update lock. Account publishers also hold the locks
+ * protecting the pool and, for vault accounts, the roster. They verify those
+ * locks immediately before replacement. A process paused beyond a lock expiry
+ * can overlap a new owner even with normal renewal.
+ */
+export declare function updateNativeRuntime(path: string, storageId: string, change: (current: NativeRuntimeState) => NativeRuntimeState | Promise<NativeRuntimeState>, hooks?: NativeRuntimeWriteHooks): Promise<NativeRuntimeState>;
+/**
+ * Result of a write whose final check may withdraw it. `skipped` means the
+ * staged file was discarded and the runtime file was left as it was.
+ */
+export type NativeRuntimeOptionalPublication = {
+    status: 'published';
+    state: NativeRuntimeState;
+} | {
+    status: 'skipped';
+};
+export interface NativeRuntimeOptionalWriteHooks {
+    /**
+     * Same checks as NativeRuntimeWriteHooks.beforeRename, run at the same
+     * point. Resolve 'skip' to discard the staged write without an error; throw
+     * to refuse it exactly as a strict write would.
+     */
+    beforeRename: () => Promise<'publish' | 'skip'>;
+}
+/**
+ * For writes that only record information a newer observation makes
+ * redundant. The final check can withdraw such a write instead of failing it.
+ * The runtime lock is still asserted before a skip is reported, so a lost
+ * lock refuses the write either way.
+ */
+export declare function updateNativeRuntimeOptional(path: string, storageId: string, change: (current: NativeRuntimeState) => NativeRuntimeState | Promise<NativeRuntimeState>, hooks: NativeRuntimeOptionalWriteHooks): Promise<NativeRuntimeOptionalPublication>;
+/**
+ * Core-internal reconciliation of a successfully checked first local UUID.
+ * Matching a response to an account disabled after dispatch does not give that
+ * account permission to make another model request; admission checks still apply.
+ * No caller mutator or publication callback can widen this transition.
+ */
+export declare function publishNativeLocalFirstIdentity(paths: NativePoolPaths, observation: NativeRefreshObservation, hooks?: Pick<NativeRuntimeWriteHooks, 'beforePublish'>): Promise<NativeRuntimeState>;
+/**
+ * Record successful credential validation for a local account with a known UUID.
+ * Bootstrap must provide the state captured before its request and the exact
+ * credentials it checked. An unidentified entry requires first-identity publication.
+ * Recording validation for a disabled entry does not enable it or permit serving.
+ */
+export declare function publishNativeLocalCredentialValidation(paths: NativePoolPaths, observation: NativeRefreshObservation, hooks?: Pick<NativeRuntimeWriteHooks, 'beforePublish'>): Promise<NativeRuntimeState>;
+export interface NativeLocalFailurePolicy {
+    readonly checkedAt: number;
+    /** A nextRetryAt equal to checkedAt adds no delay beyond the recorded failure time. */
+    readonly nextRetryAt?: number;
+    readonly retryCount?: number;
+}
+export type NativeLocalFailureSkipReason = 'not-a-failure' | 'no-context' | 'not-attributable' | 'missing-committed';
+export type NativeLocalFailureAttribution = {
+    readonly kind: 'none';
+    readonly reason: NativeLocalFailureSkipReason;
+} | {
+    readonly kind: 'refresh-error';
+    readonly target: 'captured' | 'committed';
+    readonly subject: NativeRefreshSubject;
+    readonly permanent: boolean;
+    readonly message: 'Local refresh failed' | 'Local account-check recovery required';
+    readonly status?: number;
+} | {
+    readonly kind: 'validation-retry';
+    readonly target: 'captured' | 'committed';
+    readonly subject: NativeLocalValidationRetry['subject'];
+} | {
+    /**
+     * The exchange saved a successor whose access value is not a supported
+     * Claude OAuth credential. It is kept because the previous refresh token
+     * is consumed, but it is never validated or retried; only a new sign-in
+     * replaces it. Publishing it removes refresh-error and retry state no
+     * newer than its check, advancing the refresh-error clear marker to the
+     * check time when it removes any, and adds no error or backoff.
+     */
+    readonly kind: 'unsupported-successor';
+    readonly target: 'committed';
+    readonly subject: NativeRefreshSubject;
+};
+export type NativeLocalFailureSupersededReason = 'row-binding' | 'row-credential' | 'entry-binding' | 'reset-context' | 'already-proven' | 'older-than-stored';
+export type NativeLocalFailurePublication = {
+    readonly status: 'published';
+    readonly attribution: Exclude<NativeLocalFailureAttribution, {
+        kind: 'none';
+    }>;
+    readonly state: NativeRuntimeState;
+} | {
+    readonly status: 'skipped';
+    readonly reason: NativeLocalFailureSkipReason;
+} | {
+    readonly status: 'superseded';
+    readonly reason: NativeLocalFailureSupersededReason;
+};
+/**
+ * Classify the captured observation only. Saved credentials identify which
+ * account needs recovery, but do not prove a failed refresh or a completed
+ * account check. Refuse malformed action inputs rather than infer them from disk.
+ */
+export declare function classifyNativeLocalFailure(observation: NativeRefreshObservation): NativeLocalFailureAttribution;
+/**
+ * Bind recovery metadata to the exact credential version that produced it.
+ * An unsupported replacement token needs sign-in, not another refresh attempt:
+ * remove older retry restrictions so they do not hide that account state.
+ * This does not validate credentials or repair their account identity. Credentials
+ * are saved separately; a metadata write failure cannot undo a token exchange.
+ */
+export declare function publishNativeLocalRefreshFailure(paths: NativePoolPaths, observation: NativeRefreshObservation, policy: NativeLocalFailurePolicy, hooks?: Pick<NativeRuntimeWriteHooks, 'beforePublish'>): Promise<NativeLocalFailurePublication>;

package/dist/native-transient-account.d.ts

@@ -0,0 +1,38 @@
+import { type NativePoolStorePaths } from './pool-store.ts';
+/**
+ * A local account could not be authorized because another writer was part
+ * way through saving it (for example the refresh that records its first
+ * account UUID) and did not finish within the short wait Core allows.
+ *
+ * The request should be retried. `code: 'ECONNRESET'` is how this package
+ * marks an error retryable for its hosts. A host must surface it rather than
+ * route the request to a different account, because that account was not the
+ * one routing selected. The message is fixed and names no account.
+ */
+export declare class NativeTransientAccountError extends Error {
+    readonly code: 'ECONNRESET';
+    readonly syscall: 'native-account-update';
+    constructor();
+}
+/** True only for an error Core itself constructed as NativeTransientAccountError. */
+export declare function isNativeTransientAccountError(value: unknown): value is NativeTransientAccountError;
+/**
+ * Wait until no writer holds the pool's store locks, then let them go.
+ *
+ * Takes the config lock and then the state lock, in the order every pool
+ * writer takes them, and releases both (state first) as soon as both are
+ * held, without doing anything while holding them. A writer holds both locks
+ * across its state-file and config-file writes, so once both have been
+ * acquired the earlier write has finished. A writer can start again after
+ * release, so the caller rereads the pool and checks for another partially
+ * saved row.
+ *
+ * Returns 'deadline' when the locks could not be taken within the total
+ * budget. Each wait between attempts ends early when any of `signals`
+ * aborts; `check` is then called after the leases are released and is
+ * expected to throw the caller's cancellation error. `check` runs before
+ * every attempt too, so a cancelled caller never takes a lock. `now` must be
+ * the clock the pool's writers stamp their lock expiry with, or a live
+ * writer's lock could be judged expired and taken over.
+ */
+export declare function joinNativePoolWrite(paths: NativePoolStorePaths, signals: readonly AbortSignal[], check: () => void, now?: () => number): Promise<'joined' | 'deadline'>;