@cortexkit/common-auth 0.2.9 → 0.4.0

package/dist/sidebar-file/sidebar-file.d.ts

@@ -3,7 +3,50 @@ export interface SidebarFileHooks {
     beforeRecheck?: () => void | Promise<void>;
     /** @internal Test seam after staging, before the ownership fence. */
     beforeCommit?: () => Promise<void>;
+    /** @internal Test seam after the rename, before ownership is checked again. */
+    afterRename?: () => Promise<void>;
 }
+/**
+ * Rebuild a write after the lock was lost while it was being renamed into
+ * place. `current` is the file as it is now, under a freshly taken lock: a
+ * successor may have written it after taking over the lease. `written` is the
+ * value this write committed. Return the value to write instead, typically
+ * the successor's state with only the fields this write is the authority on
+ * carried over, or undefined to leave the file as it is.
+ */
+export type SidebarRepair<T> = (current: T, written: T) => T | undefined;
+export interface SidebarWriteOptions<T> extends SidebarFileHooks {
+    /** Repair for this write; overrides the file's `repair` option. */
+    repair?: SidebarRepair<T>;
+    /**
+     * Told how this write ended, before its promise resolves. A callback
+     * rather than a resolved value, so `write` and `update` keep resolving to
+     * nothing for callers that pass them on as `Promise<void>`.
+     */
+    onResult?: (result: SidebarWriteResult) => void;
+}
+/**
+ * How a write ended.
+ *
+ * - `skipped`: the merge returned undefined, so nothing was written.
+ * - `written`: the value was renamed into place and the lock was still held
+ *   afterwards, so no other writer can have taken over during the rename.
+ * - `lost-after-rename`: the value was renamed into place, but by then the
+ *   lock had been taken over; the value may have replaced a successor's
+ *   state. `repair` says what was done about it: `none` (no repair was
+ *   supplied), `written` (the repaired value was committed and the lock held),
+ *   `skipped` (the repair returned undefined), `lock-unavailable` (the lock
+ *   could not be retaken in time) or `lost-again` (the repaired value was
+ *   committed but the lock was lost again; no further repair is tried).
+ */
+export type SidebarWriteResult = {
+    status: 'skipped';
+} | {
+    status: 'written';
+} | {
+    status: 'lost-after-rename';
+    repair: 'none' | 'written' | 'skipped' | 'lock-unavailable' | 'lost-again';
+};
 export interface SidebarFileOptions<T> {
     path: string;
     defaultValue: T;
@@ -20,11 +63,16 @@ export interface SidebarFileOptions<T> {
         warn: (message: string, payload?: unknown) => void;
         debug: (message: string, payload?: unknown) => void;
     };
+    /**
+     * Runs once, under a newly taken lock, when a write finds after its rename
+     * that the lock was lost. Without it such a write is only reported.
+     */
+    repair?: SidebarRepair<T>;
 }
 export interface SidebarFile<T> {
     read(): Promise<T>;
-    write(value: T, hooks?: SidebarFileHooks): Promise<void>;
-    update(merge: (latest: T) => T | undefined, hooks?: SidebarFileHooks): Promise<void>;
+    write(value: T, options?: SidebarWriteOptions<T>): Promise<void>;
+    update(merge: (latest: T) => T | undefined, options?: SidebarWriteOptions<T>): Promise<void>;
 }
 /** Binds generic persistence to a caller's path and normalization policy. */
 export declare function createSidebarFile<T>(options: SidebarFileOptions<T>): SidebarFile<T>;

package/dist/sidebar-file/sidebar-file.js

@@ -1,6 +1,6 @@
 import { chmod, mkdir, readFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
-import { WRITER_LOCK_CONSTANTS, withLock, writeJsonAtomic, } from '../fs/index.js';
+import { LockContentionError, LockOwnershipError, WRITER_LOCK_CONSTANTS, withLock, writeJsonAtomic, } from '../fs/index.js';
 /** Binds generic persistence to a caller's path and normalization policy. */
 export function createSidebarFile(options) {
     const { path, defaultValue, normalize } = options;
@@ -33,13 +33,79 @@ export function createSidebarFile(options) {
             return defaultValue;
         }
     };
-    const enqueue = (operation) => {
-        const result = chain.then(operation);
+    const enqueue = (operation, writeOptions) => {
+        const result = chain
+            .then(operation)
+            .then((outcome) => writeOptions?.onResult?.(outcome));
         // Keep the next operation runnable without hiding this caller's rejection.
         chain = result.catch(() => { });
         return result;
     };
-    const persist = async (merge, hooks) => {
+    const lockOptions = {
+        ...WRITER_LOCK_CONSTANTS.sidebar,
+        timeoutMs: options.timeoutMs ?? WRITER_LOCK_CONSTANTS.sidebar.timeoutMs,
+    };
+    /**
+     * Rename `value` into place under `lock`, then report whether the lock was
+     * still held. The fence before the rename stops a write whose lock is
+     * already gone; the check after it catches a lock lost while the rename
+     * itself was in flight, which no check before it can see.
+     */
+    const commitUnder = async (lock, value, hooks) => {
+        await writeJsonAtomic(path, value, {
+            serialize: JSON.stringify,
+            beforeRename: async () => {
+                await hooks?.beforeCommit?.();
+                await lock.assertOwned();
+            },
+        });
+        await hooks?.afterRename?.();
+        try {
+            await lock.assertOwned();
+            return true;
+        }
+        catch (error) {
+            if (error instanceof LockOwnershipError)
+                return false;
+            throw error;
+        }
+    };
+    /**
+     * One repair, under a new lock, of a write that lost its lock during the
+     * rename. Bounded to a single attempt: if the repair loses its lock too,
+     * the newer holder is writing and its state stands.
+     */
+    const repairLostWrite = async (repair, written, hooks) => {
+        options.logger?.warn('sidebar lock lost after rename; repairing write', {
+            path,
+        });
+        try {
+            const outcome = await withLock(path, lockOptions, async (lock) => {
+                const next = repair(await read(), written);
+                if (next === undefined)
+                    return 'skipped';
+                return (await commitUnder(lock, next, hooks))
+                    ? 'written'
+                    : 'lost-again';
+            });
+            if (outcome === 'lost-again') {
+                options.logger?.warn('sidebar repair lost its lock after rename', {
+                    path,
+                });
+            }
+            return { status: 'lost-after-rename', repair: outcome };
+        }
+        catch (error) {
+            if (!(error instanceof LockContentionError))
+                throw error;
+            options.logger?.warn('sidebar repair lock unavailable; repair skipped', {
+                path,
+            });
+            return { status: 'lost-after-rename', repair: 'lock-unavailable' };
+        }
+    };
+    const persist = async (merge, writeOptions) => {
+        const hooks = writeOptions;
         const parent = dirname(path);
         const secureDir = options.secureDir ?? true;
         await mkdir(parent, { recursive: true, mode: 0o700 });
@@ -48,38 +114,43 @@ export function createSidebarFile(options) {
                 options.logger?.warn('sidebar directory permission remediation failed', { error: error instanceof Error ? error.message : String(error) });
             });
         }
-        await withLock(path, {
-            ...WRITER_LOCK_CONSTANTS.sidebar,
-            timeoutMs: options.timeoutMs ?? WRITER_LOCK_CONSTANTS.sidebar.timeoutMs,
-        }, async (lock) => {
-            const commit = (value) => writeJsonAtomic(path, value, {
-                serialize: JSON.stringify,
-                beforeRename: async () => {
-                    await hooks?.beforeCommit?.();
-                    await lock.assertOwned();
-                },
+        const committed = await withLock(path, lockOptions, async (lock) => {
+            const commit = async (value) => ({
+                value,
+                held: await commitUnder(lock, value, hooks),
             });
             // Older processes may ignore the lock; remerge if their bytes changed.
             for (let attempt = 0; attempt < 3; attempt += 1) {
                 const raw = await readRaw();
                 const next = merge(parse(raw));
                 if (next === undefined)
-                    return;
+                    return undefined;
                 if (attempt === 0)
                     await hooks?.beforeRecheck?.();
                 if ((await readRaw()) !== raw)
                     continue;
-                await commit(next);
-                return;
+                return await commit(next);
             }
             const next = merge(await read());
-            if (next !== undefined)
-                await commit(next);
+            return next === undefined ? undefined : await commit(next);
         });
+        if (committed === undefined)
+            return { status: 'skipped' };
+        if (committed.held)
+            return { status: 'written' };
+        // The first lock is released by now; the repair takes its own.
+        const repair = writeOptions?.repair ?? options.repair;
+        if (!repair) {
+            options.logger?.warn('sidebar lock lost after rename; write not repaired', {
+                path,
+            });
+            return { status: 'lost-after-rename', repair: 'none' };
+        }
+        return await repairLostWrite(repair, committed.value, hooks);
     };
     return {
         read,
-        write: (value, hooks) => enqueue(() => persist(() => value, hooks)),
-        update: (merge, hooks) => enqueue(() => persist(merge, hooks)),
+        write: (value, writeOptions) => enqueue(() => persist(() => value, writeOptions), writeOptions),
+        update: (merge, writeOptions) => enqueue(() => persist(merge, writeOptions), writeOptions),
     };
 }

package/dist/store/attribution.js

@@ -18,8 +18,14 @@ export async function recordQuota(rt, id, attribution, observation) {
                 throw unknownRow('pull', id);
             if (row.invalid)
                 throw refusal('pull', id, 'invalid-row', `row ${id} is invalid`);
+            // A reading belongs to one (epoch, identity, credential). A row
+            // holding no credential, or torn between the writes of a replace,
+            // has no such triple on disk, so no reading is recorded for it.
+            if (!row.credential)
+                throw refusal('pull', id, 'no-credential', `row ${id} holds no credential`);
             const entry = tx.entry(id);
-            if (!entry ||
+            if (row.torn ||
+                !entry ||
                 entry.credentialEpoch !== attribution.credentialEpoch ||
                 row.identity !== attribution.identity)
                 throw new PoolOperationError({
@@ -35,7 +41,10 @@ export async function recordQuota(rt, id, attribution, observation) {
                 throw refusal('pull', id, 'invalid-quota', 'the quota codec rejected the merged map');
             tx.setEntry(id, { ...entry, quota: merged, needsFirstReading: false });
             await tx.commitConfig();
-        });
+        }, 
+        // Recording a reading never completes a torn row: the fence above
+        // refuses it, and the row's own next write completes it.
+        { completeTorn: false });
     }
     catch (error) {
         throw toFailure(error, 'pull', id, progress);

package/dist/store/errors.d.ts

@@ -7,8 +7,11 @@ export type PoolOperation = 'initialize' | 'add' | 'replace' | 'rotate' | 'disab
  * `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 row with no credential; replace: the bumped epoch beside the prior
- * credential; rotate: the rotated credential beside the old per-row entry). `pull`: a quota pull, or the recording of its result, failed.
+ * (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';
 /**
@@ -16,7 +19,7 @@ export type PoolFailurePhase = 'before-first-write' | 'after-first-write' | 'pul
  * lock outcomes (a wait that ran out, and a lease found lost); the rest are
  * refusals and failures of the operation itself.
  */
-export type PoolFailureKind = 'lock-contention' | 'lock-ownership' | 'pending-migration' | 'load-error' | 'unknown-row' | 'invalid-row' | 'invalid-input' | 'id-exists' | 'id-removed' | 'type-mismatch' | 'no-credential' | 'row-disabled' | 'row-protected' | 'duplicate-identity' | 'row-key-changed' | 'invalid-order' | 'refresh-stamp-ahead' | 'attribution' | 'provider' | 'pull' | 'invalid-quota' | 'after-persist-hook' | 'unexpected';
+export type PoolFailureKind = 'lock-contention' | 'lock-ownership' | 'pending-migration' | 'load-error' | 'unknown-row' | 'invalid-row' | 'invalid-input' | 'id-exists' | 'id-removed' | 'type-mismatch' | 'no-credential' | 'row-disabled' | 'row-protected' | 'duplicate-identity' | 'identity-mismatch' | 'row-key-changed' | 'invalid-order' | 'refresh-stamp-ahead' | 'attribution' | 'provider' | 'pull' | 'invalid-quota' | 'after-persist-hook' | 'unexpected';
 /**
  * The single failure value of every store operation. `committed` is present
  * only when the operation had already written a credential to the state file

package/dist/store/identity.d.ts

@@ -1,5 +1,14 @@
-import type { Transaction } from './mutate.js';
 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;
+}
 /** The reason recorded on a row disabled because an earlier row is the same account. */
 export declare const DUPLICATE_IDENTITY_REASON = "duplicate-identity";
 /**
@@ -12,12 +21,12 @@ export declare function countUnknownIdentityRows(rows: readonly PoolRow[]): numb
  * 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: Transaction, id: string, reason: string): void;
+export declare function disableIn(tx: RowEditor, id: string, reason: 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: Transaction, identity: string): string[];
+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: Transaction, id: string, identity: string): string[];
+export declare function recordIdentityIn(tx: RowEditor, id: string, identity: string): string[];

package/dist/store/mutate.d.ts

@@ -71,6 +71,11 @@ export declare class Transaction {
         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;
     roster(): unknown[];
@@ -85,6 +90,14 @@ export declare class Transaction {
     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 as
+     * that replace 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;
@@ -95,7 +108,9 @@ export declare class Transaction {
      * key untouched. Entries for ids no longer in the roster are dropped here,
      * and remembered so the id is not reused in this process.
      */
-    commitConfig(): Promise<void>;
+    commitConfig(options?: {
+        counted?: boolean;
+    }): Promise<void>;
     /** Writes the state: every unrecognised top-level and per-row key kept. */
     commitState(committed?: StoredCredential): Promise<void>;
     private write;
@@ -115,12 +130,17 @@ export type InitializeOutcome = 'initialized' | 'already-ready';
 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.
+ * 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>): Promise<T>;
+}, 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;
 /**

package/dist/store/mutate.js

@@ -4,7 +4,8 @@ import { LockContentionError, LockOwnershipError } from '../fs/with-lock.js';
 import { PoolOperationError, } from './errors.js';
 import { callFailureHook } from './hooks.js';
 import { LockStack, } from './refresh-lock.js';
-import { buildRows, classifyConfig, classifyState, isRecord, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, } from './schema.js';
+import { classifyConfig, classifyState, ensureEntries, entryIn, isRecord, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, rosterRowIn, setEntryIn, } from './schema.js';
+import { completeTornRows, loadRows } from './torn.js';
 async function readJson(path) {
     let text;
     try {
@@ -38,7 +39,7 @@ export async function readPool(ctx) {
         stateExists: state.exists,
         config: config.config,
         state: state.state,
-        rows: buildRows(config.config, state.state, ctx.codec),
+        rows: loadRows(config.config, state.state, ctx.codec),
     };
 }
 /** The refusal for a pool that is not ready, as a failure value. */
@@ -79,8 +80,13 @@ export class Transaction {
         this.config = structuredClone(snapshot.config);
         this.state = structuredClone(snapshot.state);
     }
+    /**
+     * 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() {
-        return buildRows(this.config, this.state, this.ctx.codec);
+        return loadRows(this.config, this.state, this.ctx.codec);
     }
     row(id) {
         return this.rows().find((row) => row.id === id);
@@ -92,7 +98,8 @@ export class Transaction {
     }
     /** The first roster row with this id (the one the pool loads). */
     rosterRow(id) {
-        return this.roster().find((raw) => isRecord(raw) && raw.id === id);
+        this.roster();
+        return rosterRowIn(this.config, id);
     }
     /**
      * Drops every roster row carrying this id. The row's per-row entry goes with
@@ -106,25 +113,28 @@ export class Transaction {
         return roster.length - kept.length;
     }
     entries() {
-        if (!isRecord(this.config[POOL_KEY]))
-            this.config[POOL_KEY] = {};
-        const pool = this.config[POOL_KEY];
-        if (!isRecord(pool[POOL_ROWS_KEY]))
-            pool[POOL_ROWS_KEY] = {};
-        return pool[POOL_ROWS_KEY];
+        return ensureEntries(this.config);
     }
     entry(id) {
-        const entries = this.entries();
-        const entry = Object.hasOwn(entries, id) ? entries[id] : undefined;
-        return isRecord(entry) ? entry : undefined;
+        this.entries();
+        return entryIn(this.config, id);
     }
     setEntry(id, entry) {
-        Object.defineProperty(this.entries(), id, {
-            value: entry,
-            enumerable: true,
-            writable: true,
-            configurable: true,
-        });
+        setEntryIn(this.config, id, entry);
+    }
+    /**
+     * Writes the config of every row torn between the writes of a replace as
+     * that replace 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`.
+     */
+    async completeTorn() {
+        const { config, torn } = completeTornRows(this.config, this.state, this.ctx.codec);
+        if (torn.length === 0)
+            return;
+        this.config = config;
+        await this.commitConfig({ counted: false });
     }
     stateAccount(id) {
         const accounts = isRecord(this.state.accounts) ? this.state.accounts : {};
@@ -152,7 +162,7 @@ export class Transaction {
      * key untouched. Entries for ids no longer in the roster are dropped here,
      * and remembered so the id is not reused in this process.
      */
-    async commitConfig() {
+    async commitConfig(options = {}) {
         const roster = this.roster();
         const rosterIds = new Set();
         for (const raw of roster)
@@ -184,7 +194,7 @@ export class Transaction {
                 [POOL_ROWS_KEY]: kept,
             },
         };
-        await this.write(this.ctx.configPath, next, 'config');
+        await this.write(this.ctx.configPath, next, 'config', options.counted ?? true);
         this.config = next;
     }
     /** Writes the state: every unrecognised top-level and per-row key kept. */
@@ -199,7 +209,7 @@ export class Transaction {
         if (committed)
             this.progress.committed = committed;
     }
-    async write(path, value, file) {
+    async write(path, value, file, counted = true) {
         await writeJsonAtomic(path, value, {
             beforeRename: async () => {
                 await this.ctx.onStep?.(`before-${file}-write`, this.info);
@@ -207,7 +217,8 @@ export class Transaction {
                 await this.locks.assertAll();
             },
         });
-        this.progress.writes++;
+        if (counted)
+            this.progress.writes++;
         await this.ctx.onStep?.(`after-${file}-write`, this.info);
     }
 }
@@ -258,9 +269,12 @@ export async function initializePool(ctx, dropKeys) {
 }
 /**
  * Runs `fn` under the store-lock list. The pool must be ready: a pending
- * migration or a load error refuses before anything is written.
+ * 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 async function withTransaction(ctx, locks, progress, info, fn) {
+export async function withTransaction(ctx, locks, progress, info, fn, options = {}) {
     const mark = locks.held.length;
     try {
         for (const spec of ctx.storeLocks)
@@ -268,7 +282,10 @@ export async function withTransaction(ctx, locks, progress, info, fn) {
         const result = await readPool(ctx);
         if (result.status !== 'ready')
             throw notReadyError(result, info.operation, info.rowId, progress.writes > 0 ? 'after-first-write' : 'before-first-write');
-        return await fn(new Transaction(ctx, result, locks, progress, info));
+        const tx = new Transaction(ctx, result, locks, progress, info);
+        if (options.completeTorn ?? true)
+            await tx.completeTorn();
+        return await fn(tx);
     }
     finally {
         await locks.releaseTo(mark);

package/dist/store/pool.d.ts

@@ -120,7 +120,14 @@ export interface PoolStore {
      * (`invalid-input`). Takes `extraLocks`, then the store locks.
      */
     updateSettings(mutator: SettingsMutator, options?: UpdateSettingsOptions): Promise<UpdateSettingsResult>;
-    recordIdentity(id: string, identity: string, options?: RowOperationOptions): Promise<{
+    /**
+     * 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[];
     }>;

package/dist/store/pool.js

@@ -77,8 +77,13 @@ export function openPoolStore(options) {
         async load() {
             const result = await readPool(ctx);
             if (result.status === 'ready') {
+                // A torn row is no candidate, but its pull is fired too: the pull
+                // completes the row on disk before reading it, so an interrupted
+                // replace of an OAuth row heals at the next load.
                 for (const row of result.rows)
-                    if (row.candidate && row.type === 'oauth' && row.needsFirstReading)
+                    if ((row.candidate || (row.torn && row.enabled)) &&
+                        row.type === 'oauth' &&
+                        row.needsFirstReading)
                         pulls.fire(row.id, 'load');
             }
             return toLoad(result);
@@ -98,7 +103,7 @@ export function openPoolStore(options) {
         reorder: (ids, callOptions) => reorderRows(rt, ids, callOptions),
         readSettings: () => readPoolSettings(rt),
         updateSettings: (mutator, callOptions) => updatePoolSettings(rt, mutator, callOptions),
-        recordIdentity: (id, identity, callOptions) => recordRowIdentity(rt, id, identity, callOptions),
+        recordIdentity: (id, identity, attribution, callOptions) => recordRowIdentity(rt, id, identity, attribution, callOptions),
         refresh: (id, provider, callOptions) => refreshRow(rt, id, provider, callOptions),
         recordQuota: (id, attribution, observation) => recordQuota(rt, id, attribution, observation),
         requestReading: (id) => pulls.fire(id, 'admission'),

package/dist/store/rows.d.ts

@@ -1,8 +1,9 @@
+import type { Attribution } from './attribution.js';
 import { PoolOperationError } from './errors.js';
 import { type Transaction } from './mutate.js';
 import type { PoolLockSpec } from './refresh-lock.js';
 import { type StoreRuntime } from './runtime.js';
-import { type PoolCredential, type PoolRow, type StoredCredential } from './schema.js';
+import { type CredentialBinding, type PoolCredential, type PoolRow, type StoredCredential } from './schema.js';
 export type FailureHook = (rowId: string, error: PoolOperationError) => void | Promise<void>;
 export interface RowOperationOptions {
     /** Called once, awaited, on every non-success path, before locks release. */
@@ -87,12 +88,15 @@ export type AddResult = {
     credential: StoredCredential;
 };
 /**
- * Writes a rotated credential into the state file (one write). A rotation is
- * the same lineage: no epoch bump, no identity or quota change.
+ * Writes a credential into the state file (one write), stamped with the
+ * credential epoch the row's entry holds in `tx` (1 without an entry) and,
+ * for a replace, the binding the config is about to get. A rotation is the
+ * same lineage: no epoch bump, no identity or quota change.
  */
 export declare function rotateIn(rt: StoreRuntime, tx: Transaction, id: string, credential: PoolCredential, extra?: {
     stamp?: number;
     clearErrors?: boolean;
+    binding?: CredentialBinding;
 }): Promise<StoredCredential>;
 export declare function addRow(rt: StoreRuntime, input: AddInput, options?: RowOperationOptions): Promise<AddResult>;
 export declare function replaceRow(rt: StoreRuntime, id: string, credential: PoolCredential, input?: {
@@ -146,7 +150,16 @@ export declare function removeRow(rt: StoreRuntime, id: string, options?: Remove
  * An order equal to the current one writes nothing.
  */
 export declare function reorderRows(rt: StoreRuntime, ids: readonly string[], options?: ReorderOptions): Promise<ReorderResult>;
-export declare function recordRowIdentity(rt: StoreRuntime, id: string, identity: string, options?: RowOperationOptions): Promise<{
+/**
+ * Records the wire identity an identity lookup found for a row's credential.
+ * `attribution` is the credential epoch the lookup was issued for (a row
+ * without an entry is at epoch 1): a lookup that completes after the row was
+ * replaced is refused (`attribution`), as a quota reading would be, so the
+ * first credential's account is never recorded on the second credential. A
+ * row already recorded for another account refuses (`identity-mismatch`):
+ * that is a replacement, not something learnt about the same credential.
+ */
+export declare function recordRowIdentity(rt: StoreRuntime, id: string, identity: string, attribution: Pick<Attribution, 'credentialEpoch'>, options?: RowOperationOptions): Promise<{
     id: string;
     disabled: string[];
 }>;