@cortexkit/common-auth 0.2.3 → 0.2.5

package/dist/cachekeep/window.js

@@ -0,0 +1,33 @@
+/**
+ * Reads a persisted `{ startHour, endHour }` pair. Anything other than two
+ * distinct whole hours in 0-23 is no window at all, which callers treat as
+ * "always warm".
+ */
+export function normalizeCacheKeepWindow(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    const startHour = Number(record.startHour);
+    const endHour = Number(record.endHour);
+    if (!Number.isInteger(startHour) ||
+        !Number.isInteger(endHour) ||
+        startHour < 0 ||
+        startHour > 23 ||
+        endHour < 0 ||
+        endHour > 23 ||
+        startHour === endHour) {
+        return undefined;
+    }
+    return { startHour, endHour };
+}
+/** Whether the local hour of `now` falls inside the window; no window is never inside. */
+export function isWithinCacheKeepWindow(window, now = new Date()) {
+    if (!window)
+        return false;
+    const hour = now.getHours();
+    if (window.startHour < window.endHour) {
+        return hour >= window.startHour && hour < window.endHour;
+    }
+    // Overnight wrap (e.g. 22-6): in window at or after the start, or before the end.
+    return hour >= window.startHour || hour < window.endHour;
+}

package/dist/claustrum/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/claustrum/index.js

@@ -0,0 +1,2 @@
+// Placeholder so the export resolves until this subpath is built.
+export {};

package/dist/commands/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/index.js

@@ -0,0 +1,2 @@
+// Placeholder so the export resolves until this subpath is built.
+export {};

package/dist/dump/index.d.ts

@@ -0,0 +1,90 @@
+export interface DumpLogger {
+    debug(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+}
+export interface DumpOptions {
+    /** Directory dumps are written to; a function is read on every dump. */
+    dir: string | (() => string);
+    /** Initial state; `setEnabled` switches it at runtime. Default off. */
+    enabled?: boolean;
+    /** Written into every filename. Default the current process id. */
+    pid?: number;
+    /** Clock for filenames and `createdAt`. Default `Date.now`. */
+    now?: () => number;
+    logger?: DumpLogger;
+    /**
+     * Key names redacted wherever they appear in headers, request metadata and
+     * the body, on top of the common credential set. Compared lower-cased with
+     * `-` and `_` removed, so `ChatGPT-Account-Id` and `chatgptAccountId` match
+     * `chatgptaccountid`.
+     */
+    secretKeys?: readonly string[];
+    /** Value patterns scrubbed from every string, on top of the common token patterns. */
+    secretPatterns?: readonly RegExp[];
+    /**
+     * Keys, at any depth of the body, whose values are declarations rather than
+     * data: their strings are scrubbed but their key names are never redacted.
+     * Default `['tools']`.
+     */
+    schemaKeys?: readonly string[];
+    /**
+     * Provider summary of the parsed body, stored in the metadata as `body`.
+     * It receives the redacted body.
+     */
+    summarize?: (body: Record<string, unknown>) => Record<string, unknown>;
+}
+export interface DumpInput {
+    /** The session the request belongs to; missing means `session-unknown`. */
+    session?: string | null;
+    /**
+     * Diff baseline group: a dump is diffed against the previous dump of the
+     * same session and channel (for example, one per transport).
+     */
+    channel: string;
+    /** Finer label for the filename, e.g. prewarm or main; it does not split the baseline. */
+    phase?: string;
+    bodyText: string;
+    accountId?: string;
+    url?: string;
+    method?: string;
+    headers?: ConstructorParameters<typeof Headers>[0];
+    status?: number;
+    error?: string;
+    /** Extra metadata, redacted like the body. */
+    meta?: Record<string, unknown>;
+}
+export interface DumpDiff {
+    changed: boolean;
+    firstByte: number;
+    lastPreviousByte: number;
+    lastCurrentByte: number;
+    changedPreviousBytes?: number;
+    changedCurrentBytes?: number;
+    previousBytes: number;
+    currentBytes: number;
+}
+export interface DumpResult {
+    id: string;
+    files: {
+        body: string;
+        metadata: string;
+        request: string;
+    };
+}
+export interface Dumper {
+    isEnabled(): boolean;
+    setEnabled(enabled: boolean): void;
+    /**
+     * Write `<id>.body.json`, `<id>.meta.json` and `<id>.request.json`. Returns
+     * undefined when dumps are off or the write failed; dumping is diagnostic
+     * and never throws into the request path.
+     */
+    dump(input: DumpInput): Promise<DumpResult | undefined>;
+}
+/**
+ * Where two bodies first and last differ, in string offsets into the dumped
+ * (redacted) text. Offsets count UTF-16 units, as the plugins' cache analysis
+ * always has.
+ */
+export declare function diffDumpBodies(previous: string | undefined, current: string): DumpDiff | null;
+export declare function createDumper(options: DumpOptions): Dumper;

package/dist/dump/index.js

@@ -0,0 +1,292 @@
+import { createHash } from 'node:crypto';
+import { chmod, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createRedactor } from '../logger/redact.js';
+const PREVIOUS_BODY_LIMIT = 100;
+const UNKNOWN_SESSION = 'session-unknown';
+function shortSession(session) {
+    return session.length <= 16 ? session : `${session.slice(0, 12)}…`;
+}
+function fileSegment(value, fallback) {
+    const normalized = value
+        .trim()
+        .replace(/[^a-zA-Z0-9._-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (!normalized)
+        return fallback;
+    return normalized.slice(0, 80);
+}
+function hashText(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function normalizeKey(key) {
+    return key.toLowerCase().replace(/[-_]/g, '');
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Where two bodies first and last differ, in string offsets into the dumped
+ * (redacted) text. Offsets count UTF-16 units, as the plugins' cache analysis
+ * always has.
+ */
+export function diffDumpBodies(previous, current) {
+    if (previous === undefined)
+        return null;
+    if (previous === current) {
+        return {
+            changed: false,
+            firstByte: -1,
+            lastPreviousByte: -1,
+            lastCurrentByte: -1,
+            previousBytes: previous.length,
+            currentBytes: current.length,
+        };
+    }
+    let firstByte = 0;
+    while (firstByte < previous.length &&
+        firstByte < current.length &&
+        previous[firstByte] === current[firstByte]) {
+        firstByte++;
+    }
+    let previousTail = previous.length - 1;
+    let currentTail = current.length - 1;
+    while (previousTail >= firstByte &&
+        currentTail >= firstByte &&
+        previous[previousTail] === current[currentTail]) {
+        previousTail--;
+        currentTail--;
+    }
+    return {
+        changed: true,
+        firstByte,
+        lastPreviousByte: previousTail,
+        lastCurrentByte: currentTail,
+        changedPreviousBytes: previousTail - firstByte + 1,
+        changedCurrentBytes: currentTail - firstByte + 1,
+        previousBytes: previous.length,
+        currentBytes: current.length,
+    };
+}
+export function createDumper(options) {
+    let enabled = options.enabled === true;
+    let counter = 0;
+    const pid = options.pid ?? process.pid;
+    const now = options.now ?? Date.now;
+    const log = options.logger;
+    const extraKeys = new Set((options.secretKeys ?? []).map(normalizeKey));
+    const redactor = createRedactor({
+        extraSecretKeys: (normalized) => extraKeys.has(normalized),
+        extraValuePatterns: [...(options.secretPatterns ?? [])],
+    });
+    const schemaKeys = new Set(options.schemaKeys ?? ['tools']);
+    /**
+     * Last dumped (redacted) body per baseline key, in memory for this process.
+     * A key missing here, on its first dump or after eviction, is looked up on
+     * disk.
+     */
+    const previousBodies = new Map();
+    const resolveDir = () => typeof options.dir === 'function' ? options.dir() : options.dir;
+    /** The mask for a secret key name, or undefined for an ordinary key. */
+    function maskFor(key) {
+        // The shared redactor masks a secret key whatever its value, so probing it
+        // with null answers "is this key a secret" without duplicating its rules.
+        const masked = redactor.redact({ [key]: null })[key];
+        return masked === null ? undefined : masked;
+    }
+    /**
+     * Redact by key name and scrub token-shaped strings, except below a schema
+     * key, where only strings are scrubbed: a tool parameter named `api_key`
+     * declares what the tool accepts, and masking that node would leave a
+     * schema that no longer parses. Key order is kept because dumps are diffed
+     * against each other.
+     */
+    function scrub(value) {
+        if (Array.isArray(value))
+            return value.map(scrub);
+        if (isRecord(value)) {
+            const out = {};
+            for (const [key, entry] of Object.entries(value)) {
+                const mask = maskFor(key);
+                if (schemaKeys.has(key))
+                    out[key] = redactor.redactStrings(entry);
+                else if (mask !== undefined)
+                    out[key] = mask;
+                else
+                    out[key] = scrub(entry);
+            }
+            return out;
+        }
+        return redactor.redactStrings(value);
+    }
+    function scrubBody(bodyText) {
+        let parsed;
+        try {
+            parsed = JSON.parse(bodyText);
+        }
+        catch {
+            // Not JSON: no keys to judge, but token-shaped strings still go.
+            return {
+                text: redactor.redactStrings(bodyText),
+                parsed: undefined,
+            };
+        }
+        const scrubbed = scrub(parsed);
+        const scrubbedText = JSON.stringify(scrubbed);
+        // Nothing redacted: keep the original bytes, whitespace included, so the
+        // dump is exactly what was sent.
+        const text = JSON.stringify(parsed) === scrubbedText ? bodyText : scrubbedText;
+        return { text, parsed: isRecord(scrubbed) ? scrubbed : undefined };
+    }
+    /**
+     * The newest earlier dump of this baseline key, read back from the dump
+     * directory. The in-memory baseline dies with the process, and the first
+     * request after a restart is the one most likely to break the prompt cache,
+     * so it is the one whose diff matters most. Reading the dumps themselves
+     * needs no extra state, and clearing the directory clears the baseline with
+     * it. Any failure is no baseline.
+     */
+    async function recoverBaseline(dir, session, channel, baselineKey) {
+        const marker = `-${fileSegment(session, UNKNOWN_SESSION)}-${fileSegment(channel, 'channel')}`;
+        let names;
+        try {
+            names = await readdir(dir);
+        }
+        catch {
+            return undefined;
+        }
+        // Names start with an ISO timestamp, so reverse lexicographic order is
+        // newest first. The metadata's key decides the match: a filename segment
+        // is truncated and sanitised, so two sessions can share one.
+        const candidates = names
+            .filter((name) => name.endsWith('.meta.json') && name.includes(marker))
+            .sort()
+            .reverse();
+        for (const name of candidates) {
+            try {
+                const metadata = JSON.parse(await readFile(join(dir, name), 'utf8'));
+                if (metadata?.baselineKey !== baselineKey)
+                    continue;
+                return await readFile(join(dir, name.replace(/\.meta\.json$/, '.body.json')), 'utf8');
+            }
+            catch {
+                // A file removed or half-written by another process: try the next.
+            }
+        }
+        return undefined;
+    }
+    function remember(key, text) {
+        if (!previousBodies.has(key)) {
+            while (previousBodies.size >= PREVIOUS_BODY_LIMIT) {
+                const oldest = previousBodies.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                previousBodies.delete(oldest);
+            }
+        }
+        previousBodies.set(key, text);
+    }
+    async function dump(input) {
+        if (!enabled)
+            return undefined;
+        counter++;
+        const session = input.session?.trim() || UNKNOWN_SESSION;
+        const dir = resolveDir();
+        const createdAt = new Date(now()).toISOString();
+        // The pid makes names unique across processes: each process starts its
+        // counter at zero, so two processes dumping the same session in the same
+        // millisecond into a shared directory would otherwise pick the same name.
+        const id = [
+            createdAt.replace(/[:.]/g, '-'),
+            String(pid),
+            String(counter).padStart(6, '0'),
+            fileSegment(session, UNKNOWN_SESSION),
+            fileSegment(input.channel, 'channel'),
+            ...(input.phase ? [fileSegment(input.phase, 'phase')] : []),
+        ].join('-');
+        const prefix = join(dir, id);
+        const files = {
+            body: `${prefix}.body.json`,
+            metadata: `${prefix}.meta.json`,
+            request: `${prefix}.request.json`,
+        };
+        // Hashed so the metadata identifies the baseline without spelling out the
+        // full session id.
+        const baselineKey = hashText(`${input.channel}\u0000${session}`);
+        try {
+            await mkdir(dir, { recursive: true, mode: 0o700 });
+            // mkdir's mode does not apply to a directory that already exists.
+            await chmod(dir, 0o700);
+            let previous = previousBodies.get(baselineKey);
+            let baselineSource = previous === undefined ? undefined : 'memory';
+            if (previous === undefined) {
+                previous = await recoverBaseline(dir, session, input.channel, baselineKey);
+                if (previous !== undefined)
+                    baselineSource = 'disk';
+            }
+            const body = scrubBody(input.bodyText);
+            const metadata = {
+                id,
+                createdAt,
+                pid,
+                session: shortSession(session),
+                channel: input.channel,
+                ...(input.phase ? { phase: input.phase } : {}),
+                accountId: input.accountId,
+                status: input.status,
+                error: input.error === undefined
+                    ? undefined
+                    : redactor.redactStrings(input.error),
+                baselineKey,
+                bodyBytes: Buffer.byteLength(input.bodyText, 'utf8'),
+                bodyHash: hashText(input.bodyText),
+                // Diffed on the redacted text that lands in the body file, so offsets
+                // index the file an operator can open, and a baseline read back from
+                // disk (also redacted) compares like with like.
+                diff: diffDumpBodies(previous, body.text),
+                baselineSource,
+                body: body.parsed
+                    ? { parseable: true, ...options.summarize?.(body.parsed) }
+                    : { parseable: false },
+                ...(input.meta ? { extra: scrub(input.meta) } : {}),
+                files,
+            };
+            const request = scrub({
+                url: input.url,
+                method: input.method,
+                accountId: input.accountId,
+                headers: input.headers === undefined
+                    ? undefined
+                    : Object.fromEntries(new Headers(input.headers).entries()),
+            });
+            // `wx`: a name collision fails loudly instead of overwriting a dump.
+            const write = (path, text) => writeFile(path, text, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+            await Promise.all([
+                write(files.body, body.text),
+                write(files.metadata, `${JSON.stringify(metadata, null, 2)}\n`),
+                write(files.request, `${JSON.stringify(request, null, 2)}\n`),
+            ]);
+            remember(baselineKey, body.text);
+            log?.debug('dumped request', {
+                id,
+                session: shortSession(session),
+                body: files.body,
+            });
+            return { id, files };
+        }
+        catch (error) {
+            log?.warn('request dump failed', {
+                session: shortSession(session),
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return undefined;
+        }
+    }
+    return {
+        isEnabled: () => enabled,
+        setEnabled: (value) => {
+            enabled = value;
+        },
+        dump,
+    };
+}

package/dist/opencode2/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/opencode2/index.js

@@ -0,0 +1,2 @@
+// Placeholder so the export resolves until this subpath is built.
+export {};

package/dist/store/errors.d.ts

@@ -1,6 +1,6 @@
 import type { StoredCredential } from './schema.js';
 /** Every library operation that can fail, as named in the failure value. */
-export type PoolOperation = 'initialize' | 'add' | 'replace' | 'rotate' | 'disable' | 'enable' | 'remove' | 'recordIdentity' | 'refresh' | 'pull';
+export type PoolOperation = 'initialize' | 'add' | 'replace' | 'rotate' | 'disable' | 'enable' | 'remove' | 'reorder' | 'recordIdentity' | 'refresh' | 'pull';
 /**
  * How far an operation got before it failed.
  *
@@ -16,7 +16,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' | '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' | '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/hooks.d.ts

@@ -9,4 +9,4 @@ export interface PoolLogger {
  * Runs a failure hook. A hook that throws never replaces the failure it was
  * handed: its exception is logged and discarded.
  */
-export declare function callFailureHook<E>(operation: PoolOperation, hook: ((rowId: string, error: E) => void | Promise<void>) | undefined, rowId: string, error: E, logger: PoolLogger | undefined): Promise<void>;
+export declare function callFailureHook<E, R extends string | undefined>(operation: PoolOperation, hook: ((rowId: R, error: E) => void | Promise<void>) | undefined, rowId: R, error: E, logger: PoolLogger | undefined): Promise<void>;

package/dist/store/index.d.ts

@@ -10,7 +10,7 @@ export type { PullHook, PullRequest } from './pull.js';
 export type { ProviderRefresh, ProviderRefreshResult, RefreshOptions, RefreshOutcome, } from './refresh.js';
 export type { LockEvent, PoolLockOptions, PoolLockSpec, } from './refresh-lock.js';
 export { POOL_LOCK_DEFAULTS } from './refresh-lock.js';
-export type { AddInput, AddResult, FailureHook, RemoveOptions, RemoveResult, RemoveView, RowOperationOptions, RowToggleOptions, } from './rows.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 { fingerprintOf, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, REFRESH_STAMP_TOLERANCE_MS, rowLockKey, } from './schema.js';

package/dist/store/mutate.d.ts

@@ -127,6 +127,7 @@ export declare function toFailure(error: unknown, operation: PoolOperation, rowI
  * The frame every lock-holding operation runs in: failures are mapped onto
  * the failure value, handed to the failure hook while the outer locks are
  * still held (the store locks are already released), and rethrown; every
- * lock is released afterwards.
+ * lock is released afterwards. `rowId` is undefined for an operation that
+ * names no row (`reorder`).
  */
-export declare function runOperation<T>(ctx: StoreContext, operation: PoolOperation, rowId: string, onFailure: ((rowId: string, error: PoolOperationError) => void | Promise<void>) | undefined, body: (locks: LockStack, progress: Progress) => Promise<T>): Promise<T>;
+export declare function runOperation<T, R extends string | undefined = string>(ctx: StoreContext, operation: PoolOperation, rowId: R, onFailure: ((rowId: R, error: PoolOperationError) => void | Promise<void>) | undefined, body: (locks: LockStack, progress: Progress) => Promise<T>): Promise<T>;

package/dist/store/mutate.js

@@ -335,7 +335,8 @@ export function toFailure(error, operation, rowId, progress) {
  * The frame every lock-holding operation runs in: failures are mapped onto
  * the failure value, handed to the failure hook while the outer locks are
  * still held (the store locks are already released), and rethrown; every
- * lock is released afterwards.
+ * lock is released afterwards. `rowId` is undefined for an operation that
+ * names no row (`reorder`).
  */
 export async function runOperation(ctx, operation, rowId, onFailure, body) {
     const locks = new LockStack(ctx.lockDefaults, ctx.lockEnv);

package/dist/store/pool.d.ts

@@ -5,7 +5,7 @@ import { type HoldPoint, type InitializeOutcome, type StoreContext } from './mut
 import { type PullHook } from './pull.js';
 import { type ProviderRefresh, type RefreshOptions, type RefreshOutcome } from './refresh.js';
 import { type LockEnvironment, type PoolLockOptions, type PoolLockSpec } from './refresh-lock.js';
-import { type AddInput, type AddResult, type RemoveOptions, type RemoveResult, type RowOperationOptions, type RowToggleOptions } from './rows.js';
+import { type AddInput, type AddResult, type RemoveOptions, type RemoveResult, type ReorderOptions, type ReorderResult, type RowOperationOptions, type RowToggleOptions } from './rows.js';
 import { type PoolCredential, type PoolRow, type QuotaCodec, type StoredCredential } from './schema.js';
 export interface OpenPoolStoreOptions {
     /** The provider every row of this pool belongs to; keys the provider-wide lock. */
@@ -101,6 +101,13 @@ export interface PoolStore {
      * (since 0.2.3). Locks as `disable`; `protect` can refuse the id.
      */
     remove(id: string, options?: RemoveOptions): Promise<RemoveResult>;
+    /**
+     * Sets the roster order (since 0.2.4) in one config write. `ids` must name
+     * every roster id exactly once; anything else refuses with `invalid-order`
+     * and writes nothing. Takes `extraLocks`, then the store locks; no row or
+     * provider-wide lock. Roster rows and their entries are left unchanged.
+     */
+    reorder(ids: readonly string[], options?: ReorderOptions): Promise<ReorderResult>;
     recordIdentity(id: string, identity: string, options?: RowOperationOptions): Promise<{
         id: string;
         disabled: string[];

package/dist/store/pool.js

@@ -3,7 +3,7 @@ import { initializePool, readPool, } from './mutate.js';
 import { PullScheduler } from './pull.js';
 import { refreshRow, } from './refresh.js';
 import { POOL_LOCK_DEFAULTS, } from './refresh-lock.js';
-import { addRow, disableRow, enableRow, recordRowIdentity, removeRow, replaceRow, rotateRow, } from './rows.js';
+import { addRow, disableRow, enableRow, recordRowIdentity, removeRow, reorderRows, replaceRow, rotateRow, } from './rows.js';
 import { POOL_SCHEMA_VERSION, } from './schema.js';
 /**
  * Process-wide memory per config file: ids whose per-row entry a library
@@ -94,6 +94,7 @@ export function openPoolStore(options) {
         disable: (id, reason, callOptions) => disableRow(rt, id, reason, callOptions),
         enable: (id, callOptions) => enableRow(rt, id, callOptions),
         remove: (id, callOptions) => removeRow(rt, id, callOptions),
+        reorder: (ids, callOptions) => reorderRows(rt, ids, callOptions),
         recordIdentity: (id, identity, callOptions) => recordRowIdentity(rt, id, identity, callOptions),
         refresh: (id, provider, callOptions) => refreshRow(rt, id, provider, callOptions),
         recordQuota: (id, attribution, observation) => recordQuota(rt, id, attribution, observation),

package/dist/store/rows.d.ts

@@ -1,4 +1,4 @@
-import type { PoolOperationError } from './errors.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';
@@ -57,6 +57,23 @@ export type RemoveResult = {
      */
     outcome: 'removed' | 'completed';
 };
+/**
+ * Options of `reorder`. It names no row, so its failure hook is handed only
+ * the failure; it takes no row lock and no provider-wide lock, so the extra
+ * locks are taken first, then the store locks.
+ */
+export interface ReorderOptions {
+    /** Called once, awaited, on every non-success path, before the extra locks release. */
+    onFailure?: (error: PoolOperationError) => void | Promise<void>;
+    /** Locks taken, in this order, before the store locks. */
+    extraLocks?: readonly PoolLockSpec[];
+}
+export type ReorderResult = {
+    /** The roster order now on disk. */
+    ids: string[];
+    /** `unchanged` when the roster was already in this order; nothing was written. */
+    outcome: 'reordered' | 'unchanged';
+};
 export interface AddInput {
     id: string;
     credential: PoolCredential;
@@ -119,6 +136,16 @@ export declare function enableRow(rt: StoreRuntime, id: string, options?: RowTog
  * not reused by `add` in this process.
  */
 export declare function removeRow(rt: StoreRuntime, id: string, options?: RemoveOptions): Promise<RemoveResult>;
+/**
+ * Sets the roster order in one config write. `ids` must name every roster id
+ * exactly once; anything else refuses (`invalid-order`) before writing. The
+ * roster rows, the per-row entries and the state file are left as they are:
+ * only the order of the legacy `accounts` array changes, which older readers
+ * load as is. It takes the extra locks, then the store locks, and no row or
+ * provider-wide lock, since no row's credential, identity or quota changes.
+ * 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<{
     id: string;
     disabled: string[];