@cortexkit/common-auth 0.3.0 → 0.4.1

package/dist/routing/sticky.js

@@ -7,12 +7,6 @@ import { isPinValid } from './pins.js';
 export const QUOTA_STALENESS_MS = 15 * 60_000;
 export const MIN_RESET_HOURS = 1 / 60;
 export const MIN_WEIGHT = 1e-6;
-/**
- * How many window readings the selection primitives judge, as openai-auth's
- * primary and secondary slots did. The projection's first readings in its
- * order fill the slots; any further window is judged by admission only.
- */
-export const STICKY_WINDOW_SLOTS = 2;
 /** The projection's time, else the caller's cache-entry time. */
 export function snapshotCheckedAt(quota, entryCheckedAt) {
     for (const checkedAt of [quota?.checkedAt, entryCheckedAt]) {
@@ -22,10 +16,33 @@ export function snapshotCheckedAt(quota, entryCheckedAt) {
     }
     return undefined;
 }
-function slotReadings(quota) {
-    // Longest known window first, unknown lengths last, as openai-auth sorts.
-    // Tombstones and absence records carry no capacity figure, so they occupy
-    // no slot.
+/**
+ * The status rule used when the adapter supplies none, carried from
+ * openai-auth: 401 and 403 are permanent; no response, 0, a non-finite
+ * status, 429 and 5xx are transient; anything else leaves the row healthy.
+ * A provider whose 403 can mean an organisation or model policy rather than
+ * a dead account supplies its own classifier and can fall back to this one
+ * for the statuses it does not single out.
+ */
+export function defaultStickyStatusClass(status) {
+    if (status === 401 || status === 403)
+        return 'permanent';
+    if (status === undefined ||
+        status === 0 ||
+        !Number.isFinite(status) ||
+        (status >= 500 && status <= 599) ||
+        status === 429) {
+        return 'transient';
+    }
+    return 'healthy';
+}
+function windowReadings(quota) {
+    // Every reading is an independent constraint, so all of them are judged:
+    // a third window (for example a short window beside two weekly ones) can
+    // be the one that is nearly spent. Longest known window first, unknown
+    // lengths last, as openai-auth sorts, so a break decision with several
+    // spent windows names the longest. Tombstones and absence records carry no
+    // capacity figure and are left out.
     return quota.limits
         .filter((limit) => limit.kind === 'reading')
         .sort((left, right) => {
@@ -37,12 +54,12 @@ function slotReadings(quota) {
             return (right.windowMinutes ?? 0) - (left.windowMinutes ?? 0);
         }
         return 0;
-    })
-        .slice(0, STICKY_WINDOW_SLOTS);
+    });
 }
 /** Classifies whether a pinned session should leave its row after a failure. */
 export function decideStickyBreak(input) {
-    if (input.status === 401 || input.status === 403) {
+    const statusClass = (input.classifyStatus ?? defaultStickyStatusClass)(input.status);
+    if (statusClass === 'permanent') {
         return { action: 'migrate', reason: 'permanent' };
     }
     if (!input.quota)
@@ -58,7 +75,7 @@ export function decideStickyBreak(input) {
     if (input.killswitchPasses === false) {
         return { action: 'migrate', reason: 'killswitch' };
     }
-    for (const limit of slotReadings(input.quota)) {
+    for (const limit of windowReadings(input.quota)) {
         const remaining = limit.remainingPercent;
         if (typeof remaining === 'number' &&
             Number.isFinite(remaining) &&
@@ -83,14 +100,7 @@ export function decideStickyBreak(input) {
             resetsAt: budgetReset.resetsAt,
         };
     }
-    if (input.status === undefined ||
-        input.status === 0 ||
-        !Number.isFinite(input.status) ||
-        (input.status >= 500 && input.status <= 599) ||
-        input.status === 429) {
-        return { action: 'retain', reason: 'transient' };
-    }
-    return { action: 'retain', reason: 'healthy' };
+    return { action: 'retain', reason: statusClass };
 }
 export function sustainableWindowWeight(window, reservePercent, now) {
     const spendable = Math.max(0, window.remainingPercent - reservePercent);
@@ -124,7 +134,8 @@ function candidateWeight(candidate, now) {
     }
     // Missing reserve data must leave a window usable rather than silently
     // excluding its account.
-    const weights = slotReadings(candidate.quota).map((limit) => sustainableWindowWeight({
+    // The account is as constrained as its tightest window, whichever it is.
+    const weights = windowReadings(candidate.quota).map((limit) => sustainableWindowWeight({
         remainingPercent: limit.remainingPercent ?? Number.NaN,
         ...(limit.resetsAt === undefined ? {} : { resetsAt: limit.resetsAt }),
     }, candidate.reservePercent[limit.label] ?? 0, now));

package/dist/rpc/notifications.d.ts

@@ -22,7 +22,27 @@ export interface NotificationScope {
     rpcRoot: string;
     directoryPrefix: string;
     registrationSessionId: string;
+    /**
+     * Strict session isolation. When true, `pushNotification` and
+     * `drainNotifications` refuse an absent or empty session id (throwing
+     * `RpcSessionRequiredError`) and a drain returns only that session's own
+     * notifications: no notification reaches every session. A strict scope is
+     * a separate queue from the same scope without the flag, so a lenient
+     * caller cannot push into it or drain it.
+     *
+     * Off by default: without it, a drain with no session returns every
+     * session's notifications and a push with no session reaches every
+     * session, which plugins that drain from one process-wide TUI rely on.
+     */
+    requireSession?: boolean;
 }
+/** A strict notification scope was used without a session id. */
+export declare class RpcSessionRequiredError extends Error {
+    readonly operation: 'push' | 'drain';
+    constructor(operation: 'push' | 'drain');
+}
+/** True for a session id a strict scope accepts: a non-empty string. */
+export declare function isSessionId(value: unknown): value is string;
 export declare function pushNotification(scope: NotificationScope, payload: OpenDialogPayload, sessionId?: string): void;
 export declare function drainNotifications(scope: NotificationScope, lastReceivedId?: number, sessionId?: string): RpcNotification[];
 export declare function isTuiConnected(scope: NotificationScope, sessionId: string): boolean;

package/dist/rpc/notifications.js

@@ -1,9 +1,23 @@
+/** A strict notification scope was used without a session id. */
+export class RpcSessionRequiredError extends Error {
+    operation;
+    constructor(operation) {
+        super(`a ${operation} on a strict notification scope needs a session id`);
+        this.name = 'RpcSessionRequiredError';
+        this.operation = operation;
+    }
+}
+/** True for a session id a strict scope accepts: a non-empty string. */
+export function isSessionId(value) {
+    return typeof value === 'string' && value.length > 0;
+}
 const queues = new Map();
 function state(scope) {
     const key = JSON.stringify([
         scope.rpcRoot,
         scope.directoryPrefix,
         scope.registrationSessionId,
+        ...(scope.requireSession === true ? ['strict'] : []),
     ]);
     let value = queues.get(key);
     if (!value) {
@@ -15,6 +29,8 @@ function state(scope) {
 const QUEUE_CAP = 100;
 const TUI_CONNECTED_WINDOW_MS = 3_000;
 export function pushNotification(scope, payload, sessionId) {
+    if (scope.requireSession === true && !isSessionId(sessionId))
+        throw new RpcSessionRequiredError('push');
     const value = state(scope);
     value.queue.push({
         id: value.nextId++,
@@ -26,6 +42,11 @@ export function pushNotification(scope, payload, sessionId) {
         value.queue = value.queue.slice(-QUEUE_CAP);
 }
 export function drainNotifications(scope, lastReceivedId = 0, sessionId) {
+    // A strict queue holds only session-scoped notifications (its push refuses
+    // the rest), so the ordinary match below already gives a strict drain
+    // nothing but its own session's notifications.
+    if (scope.requireSession === true && !isSessionId(sessionId))
+        throw new RpcSessionRequiredError('drain');
     const value = state(scope);
     const now = Date.now();
     if (sessionId !== undefined)

package/dist/rpc/rpc-server.d.ts

@@ -1,5 +1,5 @@
 import type { RpcLogChannel } from './index.js';
-import type { ApplyRequest, ApplyResult, RpcNotification } from './notifications.js';
+import { type ApplyRequest, type ApplyResult, type RpcNotification } from './notifications.js';
 export interface RpcServerHandle {
     port: number;
     token: string;
@@ -13,6 +13,14 @@ export interface RpcServerOptions {
     sweepRoot?: string;
     drain: (lastReceivedId: number, sessionId?: string) => RpcNotification[];
     apply: (request: ApplyRequest) => Promise<ApplyResult>;
+    /**
+     * Refuse a `pending-notifications` drain whose `sessionId` is absent, not a
+     * string or empty, with 400 and without calling `drain`. Pair it with a
+     * strict notification scope (`requireSession`) so neither the wire nor
+     * the queue can hand one session's notifications to another. Off by
+     * default, when a session-less drain is passed to `drain` as undefined.
+     */
+    requireSession?: boolean;
     timeoutMs?: number;
     receiptTimeoutMs?: number;
 }

package/dist/rpc/rpc-server.js

@@ -2,6 +2,7 @@ import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { readFile, unlink } from 'node:fs/promises';
 import { createServer, } from 'node:http';
 import { join } from 'node:path';
+import { isSessionId, } from './notifications.js';
 import { sweepRpcState, writePortFile } from './port-file.js';
 function readBody(req) {
     return new Promise((resolve, reject) => {
@@ -64,6 +65,8 @@ export async function startRpcServer(options) {
             const body = await readBody(req);
             const params = JSON.parse(body || '{}');
             if (method === 'pending-notifications') {
+                if (options.requireSession === true && !isSessionId(params.sessionId))
+                    return json(400, { error: 'session required' });
                 const sessionId = typeof params.sessionId === 'string' ? params.sessionId : undefined;
                 if (sessionId === undefined && !warnedMissingNotificationSession) {
                     warnedMissingNotificationSession = true;
@@ -81,9 +84,13 @@ export async function startRpcServer(options) {
             return json(404, { error: 'unknown method' });
         }
         catch (error) {
-            json(500, {
+            // A handler's exception can quote a request or a credential, so its
+            // text goes to the plugin's log channel only; the wire gets a fixed code.
+            log.warn('rpc request failed', {
+                pid: process.pid,
                 error: error instanceof Error ? error.message : String(error),
             });
+            json(500, { error: 'internal error' });
         }
     }
     const port = await new Promise((resolve, reject) => {

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

@@ -1,2 +1,2 @@
-export type { SidebarFile, SidebarFileHooks, SidebarFileOptions, } from './sidebar-file.js';
+export type { SidebarFile, SidebarFileHooks, SidebarFileOptions, SidebarRepair, SidebarWriteOptions, SidebarWriteResult, } from './sidebar-file.js';
 export { createSidebarFile } from './sidebar-file.js';

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

@@ -2,6 +2,7 @@ import { PoolOperationError } from './errors.js';
 import { toFailure, withTransaction } from './mutate.js';
 import { LockStack } from './refresh-lock.js';
 import { refusal, unknownRow } from './runtime.js';
+import { isCredentialEpoch } from './schema.js';
 /**
  * Merges a quota observation into a row's stored map under the store locks,
  * after attribution passes. Needs no row lock, so it is permitted from
@@ -12,14 +13,22 @@ export async function recordQuota(rt, id, attribution, observation) {
     const locks = new LockStack(ctx.lockDefaults, ctx.lockEnv);
     const progress = { writes: 0 };
     try {
+        if (!isCredentialEpoch(attribution?.credentialEpoch))
+            throw refusal('pull', id, 'invalid-input', 'the credential epoch the reading was issued for must be a positive safe integer');
         await withTransaction(ctx, locks, progress, { operation: 'pull', rowId: id }, async (tx) => {
             const row = tx.row(id);
             if (!row)
                 throw unknownRow('pull', id);
             if (row.invalid)
                 throw refusal('pull', id, 'invalid-row', `row ${id} is invalid`);
+            // A reading belongs to one (epoch, identity, credential). A row
+            // holding no credential, or torn between the writes of a replace,
+            // has no such triple on disk, so no reading is recorded for it.
+            if (!row.credential)
+                throw refusal('pull', id, 'no-credential', `row ${id} holds no credential`);
             const entry = tx.entry(id);
-            if (!entry ||
+            if (row.torn ||
+                !entry ||
                 entry.credentialEpoch !== attribution.credentialEpoch ||
                 row.identity !== attribution.identity)
                 throw new PoolOperationError({
@@ -35,7 +44,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' | 'endpoint-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/index.d.ts

@@ -12,7 +12,7 @@ export type { LockEvent, PoolLockOptions, PoolLockSpec, } from './refresh-lock.j
 export { POOL_LOCK_DEFAULTS } from './refresh-lock.js';
 export type { AddInput, AddResult, FailureHook, RemoveOptions, RemoveResult, RemoveView, ReorderOptions, ReorderResult, RowOperationOptions, RowToggleOptions, } from './rows.js';
 export type { PullReason } from './runtime.js';
-export type { ApiKeyCredential, OAuthCredential, PoolCredential, PoolRow, QuotaCodec, StoredCredential, } from './schema.js';
+export type { ApiKeyCredential, OAuthCredential, PoolCredential, PoolRow, QuotaCodec, RotateCredential, StoredCredential, } from './schema.js';
 export { fingerprintOf, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, REFRESH_STAMP_TOLERANCE_MS, rowLockKey, } from './schema.js';
 export type { PoolSettings, SettingsMutator, SettingsRead, UpdateSettingsOptions, UpdateSettingsResult, } from './settings.js';
 export { POOL_OWNED_KEYS } from './settings.js';

package/dist/store/mutate.d.ts

@@ -64,13 +64,21 @@ export declare class Transaction {
     readonly snapshot: Snapshot;
     private readonly locks;
     private readonly progress;
-    private readonly info;
+    readonly info: {
+        operation: PoolOperation;
+        rowId: string | undefined;
+    };
     config: Record<string, unknown>;
     state: Record<string, unknown>;
     constructor(ctx: StoreContext, snapshot: Snapshot, locks: LockStack, progress: Progress, info: {
         operation: PoolOperation;
         rowId: string | undefined;
     });
+    /**
+     * The rows as every reader loads them: a row torn between the writes of a
+     * replace is shown as that replace leaves it once completed (see
+     * `PoolRow.torn`).
+     */
     rows(): PoolRow[];
     row(id: string): PoolRow | undefined;
     roster(): unknown[];
@@ -85,6 +93,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 +111,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 +133,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;
 /**